Quickstart

From pip install to cross-agent recognition in about three minutes. Nothing here needs an account, a card, or a server you do not control.

If you would rather see Bourdon work before it touches your machine, jump to bourdon demo first. It runs the production pipeline against synthetic data in a temporary directory.

Already paid for a hosted instance? This page installs the engine on your own machine, which you do not need. Go to the Hosted guide instead - your endpoint is already running.

1. Install#

pip install bourdon

Python 3.10 or newer. macOS, Linux, and Windows (WSL recommended) are all exercised by CI.

Homebrew (Apple silicon macOS and ARM64 Linux):

brew tap bourdonai/bourdon https://gitlab.com/bourdonai/bourdon
brew install bourdonai/bourdon/bourdon

Docker, if you want the MCP server as a container instead of a Python install:

docker run -d -p 7500:7500 -v bourdon-data:/data --name bourdon bourdonai/bourdon

Optional extras:

2. Set up#

bourdon setup

The wizard detects which agents are installed on this machine and shows them as a checkbox list. Detection is automatic; federation is your choice. Every detected agent starts checked, you uncheck any you want kept out, and Enter continues. Your picks are recorded in ~/.bourdon/agents.yaml and honoured by every later export.

Setup then creates ~/agent-library/, wires Claude Code's hooks (a SessionEnd export so the manifest stays fresh, plus UserPromptSubmit and SessionStart recognition hooks so every turn starts with what the federation already knows, and a Stop hook that scores whether the reply used it), and offers to run the first export for you.

It is idempotent. --dry-run prints the plan without changing anything; --non-interactive takes the defaults.

Changed your mind later? bourdon agents list shows the roster, and bourdon agents enable <agent> / bourdon agents disable <agent> change it without re-running the wizard. bourdon console opens the same picklist as a loopback-only browser page.

3. Verify#

bourdon doctor

Each participant reports ok, degraded, or blocked. Anything not ok carries a proposed_fix line with the exact command to run next:

- agent: codex
  status: degraded
  reason: 'Missing Codex sub-sources: session_index, sessions_dir'
  proposed_fix: If Codex was just signed in but has no chat history, this is
    expected. Run `bourdon codex sync-native --from-library --memory-md --write`
    to seed recognition substrate from your federation library.

Add --strict to exit non-zero on anything unhealthy (surfaces that have never yielded on this machine are ignored, so an agent you do not use cannot fail the check).

4. Connect an agent over MCP#

Every agent that speaks MCP can read the federation directly. The zero-config path is stdio: the client launches the server itself, no ports and no tokens.

Claude Code:

claude mcp add bourdon -- bourdon serve

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "bourdon": { "command": "bourdon", "args": ["serve"] } } }

Cursor, Codex, Copilot, Cascade, Hermes and the others have their own notes under docs/integrations/ in the repository. For a server other machines can reach, see Self-host.

5. See it work#

Open an agent and ask:

What dev tools or projects am I currently working on?

The first-turn answer should surface project recognition from the federation library, attributed to the agents that produced it. The reader agent is calling prepare_recognition_context, find_entity, or list_recent_work on the Bourdon server; the writer agent never had to be told anything.

From the command line, the same recognition step is:

bourdon prepare-turn "what am I working on"

If recognition did not fire, see Troubleshooting.

Cross-machine (optional)#

Use Bourdon on two machines? Sync the federation library between them:

# on machine A
bourdon sync push [email protected]:~/agent-library/

# on machine B
bourdon sync pull [email protected]:~/agent-library/

Push filters by visibility before the network leg (--access-level public|team|private, default public). Pull receives into a quarantine: remote-changed manifests must pass identity and shape validation before the agents/ directory is promoted atomically. Both wrap rsync -az --checksum --delay-updates --safe-links, so the transport is idempotent.

For two always-on servers that answer each other's queries live, see peer federation.

See it before installing#

bourdon demo

A self-contained walkthrough. It stages synthetic agent-library content in a temporary directory, runs the production federation pipeline against it, and prints what would land in a recognition file, including multi-agent (via <agent>) attribution and visibility filtering. No real IDE state is touched and no network call is made.

bourdon demo --access-level team shows what team-only entries look like. --no-keep deletes the tempdir on exit.

Maintain#

bourdon export-all    # refresh every participant's manifest
bourdon doctor        # check health, get fix proposals if anything drifts

The Claude Code SessionEnd hook wired by setup already keeps claude-code.l5.yaml fresh. The explicit export-all matters when you add a participant or want to force a refresh.

Troubleshooting#

Still stuck? bourdon dogfood plants a marker entity, exports everything, queries L6, and verifies the round trip end to end, then prints a machine-readable report you can attach to an issue.