Pigeon MCP Server

<div align="center">

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs-site/public/pigeon-logo-dark.png"> <img src="docs-site/public/pigeon-logo-light.png" alt="Pigeon" width="240" /> </picture>

Pigeon

The visible workbench for AI-paired development. The card is the container — story, plan, comments, decisions, and cost live on the work itself, and your agents read and write it the way you do.

You see a board. The agent reads and writes the same board through MCP. Nothing leaves your machine.

Documentation · Quickstart · The session loop · Why local-first?

     

<br />

<img src="docs-site/src/assets/screenshots/board-overview.png" alt="Pigeon board view with Backlog, In Progress, and Done columns. Cards show priority-colored stripes, tags, and stable card numbers." width="900" />

</div>

---

What it is, in three sentences

Pigeon is the visible workbench for AI-paired development: a local-first kanban board that is also an MCP server, so your agents work from the same board you drag cards around on. The card is the container — story, plan, comments, decisions, and cost live on the work itself, where you see what the agent believes and correct it right where you'd naturally encounter it. Session continuity is the proof: briefMe at session start (catch up), do the work, saveHandoff at session end (leave a trail), repeat.

The metaphor is in the name — agent A wraps a session with saveHandoff; the homing pigeon flies the message across the gap; agent B catches it at briefMe and starts in-context. Same SQLite file backs the kanban UI you drag cards around in and the MCP surface your agent calls. Nothing leaves your machine.

For the long-form design narrative — the two readers, the board, the tracker.md policy contract, the MCP surface — see Concepts.

30-second demo

<!-- TODO(user): supply a 15–30s demo GIF/MP4 of the session loop (briefMe → make a card change → /handoff). Place at docs/assets/demo.gif and replace the ASCII diagram below with: <img src="docs/assets/demo.gif" alt="Pigeon session loop demo" width="900" />. -->

The session loop, end-to-end:

  ┌──────────────┐    briefMe       ┌────────────────┐    saveHandoff   ┌──────────────┐
  │  fresh chat  │ ───────────────► │   do the work  │ ───────────────► │  next chat   │
  │  (agent B)   │   load board,    │   move cards,  │   /handoff       │  (agent C)   │
  │              │   handoff, top   │   addComment,  │   wraps with     │              │
  │              │   work, blockers │   updateCard   │   summary +      │              │
  │              │                  │                │   commits        │              │
  └──────────────┘                  └────────────────┘                  └──────────────┘
         ▲                                                                      │
         └──────────────────────────────────────────────────────────────────────┘
                          briefMe again — the loop closes

You see the same board the agent does. Drag cards in the UI; the agent's next briefMe will reflect the change. The agent moves a card; you see it move on screen.

Install

You need Node 20+, git, and Claude Code. From inside the repo you want to track, run:

npx @2nspired/pigeon init

Then open Claude Code in that repo and say brief me.

init does everything — Pigeon checkout at ~/.pigeon, database, MCP registration, repo binding, starter tracker.md, slash commands, Stop hook, and (on macOS) the always-on board at localhost:3100 — and is safe to re-run. Connect more repos later with npx @2nspired/pigeon connect.

<details> <summary><strong>Manual install</strong> — clone and run the checkout yourself instead of using the CLI</summary>

<br />

Common setup, every platform:

git clone https://github.com/2nspired/pigeon.git
cd pigeon
npm install
npm run setup            # interactive: creates the DB, optionally seeds the Learn Pigeon tutorial

Then start the UI — macOS installs a persistent launchd service on :3100 (always available, restarts on crash):

npm run service:install
npm run doctor           # verifies the install (8-check diagnostic)

Linux / Windows / WSL runs the foreground dev server on :3000 (you re-run it each shell):

npm run dev              # leave running; open http://localhost:3000
npm run doctor           # in a second terminal — verifies the install

Then, from inside any project you want to track:

/path/to/pigeon/scripts/connect.sh

That writes a .mcp.json in the project's repo root, installs Pigeon's slash commands, and installs the Stop hook. Start a new chat with your agent in that directory and ask it to run briefMe. Full walkthrough: Quickstart.

