convez.ai
Agente
tintin9999

agentboard

tintin9999/agentboard

Ver no GitHub
InicialPluginScore · de 0 a 100

agentboard — a local-first kanban + orchestration tool for AI coding agents (Claude Code, Codex, Cursor)

Instalação

$npx convez-ai tintin9999/agentboard

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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.toml under [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:

  1. Creates ~/.agentboard/worktrees/<project>/card-N on branch agent/card-N-<slug> (off the project's default branch)
  2. Spawns claude -p / codex exec headless in that worktree, model picked from card complexity (see ~/.agentboard/config.json)
  3. 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)
  4. By default that first pass is a review gate: it posts APPROVAL NEEDED: (the options comparison) or CLARIFICATION NEEDED: (decision-grade questions with safe defaults), moves the card to needs_clarification (shown in In progress with a highlighted border), and stops
  5. You answer/approve in the card drawer (Approve + run writes an APPROVED: 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 a SELF-REVIEW: event with findings + fixes), attaches a test-plan doc, and calls request_review
  6. 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 15 from the CLI; POST /api/projects/:slug/run-group from 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 run treats 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 test runs 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.
Ver o original no GitHub

Bom para

Relacionados