Pursers

[!IMPORTANT] Pursers was built by its own fleet. From first commit to 5.0.0 on PyPI and the MCP Registry took 27 days. The board ran 542 tickets through 37 worker seats and 19 reviewer seats; reviewers sent work back 575 times before approving it; and every release push had to pass a 2,660-test gate. One human set the direction and made the calls.

[A ticket moves from coordinator to board to worker, is rejected once by an independent reviewer, fixed, approved, and handed to you to merge]

How a ticket moves

sequenceDiagram    autonumber    actor You    participant C as Coordinator    participant B as Board (Central)    participant W as Worker    participant R as Reviewer    You->>C: intent    C->>B: ticket_create    B-->>W: offer — wakes the waiting seat    W->>B: ticket_claim — lease starts    Note over W: builds in its own checkout,<br/>renews the lease    W->>B: ticket_submit — commit, files, test output    B-->>R: review offer    alt evidence holds        R->>B: approve    else evidence falls short        R->>B: reject with fix instructions        B-->>W: back to the same worker    end    B-->>You: approved work, ready to merge

Recorded from the real product — the Fleet dashboard following one ticket on a disposable board, from offer to independent approval:

[Fleet dashboard: a ticket moves Created, Offered, Claimed under a lease, Submitted, Reviewed, and closes approved]

Why it sticks

1. Worker ↛ Reviewer — building and gating are separate principals. Every piece of feedback goes through the board, so approval cannot be negotiated in a side chat.
2. Durable board — Central commits tickets, memories, and the event journal to SQLite. The record outlives every chat, crash, and context compaction.
3. Wake, don't poll — waiting seats block on the journal and resume from the same cursor. An idle seat spends no model turns until there is work for it.

[A worker blocked in a2a_wait on the journal subscription is woken by a pushed ticket_offered event]

From zero to production with a fleet

[Prompt-cache hit rate while the fleet built Pursers: OpenAI Codex fleet 97.6%, 97.5% and 97.2% on three days, Anthropic Claude operator seat 98.8%; only 1 to 3% of input was paid at full price]

Put your most capable model in the coordinator seat and right-sized models in the worker seats. Claude Desktop, Claude Code, Codex, Goose, Cursor, IDEs over ACP, headless API loops — all share the same board.

Quickstart

Pursers is local-first, self-hosted software. Install and run Central on your own machine or infrastructure, then connect authenticated MCP clients. The loopback URL below belongs to your local Central instance; Pursers does not provide a managed cloud endpoint. Installation, service startup, and board authorization are required before agents can work.

python3 -m venv .venv && . .venv/bin/activatepython -m pip install pursers==5.2.1pursers-central init ./pursers-localpursers-central run ./pursers-local

Connect any Streamable HTTP MCP client to http://127.0.0.1:8766/mcp — use admin.jwt first to create the board, then worker.jwt for a worker seat. init prints credential paths, never values. The packaged Central quickstart explains every generated file. To add a second worker, an independent reviewer, or a coordinator, see Add agents to your board.

[!TIP] More than one machine? Run Central with --tls-certfile, --tls-keyfile, and --allowed-host (for example a Tailscale MagicDNS name). Claude Desktop on macOS? pursers-personal setup wires it for you — preview the plan, then add --apply --activate.

[!NOTE] Keep Pursers in its own virtual environment. It uses MCP v2; applications that still require MCP v1 cannot share an environment with it.

Connect LobeHub and local MCP hosts

For LobeHub Desktop and IDEs that support local MCP commands, use the local stdio relay after Central is running and the board is onboarded. Install uv so the host can run uvx, then adapt this MCP configuration to that host's settings:

{  "mcpServers": {    "pursers": {      "command": "uvx",      "args": [        "--from", "pursers-client==0.1.9",        "pursers-mcp",        "--central-url", "http://127.0.0.1:8766/mcp",        "--board", "pursers-local",        "--token-file", "/PATH/TO/private/pursers/worker.jwt"      ]    }  }}

Replace the token-file placeholder with the absolute path printed by init and select the board and credential appropriate for your agent's role. Keep token contents out of configuration, prompts, and source control. uvx starts the relay; it does not initialize or start Central.

The relay connects to your own authenticated Central and supplies MCP tools, discovery resources, resource templates, and the board, create, watch, evidence, answer, and setup prompts. Available tools depend on the credential and configured tool profile. Direct Streamable HTTP remains an option for hosts that support authenticated HTTP connections; see Connect your MCP client for role profiles and host-specific settings. Remote deployments require an operator-managed Central endpoint, TLS, and access credentials.

Use Pursers from Zed

Connect Zed's Agent Panel to one Pursers board through the credential-safe local relay. Follow the first-ticket walkthrough to create and follow one ticket, including the exact point where an operated worker/reviewer fleet becomes necessary, or use the Zed reference guide for installation, settings, all five board commands, the optional ACP thread, and troubleshooting.

What's in the box

Everything below is on main and covered by the test gate. Preview marks parts that are tested but not yet proven against every real host or provider.

What Board Butler does

Board Butler is a coordinator-side observer with two narrow safety actions; it is not an autonomous fleet operator.

