Skip to content
Pigeon — local-first MCP kanban Pigeon — local-first MCP kanban Pigeon

Quickstart

This walks you from a clean checkout to a working briefMe call in under ten minutes. Everything runs on your machine — nothing to sign up for.

Board view after running the setup wizard with the tutorial project seeded — 20 cards across five columns demonstrating priorities, tags, checklists, comments, relations, and milestones.

Before you start

Section titled “Before you start”

You need:

  • Node.js 20 or newer — node --version
  • Git — for the #N ↔ commit linkage feature
  • An MCP-compatible coding agent — Claude Code, Codex, or anything that speaks MCP over stdio

The ten-minute path

Section titled “The ten-minute path”

  1. Clone and install

    Terminal window
    git clone https://github.com/2nspired/pigeon.git
    cd pigeon
    npm install

  2. Run the setup wizard

    Terminal window
    npm run setup

    It creates the SQLite database, optionally seeds a tutorial project with sample cards, and can connect an external project in one pass.

  3. Start the UI

    Terminal window
    npm run service:install

    Registers the UI as a launchd service on port 3100. It starts on login and restarts on crash. Run npm run service:update after pulling new code. Open http://localhost:3100.

  4. Connect one of your projects

    From inside the project you want to track:

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

    This does three things in one pass:

    • Writes a .mcp.json in the project root pointing at the tracker so your agent finds the MCP server.
    • Installs Pigeon’s slash commands (/brief-me, /handoff, /plan-card) into .claude/commands/ so they show up in Claude Code’s slash-command menu for this project.
    • Installs the Stop hook into .claude/settings.json so the per-session token usage gets recorded to the Costs page automatically.

    It’s idempotent — re-running on a project that’s already connected just refreshes whatever drifted. Run it on every project you want to track; run it again any time you upgrade Pigeon. Doing so is the right move on every project, every time.

    Using a non-Claude agent?

    Terminal window
    AGENT_NAME=Codex /path/to/pigeon/scripts/connect.sh

  5. Start a new chat and run briefMe

    Open a new session with your agent in the connected project. Ask it to run briefMe. You’ll see a compact primer come back — roughly 300–500 tokens of: the last handoff, changes since then, top work-next candidates, blockers, recent decisions.

    That’s the loop. Every session starts this way.

Zero → briefMe, visually

Section titled “Zero → briefMe, visually”
flowchart LR
	A[Clone repo] --> B[npm install]
	B --> C[npm run setup]
	C --> D{UI choice}
	D -->|macOS| E[npm run service:install]
	D -->|Any OS| F[npm run dev]
	E --> G[connect.sh in project]
	F --> G
	G --> H[Agent runs briefMe]
	H --> I[Session primer returned]

After the wizard

Section titled “After the wizard”

Once you have a board running, the next thing to read is The session loop — it’s the workflow the whole tool is built around.

If you want to give your agent a nudge toward using the tracker consistently, drop a short Project Tracking section into your project’s CLAUDE.md (or AGENTS.md). Example:

## Project Tracking


This project is tracked via Pigeon MCP. Call `briefMe()` at the start
of each conversation. Reference cards by `#number`. Call `saveHandoff(...)`
before wrapping up — in Claude Code, the `/handoff` slash command runs it
for you.

Keyboard shortcuts

Section titled “Keyboard shortcuts”

The web UI supports a small set of shortcuts. More may be added over time.

KeysWhereWhat it does
⌘K / Ctrl+KAnywhereOpen the command palette
← / →Card detail sheet openStep to the previous / next card in the current view’s visible order
EscEditing title or descriptionCancel edit and discard changes
⌘↵ / Ctrl+↵Editing descriptionSave changes

Arrow-key card navigation honors the active filters, hidden roles, and sort mode of the view you’re in. It won’t fire while a text input, select, or dialog has focus, so it stays out of the way while you’re editing.

When something goes wrong

Section titled “When something goes wrong”

Run npm run doctor first — it’s the eight-check install diagnostic and prints a copy-pasteable fix for every failure. Then look up the symptom on the Troubleshooting page, which covers the common failure modes (MCP not connecting, briefMe failing on missing repoPath, FTS5 half-state, schema drift, launchd label drift, stop-hook silently no-op’ing, old tool names that no longer resolve).

Two install-stage gotchas that aren’t on the troubleshooting page because they only fire once:

  • Database is empty after clone — data/tracker.db is gitignored, so each install is fresh. Run npm run setup or npm run dev to create it.
  • Forked the repo and docs won’t deploy — the GH Pages workflow requires Settings → Pages → Source → GitHub Actions. Set this once per fork before the first push.

For workflow-level pitfalls (skipping briefMe, prose-instead-of-structure handoffs), see the anti-patterns page — that’s a different category from the install-and-config failures the troubleshooting page covers.

Section titled “Read next”