</details>

What you get after install

• A kanban board at localhost:3100 (macOS) or localhost:3000 (other platforms) — drag cards around, see priority stripes, filter by tag.
• An MCP server your agent calls — briefMe, planCard, moveCard, addComment, saveHandoff, plus 65+ extended tools (saveClaim, search, costs).
• A Costs page — per-card attributed spend, top-N expensive sessions, briefMe-vs-naive savings, project-wide MCP overhead.
• An 8-check doctor (npm run doctor) — exit code 0 on green, 1 on any failure. CI-friendly.

Pigeon Doctor — install health check
────────────────────────────────────
✓ MCP registration             PASS
✓ Hook drift                   PASS
✓ launchd label                PASS
✓ Connected repos              PASS
✓ Server version               PASS
✓ Per-project tracker.md       PASS
✓ WAL hygiene                  PASS
✓ FTS5 sanity                  PASS

8 pass
All checks passed.

Run it after install and after every git pull. Stuck on something the doctor doesn't fix? See the Troubleshooting page — one page covering MCP not connecting, briefMe failing on missing repoPath, schema drift, FTS5 half-state, launchd label drift, stop-hook silently no-op'ing, old tool names, _versionMismatch.

Pigeon vs. the alternatives

How Pigeon stacks up against what people actually use today for tracking AI-assisted work:

| Dimension | Pigeon | GitHub Projects | Linear | Notion DB | Plain spreadsheet | | :-- | :-: | :-: | :-: | :-: | :-: | | Local-first (your data on your disk) | yes | no | no | no | yes (file) | | AI-native (agents read/write via MCP) | yes | unclear | unclear | unclear | no | | Free / self-hosted | yes | free w/ GitHub | freemium | freemium | yes | | Multi-user collaboration | no (solo) | yes | yes | yes | yes (shared file) | | Opinionated workflow (session loop, intent, handoffs) | yes | no | partial | no | no | | MCP server out of the box | yes | no | no | no | no | | Cost legibility for AI work | yes (Costs page) | no | no | no | no |

Notes on "unclear" entries: GitHub Projects, Linear, and Notion all have public APIs that an MCP server could be built against, and community MCP shims exist for some — but none ship a first-party MCP server that's the canonical surface for AI agents. Pigeon is built MCP-first.

Who's it for

Pigeon is built for two readers — see Pigeon ICP for the long version.

• Indie dev or consultant juggling parallel projects. You bounce between three repos in a day, each with its own context. Pigeon gives every project a board the agent can resume from cold — no more "tell me again what we were doing" at the start of every chat.
• Product Owner running an AI-assisted team. You don't write the code, but you need to know what got done, how much it cost, and whether the work is converging. Pigeon's Costs page shows attributable spend per card; the board shows what's in flight without you having to ping the agent.

Documentation

Two surfaces, different audiences:

• 2nspired.github.io/pigeon — the public docs site. First-time readers, narrative concepts, quickstart.
• docs/README.md — the in-repo doc tree. Contributors and operators of a local Pigeon checkout: architecture, data model, attribution engine, operating runbook.

When the two disagree, the site wins for concepts; the in-repo tree wins for implementation detail (cited by file:line).

Most-asked entry points

• Quickstart — install, connect, first briefMe call.
• The session loop — the four moves: briefMe, work, saveHandoff (/handoff), resume.
• MCP tools — every tool the agent can call (11 essentials + 65+ extended).
• Cost tracking — what the Costs page records, how attribution works, and the savings/overhead math.
• docs/ARCHITECTURE.md — the three-layer rule and where new code goes.
• AGENTS.md — contributor reference for agent conventions.

Releases & upgrades

• RELEASES.md — what shipped, in plain language (3–5 bullets per release).
• CHANGELOG.md — every change with card and PR refs.
• docs/UPDATING.md — what to run after git pull (npm run service:update alone is not always enough).
• docs/VERSIONING.md — semver + schema-version policy.
• docs/MIGRATION-HISTORY.md — pre-v6 tool renames (only useful when reading old transcripts).

License

MIT — © 2026 Thomas Trudzinski / 2nspired.