Use your own local agent
If Claude Code or Codex is already installed and signed in on your machine, the Advisor can drive that agent directly to answer board questions — no API key, no model to configure, no separate LLM bill. Board data still leaves your machine: it goes to whichever cloud model that agent is signed in to (Anthropic for Claude Code, OpenAI for Codex), the same as any other conversation with that agent. This is automatic detection of a coding agent already on your machine, distinct from the manual provider you set up on the providers page.
pnpm deckgauge:advisor to use your local Claude CodeConnected, versus the bridge not running.
What it does, and where the data comes from
pnpm deckgauge:advisor starts the advisor bridge — a small host-side process, not a container, since it needs your own already-authenticated agent login. It detects whichever supported agent's ACP adapter is installed (Claude Code or Codex), spawns it, and opens an Agent Client Protocol session declaring Deckgauge's MCP server as that session's tool source, then listens on 127.0.0.1 only — never exposed as a network service.
Sign in to Deckgauge and open a board's Advisor panel, and the panel sends your own session's access token to the bridge automatically — no separate login step for the bridge itself. That handshake completing flips the panel to "Connected to your local {agent} — ready", and every question routes to your local agent instead of the panel's provider-backed flow from then on. If the bridge isn't running, isn't reachable, or has nothing to authenticate it, the panel falls back to the configured provider automatically and shows a hint to start the bridge instead.
How to run it
- Install and sign in to Claude Code or Codex on your machine, exactly as you would for any other project.
- Run
pnpm deckgauge:advisor— starts the bridge in the foreground. (It also starts automatically alongsidepnpm dev.) - Sign in to Deckgauge and open a board's Advisor panel — this is what authenticates the bridge and flips the panel to "Connected".
Security posture
Worth reading closely before you rely on this:
- Board data access adds no new path — but it does leave your machine. The agent reaches Deckgauge only through the same read-only MCP tools an external MCP client gets (see MCP integration). Every tool call re-checks the calling token's board access (Viewer minimum) and builds the board's data scope on the server — never something the agent or bridge can supply as input. Nothing behind those tools writes to Postgres, Jira, GitHub, Azure DevOps, or GitLab. That covers write access and how Deckgauge is reached; it says nothing about where the data ends up next — whatever a tool call returns is sent on to the agent's own cloud model as part of its normal conversation, same as pasting that data into Claude Code or Codex yourself.
- Destructive tool calls are auto-denied, not left to a missing prompt. Running headlessly, the bridge answers every ACP permission request itself — there's no interactive terminal to ask "may I run this?". It auto-approves non-destructive calls (read/fetch, including the Deckgauge tool calls) so the agent can gather evidence, and it denies every destructive tool call it is asked to approve — the kinds
edit,delete,move, andexecute, i.e. local file writes, deletes, moves, or shell execution. Know the two edges of that gate before you rely on it: it only fires when the agent asks for permission at all, and a tool call that arrives with an unrecognised or absent kind falls through to the approve branch. It's a checkpoint on unattended local mutation, not a sandbox around your agent. - Run it only on a machine you trust with your own session. The token authenticating your agent's tool calls is passed to the MCP-proxying subprocess as a command-line argument, so any other user on the same host can read it via a process listing. On the default browser-authenticated path, that token is your live Deckgauge session token — treat this bridge like any other locally-run developer tool: fine on your own laptop, not a shared or multi-user box.
If it looks wrong
| Symptom | Cause | Fix |
|---|---|---|
| "No local agent found. Install and sign in to Claude Code (or Codex) and try again." | Neither agent's ACP adapter is on your machine | Install and sign in to one, then rerun pnpm deckgauge:advisor |
| The bridge's terminal shows it detected an agent, but the panel never reaches "Connected" | Nothing has authenticated the bridge yet | Make sure you're signed in to Deckgauge in the tab with the panel open |
| Tool calls come back unauthorized, or answers are empty | Your user lacks Viewer access on this board | Ask a board owner for access — access is re-checked per board, per call |
Panel shows the "Run pnpm deckgauge:advisor…" hint instead of "Connected" | The bridge isn't running, or the connection attempt timed out | Start the bridge and reopen the panel — it fell back automatically, so you're never blocked meanwhile |
Related
- Ask the Advisor — the panel this bridge connects to, and what it looks like once you're connected.
- Configuring an LLM provider — the fallback the panel uses when this bridge isn't running.
- MCP integration — the same read-only tools, exposed to any external MCP client.
Last updated