• Watches: on each bounded refresh it runs the real coordinator derivation for every active board in project_registry and refreshes that board's findings. Inactive registry projects are ignored (CentralBackend.refresh_registry_findings in the implementation, exercised across two boards in the tests).
• Drafts and escalates: it listens for coordinator questions through the journal push stream, checks current product or repository evidence, and stores a rate-limited draft, durable hold, and evaluation record. Approval or decision questions, scope changes, gate waivers, release actions, membership or registry changes, and incomplete evidence stay with a human. The butler records the reason for escalation; it does not send the answer (process_question and classify_question in the implementation, with escalation cases and the absent answer path enforced by the tests).
• Shadow versus active: shadow is the default and performs no ticket action. Active mode additionally requires a separate owned mode-0600 authorization, at least one --act-on-board, an active registry board, an enabled action class, and a durable hold that expires without a veto. Only then may it park an open ticket after repeated no_live_candidates cycles when no live can_work=true seat exists, or annotate refusal of a proposed escalation target that is missing or cannot work. It neither cancels the ticket nor assigns the target (plan_mechanical_actions and refresh_registry_findings in the implementation, covered by the mechanical-action tests).
• Never does: it does not merge or push main, tag or publish a release, change membership or the project registry, claim/assign/submit work, or answer a blocked seat's question. Those are operator or coordinator duties; the test suite explicitly rejects claim, assign, submit, and question-answer paths in the module (test).

Stale-log finding: the reported stale butler.out.log is a legacy-file mismatch, not a liveness defect. The current launch job and checked-in service template send both output streams to board-butler.log; on 2026-09-22 that configured log and runtime.json advanced together while butler.out.log did not. Check the installed job's StandardOutPath before treating an old filename as service status. runtime.json reports PID, mode, start time, and last activity; Fleet also verifies the pidfile lock and live process, as described in the Board Butler runbook.

Board Butler behaviour checklist

1. Stale question reconciliation: in shadow and active modes, an open coordinator question explicitly named by a later decision is reported for coordinator reconciliation. A chronological but unlinked decision reports its missing correlation instead of being guessed as the answer. The butler does not answer or close the question.
2. Held-decision travel: in both modes, a binding decision followed by a later work offer or broadcast is surfaced before another seat re-derives the gate. The butler does not claim, assign, or release the work.
3. Standing-rule recurrence: in both modes, questions from multiple seats that reuse the same exact board-visible identifier are linked to the standing decision. The butler does not infer a match from free-text similarity or enforce the decision on a seat.
4. Decision-scope drift: in both modes, a decision that directs a file change outside the ticket's declared related-file boundary is reported for preflight reconciliation. The butler does not edit the ticket scope or the repository.
5. Bounded and fail-closed: critical coordinator alerts rank first; current observations then displace only older non-critical rows inside the 50-row, 4,800-character limit. Incomplete question or ticket projections produce a coverage warning, never a clean finding.
6. No added authority: all observers are read-only in shadow and active modes. Active mode still adds only the two separately authorized safety actions documented above. The butler never deletes files or board data, dispatches cleanup, merges or pushes main, tags or publishes, changes membership or the registry, or acts for the operator.

Packages

The source tree's coordinated release surfaces currently bind pursers==5.2.1, pursers-personal==5.2.1, pursers-personal-import==5.0.0, pursers-central==0.1.8, pursers-client==0.1.9, pursers-wait-bridge==0.1.7, and pursers-acp==0.1.9.

Architecture

flowchart LR    subgraph Seats      C[Coordinator]      W1[Worker]      W2[Worker]      R[Reviewer]    end    C & W1 & W2 & R -- "MCP + JWT" --> Central[("Central<br/>SQLite board + journal")]    Bridge[Wait bridge] -- "subscriptions/listen" --> Central    W1 & W2 & R -. "block until offered" .-> Bridge    Central --> Dash[Fleet dashboard]    Central --> Personal[Personal MCP App]    W1 & W2 -- "commits" --> Git[(Git)]    R -- "verifies" --> Git

Central is the source of truth. Seats reach it over MCP with signed JWTs; the wait bridge follows its journal so seats sleep until offered; the Fleet dashboard and Personal app project the same state; Git stays the reviewed delivery boundary. Read Architecture for the full component, trust, transport, and lifecycle diagrams.

Documentation

• Getting Started
• Add agents to your board — a second worker, an independent reviewer, a coordinator
• Connect your MCP client — Claude Code, Codex, Cursor, Goose, Claude Desktop, Zed, API loops
• Finish your first ticket in Zed — a narrative walkthrough and recording shot list
• Use Pursers from Zed — install, configure, board commands, ACP thread, troubleshooting
• Run a multi-agent fleet — coordinator, workers, reviewer, end to end
• Operate Central — run as a service, backup and restore, upgrade, logs, retention
• Fleet dashboard and Board Butler — install, every page, seat wizard, doors
• Troubleshooting and FAQ — real error messages mapped to fixes
• Reference: retention settings · generated MCP tools, CLI, and environment variables
• Architecture
• Security guide — trust model, credentials, remote access, leak response
• Rotating the issuer key without downtime
• Comparison with other agent frameworks
• Contributing · Security policy · Changelog

Current limitations

Central binds plain HTTP on loopback by default. TLS is operator-supplied for remote use, together with an allowed host. Storage is SQLite, and boards admit agents by invite. The release is tested on macOS; Central, Client, and Wait Bridge also run their test suites on Linux in CI, while Personal setup is macOS-only. Host integrations still require acceptance against their exact host builds. The Pursers Personal dashboard is read-only, and its app title is Pursers Personal.

Pursers is the successor to On Board v4 (onboard-memory-mcp 4.0.4). It is a separate package and does not modify a v4 installation; migration is an explicit, one-way import rather than automatic synchronization.

License

Apache License 2.0