agentboard
tintin9999/agentboard
agentboard — a local-first kanban + orchestration tool for AI coding agents (Claude Code, Codex, Cursor)
Instalação
npx convez-ai tintin9999/agentboard1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
agentboard
Local multi-project kanban + orchestration for AI coding agents (Claude Code, Codex, Cursor) — one board, one database, every agent talks to it over MCP.
Requires Node ≥ 22.13 (uses built-in node:sqlite — zero native dependencies).
Install
cd agentboard
npm install # installs root + ui deps
npm run ui:build # build the web UI once
npm link # optional: makes `board` available globally
Everything (db, docs, worktrees, logs, config) lives in ~/.agentboard/ (override with AGENTBOARD_DATA).
1. Add your projects
board project add "MyApp" ~/code/myapp
board project add "Side Project" ~/code/sideproj -s sideproj -b main
2. Register the MCP server in your agents
board mcp-config # prints the JSON
- Claude Code:
claude mcp add agentboard -- <tsx-path> <repo>/src/mcp/server.ts(or paste into.mcp.json) - Cursor: paste into
~/.cursor/mcp.json - Codex: add to
~/.codex/config.tomlunder[mcp_servers.agentboard]
Now any agent can list/create/claim cards, post progress events, attach docs, and request review — from inside any conversation.
3. Daily flow
board serve # web UI at http://localhost:4848
board intake myapp complaints.md # preview cards from a notes doc
board intake myapp complaints.md -y # create them
board list myapp -s ready
board ready 12 # move card 12 to ready
board run myapp # run all ready claude/codex cards in parallel worktrees
board group 12 15 # related cards → one runner, one shared branch
board run-group myapp 12 15 # run a group right now
board show 12 # timeline, docs, branch
board done 12 && board prune myapp # after you merge the branch
Intake markers in your doc: [me|cursor|claude|codex], [p0]–[p4], [simple|complex], #tag. Use ## headings or - bullets.
How a run works
For each ready card assigned to claude/codex:
- Creates
~/.agentboard/worktrees/<project>/card-Non branchagent/card-N-<slug>(off the project's default branch) - Spawns
claude -p/codex execheadless in that worktree, model picked from card complexity (see~/.agentboard/config.json) - The agent works a phased pipeline: scout (read the code + project docs first) → clarify (hard bar: never implement on an assumption) → solutions (2–3 candidate approaches with tradeoffs + a recommendation)
- By default that first pass is a review gate: it posts
APPROVAL NEEDED:(the options comparison) orCLARIFICATION NEEDED:(decision-grade questions with safe defaults), moves the card toneeds_clarification(shown in In progress with a highlighted border), and stops - You answer/approve in the card drawer (
Approve + runwrites anAPPROVED:event), then the next run implements the chosen option, posts progress/blockers (BLOCKED:), writes/updates test files, does a mandatory self-review of the whole branch diff (posts aSELF-REVIEW:event with findings + fixes), attaches atest-plandoc, and callsrequest_review - You review the branch, merge, mark done,
board prune
Cards assigned to me or cursor are interactive work — they never run headless.
Group runs — related cards, one runner
When several cards are really one topic, run them as one unit: a single agent in a single shared worktree on branch agent/group-<key>-<slug> — one scouting pass (fewer tokens), one coherent change-set, zero rebase/merge pain between sibling branches.
- The board auto-suggests groups: a banner appears when ready/backlog agent cards look like the same topic (shared tags + title/body overlap) — Group, Group + run, or dismiss
board group 12 15/board ungroup 15/board run-group myapp 12 15from the CLI;POST /api/projects/:slug/run-groupfrom anywhere else- Grouped cards show a ⧉ badge; the drawer shows the members and runs/approves the whole group as one (one approval covers the group, agents still keep per-card timelines and request review per card)
board runtreats a grouped set as one unit of concurrency
Runs also start from the web UI: a Run button in the card drawer, and Run ready (N) in the header for everything ready in the project. The header shows a live "N running" indicator and running cards get a badge — each run writes a card-N-<ts>.meta.json beside its prompt/transcript, so runs are visible no matter whether the CLI or the UI started them. A card with an active run can't be started twice.
Learning loop
Check "Require a learning explainer doc" on a card (or board add ... --explainer): the agent must attach an explainer doc — what was weak, the pattern behind the fix, what a senior dev watches for, what to verify manually. Read it next to the diff at review time. Also create periodic architecture cards ("explain X subsystem, propose improvements") — docs accumulate per project under ~/.agentboard/docs/.
Docs are the board's collective memory, so they're many-to-many: one architecture doc can feed any number of cards. The card drawer suggests relevant project docs (keyword relevance against the card's title/body/tags) — one click links a doc, and every linked doc is injected into that card's generated agent prompt. Agents can do the same via the attach_doc MCP tool, and are told to check list_docs/get_doc while scouting.
Config
~/.agentboard/config.json: model-per-complexity per agent, max concurrency, extra CLI args, prompt addenda, approval-gate toggle, port. Editable from the web UI (header → Settings), which writes the same file. Models are picked from modelChoices (per agent) — extend that list in Settings or config.json and the dropdowns follow. Per-card model overrides and agent prompt notes live on the card itself.
Codex headless runs default to approval_policy="never" and danger-full-access. Codex CLI 0.137 cancels stdio MCP writes under workspace-write, so the runner uses the same fully automated mode you would use for trusted local orchestration.
Always-on serving
Only the web UI/API (board serve) needs to stay running. board mcp is a stdio server: every agent client spawns its own instance on demand — there is nothing to keep alive. The runner must stay on the host too: it spawns the real claude/codex CLIs against your repos with your credentials.
Docker (serves the UI/API against your existing data):
docker compose up -d --build # → http://localhost:4848
~/.agentboard is bind-mounted to /data. Host (CLI/MCP/runner) and container then write the same SQLite file across the mount boundary; that's fine for a localhost board, but if you ever hit SQLITE_BUSY/lock errors, switch to the native option below.
launchd (macOS, no Docker, no shared-mount caveat): see the install one-liner inside deploy/com.agentboard.serve.plist. It keeps board serve alive across reboots and logs to ~/.agentboard/logs/serve.log.
Layout
src/db node:sqlite schema (projects, cards, events, docs)
src/core store + agent prompt builder
src/mcp MCP stdio server (14 tools)
src/api Hono REST API + serves ui/dist
src/cli `board` command
src/runner worktrees + headless claude/codex spawning
src/intake complaints.md → cards parser
ui/ React kanban (Vite)
Notes
npm testruns the node:test suite (similarity scoring, group/doc-link store logic, run-meta scanning).- "Iterations" are gone on purpose: state lives in the DB, archive = status. Filter done cards by date when you want a retrospective.
- Statuses: backlog → ready → in_progress → needs_clarification → review → done (archived hidden).
- The runner is a safety net: if an agent exits without calling
request_review, the card still moves to review (exit 0) or back to ready (non-zero), with the log path in the timeline.