DocsCLI

Open documentation actions
View MarkdownOpen on GitHub

Devtools

Open a live panel for a generated project, expose the same lifecycle operations to coding agents over HTTP, or bake a static report.

devtools starts a local server for one Better Fullstack project. It serves a browser panel, the lifecycle operations over RPC, and an MCP endpoint that coding agents discover without any per-agent setup. Every operation is the same one the CLI and the stdio MCP server use, so the panel never claims more than status, check, update, or doctor would.

bash
npx create-better-fullstack@latest devtools --project-dir ./my-app --open
FlagBehavior
--project-dir <path>Project to serve; defaults to the current directory.
--port <number>Port to listen on; defaults to a free port.
--host <name>Bind host; defaults to localhost. Keep it there unless you understand the trust model.
--openOpen the panel in a browser with a magic link that skips the code prompt.
--report <dir>Write a static report to <dir> and exit. The panel renders it without a running server.

The panel

The panel has five tabs.

  • Overview shows the project report: health, stack graph, lifecycle baseline, provenance, recovery eligibility, the update window, and template drift counts.
  • Checks runs the generated targets, the same as check. Build tools may write their normal caches and output.
  • Update plans a template update and a config repair. Apply is only enabled when the plan issued a review token, and it writes inside a recoverable transaction exactly like update --apply and doctor --fix.
  • Recovery lists recovery points, verifies them, restores one, and previews or applies pruning with the same review token the MCP tool requires.
  • Evidence shows the project context: roles, capabilities, their evidence level, compatibility issues, and safe next actions.

Every view keeps the raw payload one click away, so what an agent sees over MCP and what you see in the panel is the same document.

Authorization

The server trusts a browser only after a one-time code. Without --open, the panel asks the server to print a six digit code in the terminal; enter it once and that browser stays trusted. The server binds to localhost and never trusts a request that arrives from another machine.

Agents

While devtools runs, its MCP endpoint is listed in the Devframe instance registry. Agents that have the devframe gateway configured find it automatically:

json
{
  "mcpServers": {
    "devframe": { "command": "npx", "args": ["devframe", "connect"] }
  }
}

The gateway lists running devtools and forwards calls to the same bfs_* tools the stdio server advertises, with identical input and output schemas. The route rejects browser requests from other origins and non-loopback peers by design; a direct HTTP MCP client must send a loopback Origin header.

Static report

bash
npx create-better-fullstack@latest devtools --project-dir ./my-app --report ./devtools-report

The report contains the panel plus the project reads (status, context, history, recovery points, evidence), baked at build time. Plans are left out because they carry review tokens and proposed file contents. Serve the directory from any static host. Actions that need a live server, such as planning, running checks, or applying an update, are disabled in a report.

--report replaces the target directory, so it only accepts a new directory, an empty one, or a previous report.

GitHub Sponsors