Reference · Dashboard

The local dashboard

agentmako ships an optional local web dashboard — a Vite + React app that talks to the same HTTP API the MCP server uses. Browse projects, run tools, inspect Reef state, and chat with the harness in a browser tab. It's local-only: no hosted service, no auth tokens, no remote access.

When to use it

The dashboard isn't required — the MCP server and CLI cover most workflows. Reach for it when:

  • You want a visual view of Reef state — findings, facts, freshness — without paging through CLI output.
  • You're onboarding to a new project and want to skim its symbols/routes/schema in one place.
  • You're debugging a tool and want to call it with a UI form instead of crafting JSON.
  • You want a chat interface with full tool-call timelines, artifact rendering, and approval modals — without integrating an external agent harness.

If you're already happy in Claude Code / Cursor / Codex, you can ignore the dashboard entirely. It's a complement, not a replacement.

Running the dashboard

Two pieces need to be up: the local HTTP API server, and the Vite dev/build output the dashboard is served from.

The bundled command

From any attached project:

agentmako dashboard

Under the hood this:

  1. Starts the local HTTP API service (agentmako serve) on a free port.
  2. Serves the dashboard's pre-built static bundle from the same port.
  3. Opens your default browser at http://127.0.0.1:<port>.

Common flags:

  • --port 4830 — pin the API + dashboard to a specific port.
  • --no-open — skip the browser launch (useful in CI / remote shells).
  • --project PATH — start with a specific project selected.

API only (no UI)

If you just want the HTTP API for scripting:

agentmako serve --port 4830

Then GET http://127.0.0.1:4830/api/v1/health to check it's up. The dashboard is just one HTTP client of this API.

Tour of the dashboard

The sidebar lists every page; here's what each is for.

Home

Project picker plus a per-project status card — freshness counts, recent activity, attached database, configured provider. The fastest way to confirm "I'm pointed at the right project."

Agent

A chat interface. Same backend the CLI chat command uses, but with full tool-call cards (read/mutation badge, structured input/output), workflow packet rendering, and an approval modal for permission-gated actions. Sessions persist; Resume picks up where you left off.

Tools

Browse the full tool registry by category. Each tool has a form derived from its input schema — fill in arguments, click run, see the response rendered with syntax highlighting. A fast way to learn a tool without writing JSON by hand.

Search

Run cross_search / live_text_search from a UI with result grouping (code chunks, schema, RPCs, routes, memories). Click a result to jump to the file or subject.

Memory

The harness's user-curated memory store — separate from Reef facts/findings. Add notes, recall by tag, list across projects.

Providers

Add/remove model providers (Anthropic, OpenAI, Ollama, LM Studio, etc.), test connections, manage keychain entries. Same surface as the providers CLI commands but with a real form.

Session

Drill into a single chat session. Full message timeline, tool-call cards, edited messages, copy/edit affordances. The place to retrace what an agent actually did.

Artifacts

Browse files the harness produced or referenced — diffs, generated code, attached screenshots. Each artifact links back to the session that created it.

Usage

Per-provider token and call counts. Filter by project or time range.

Health

What agentmako doctor shows, but as a live status page. Refreshes on a timer; useful to leave open in a background tab.

Local-only by design

The dashboard is a local web client. It does not:

  • Bind to anything other than 127.0.0.1.
  • Talk to a hosted Mako service (there isn't one).
  • Sync sessions, findings, or artifacts anywhere.
  • Ship auth tokens — there are none.

If you want to expose it to teammates, you need to put your own auth + reverse proxy in front of the API port and accept the consequences. The default posture is single-machine.

Privacy

Everything you see in the dashboard comes from the local Reef store and (optionally) the model provider you configured. agentmako has no telemetry. The dashboard itself loads no third-party scripts.

The HTTP API the dashboard uses

The dashboard is a thin client over the agentmako HTTP API. You can call the same endpoints from any HTTP client — useful for CI scripts, integrations, or building your own UI.

Common endpoints:

  • GET /api/v1/health — service health
  • GET /api/v1/projects — list attached projects
  • POST /api/v1/projects/attach — attach a project
  • GET /api/v1/projects/:id/status — project freshness + counts
  • GET /api/v1/tools — list registered tools (same surface as the MCP tools/list)
  • POST /api/v1/tools/:name/call — invoke a tool with JSON args

Full schema lives in the @mako-ai/contracts workspace package; the dashboard's api-types.ts is the canonical TypeScript binding.

Hacking on the dashboard

If you want to modify the dashboard itself, clone the public repo and use the Vite dev workflow:

git clone https://github.com/drhalto/agentmako
cd agentmako
pnpm install

# terminal 1: local API
pnpm --filter @mako-ai/api dev

# terminal 2: dashboard with HMR
pnpm --filter @mako-ai/web dev

The Vite dev server proxies API calls to the local API service, so you get hot reload on dashboard changes without rebuilding the API. Stack: React 19, react-router 7, TanStack Query, Tailwind v4, Shiki for code highlighting, Sonner for toasts.

What the dashboard is not

  • Not a replacement for your IDE. It doesn't edit code. Use it to inspect, query, and chat — then edit in your editor.
  • Not the only entry point. Every action the dashboard offers is also a CLI command and an MCP tool. The dashboard is convenience UI, not authoritative state.
  • Not multi-user. No accounts, no sharing. If two devs need to see the same Reef state, commit .mako-ai/ or use the API directly.

Common pitfalls

  • Port conflicts. The dashboard picks a free port by default. If your dev environment has strict port allocations, pin one with --port.
  • "Connection refused" when the dashboard opens. The API service crashed or hasn't finished starting. Refresh the browser, or check agentmako doctor in another terminal.
  • Stale dashboard after upgrade. The dashboard is a static bundle compiled into the CLI binary. After npm install -g agentmako upgrades, hard- reload (Cmd/Ctrl+Shift+R) to clear cached JS.
  • Browser blocking localhost requests. Some corporate browser extensions or Safari privacy modes block 127.0.0.1 requests. Try a clean Chrome / Firefox profile or whitelist the loopback address.