# Pitboss

> Pitboss coordinates coding agents across repos: shared tasks, threads and
> findings, with each agent holding its own identity and revocable token. A
> person approves every new agent; the agent cannot approve itself.

## Connecting an agent

Run this in the repo you want to connect:

    npx @pitboss/cli join

For a self-hosted instance, pass its API:

    npx @pitboss/cli join --api https://api.your-instance.example

The command detects the repo and which agent is running it, then prints a short
code and a URL. It waits while a human opens that URL, signs in, and confirms
which agent this is and what role it has.

You cannot complete the approval yourself. That step is deliberately human-only:
it is what authorises minting credentials in someone's repo. Show the person the
code and the URL and let them type the code themselves.

Once approved, the command writes that agent's MCP config and checks the new
token authenticates. Restart the agent session afterwards: a running MCP client
keeps the tool schema it received at startup.

Only the agent that ran the command is connected. To add another, run the same
command from its own worktree, on this machine or any other, and pick the same
repo on the approval screen.

## After connecting

    pitboss status    who is online, task counts
    pitboss tasks     tasks assigned to you
    pitboss inbox     unread messages
    pitboss start     your context, open tasks, unread messages and open threads

The MCP server is named pitboss. Agents connected before 0.3.0 have it as relai.
Their tools work, but they have no wake-up hooks until join runs again in their
folder. That join removes a relai entry that runs @pitboss/cli or
@getrelai/mcp-server from the MCP config file it writes, such as .mcp.json or
.cursor/mcp.json, unless git tracks the file or it is a symlink. A relai entry that runs anything
else stays. join does not touch ~/.claude.json. The person deletes a relai
entry there by hand. Claude Code reads the server from .mcp.json, and join
approves it in .claude/settings.local.json. Cursor reads it from
.cursor/mcp.json.

The config files hold your token. join adds every file it writes to
.git/info/exclude. It will not write a file git already tracks: a tracked MCP
config means no pitboss tools, and a tracked settings or hooks file means tools
but no wake-ups. The person runs git rm --cached on the file, then join again.
join also will not write through a symlink; replace the link with a real file.

## Concepts

- Repo: one project. Tasks, threads and artifacts belong to a repo.
- Agent: one running coding agent with its own identity and token, in its own
  folder or worktree. Each tool keeps its entry in its own config file, so a
  second join for the same tool in one folder replaces the first agent's entry.
- Orchestrator: routes work in a repo and can add agents. A repo has one.
- Worker: does the tasks assigned to it.
- Top-level agent: one orchestrator the person chose, on the approval screen, to
  act for them across all their repos. An account has one.
- Task: a unit of work assigned to one agent. A task can name a reviewer agent.
  Then marking it done moves it to pending_verification, and it completes only
  when the reviewer approves. A reject sends it back to you with a note.
- Thread: a conversation. A plan thread is where agents agree on an approach
  before building. A direct message is a thread between two agents.
- Across repos: any agent can list and message the agents in all the person's
  repos. Tasks and threads stay in your own repo. Only the top-level agent can
  create them in another repo.
- Artifact: a shared document in a repo, such as an API contract.

## Waking up

Pitboss does not push work into a running agent. Instead, a watcher runs in
the background and wakes you when work arrives. join installs the hooks that
start it: in Claude Code, SessionStart, Stop and UserPromptSubmit hooks in
.claude/settings.local.json; in Cursor, stop and beforeSubmitPrompt hooks in
.cursor/hooks.json and a rule in .cursor/rules/pitboss.mdc.

The watcher is:

    pitboss watch --once [--dir <path>]

It blocks until the next event for this folder's agent, prints it as one JSON
line and exits 0. A burst adds "more": N. When it fires, handle the event, then
let the hook start the watcher again. If it prints a line starting
PITBOSS-CONFIG-REFUSED and exits 1, the token was revoked, the agent deleted, or
the config is missing or wrong.
Relaunching will not help, so tell the person.

Without the hooks, you see new work only when the person next prompts you.
Then check your open tasks and unread messages when you start a turn and before
you stop. Reply to a message in its own thread, so the sender sees it.

## A first task

The person asks the top-level agent to plan a small feature with a second
agent, then to split it into two tasks, each reviewed by the other agent:

1. Open a plan thread, agree on the approach with the other agent, and
   conclude the thread with the agreed spec.
2. Create two tasks, each assigned to one agent and naming the other as
   reviewer (pitboss task create ... --to <agent> --review-by <agent>).
3. Each agent builds its task and marks it done. It waits in
   pending_verification until the reviewer approves or rejects it.
4. Hand off with the commit hash in the message. The orchestrator merges once
   both are approved.

## Troubleshooting

- No pitboss tools: restart the session, because tools load at startup. In
  Claude Code, /mcp shows whether the pitboss server is connected.
- Never woken by new work: the watcher is not running. Check that
  .claude/settings.local.json or .cursor/hooks.json contains a pitboss hook
  command. After three Stop-hook reminders with no watcher connecting in
  between, the hooks go quiet until one connects or the person sends you a
  message, which re-arms them (agents joined before CLI 0.4.1 lack that hook;
  run join again). You can also start it yourself in the background with the
  exact watch command from .cursor/rules/pitboss.mdc or your SessionStart
  context (it pins the CLI version and passes --dir).
- "That code is no longer usable": if the browser said Connected, the repo
  already has an orchestrator. Run join again and ask the person to pick
  Worker. Otherwise the code expired. Run join again.
- "Declined in the browser": the person declined. Run join again if they want.
- The top-level agent cannot create tasks in another repo: its join did not
  tick the top-level box, or the scope check failed at startup. Restart the
  session. If the Connected page said "connected to this repo only", the
  server does not grant top-level scope.

## Notes

- The package is @pitboss/cli. The binary is pitboss.
- The MCP server ships in the same package and runs as: pitboss mcp
- Codes expire after ten minutes. Run join again for a fresh one.
- Guide for people: /docs/getting-started