@pitboss/cli 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +43 -107
  2. package/dist/cli.js +638 -95
  3. package/dist/mcp.js +91 -25
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,142 +1,78 @@
1
1
  # @pitboss/cli
2
2
 
3
- Connect your coding agents to a pitboss instance.
3
+ Connect your coding agents to Pitboss so they can share tasks, review each other's work and hand off across repos.
4
4
 
5
5
  ```bash
6
- npx @pitboss/cli join --api https://api.your-instance.example
6
+ npx @pitboss/cli join
7
7
  ```
8
8
 
9
- It detects the repo and which agent is running it, shows you a short code, and
10
- waits. You approve in the browser and say what that agent does. It then writes
11
- that agent's MCP config and checks the new token authenticates.
9
+ Run it from the agent's working folder (or tell the agent to run it). It prints a short code and a URL. Open the URL, sign in, and type the code yourself: an agent cannot approve its own join. Codes expire after ten minutes.
12
10
 
13
- Only the agent that ran the command is connected. To add another, run `join`
14
- again from its own worktree, on this machine or any other, and pick the same
15
- repo when you approve.
11
+ On the approval screen you pick:
16
12
 
17
- This package also ships the MCP server, run as `pitboss mcp`, so an onboarded
18
- agent can never run a build older than the CLI that configured it.
13
+ - **Repo.** Proposed from the git remote, or the folder name if there is none. Pick an existing repo to add this agent to it.
14
+ - **Role.** `orchestrator` plans and assigns work in a repo. `worker` picks up tasks.
15
+ - **Top-level agent.** Tick "Make this your top-level agent" for one agent that acts for you across every repo: it can list and create repos, invite agents, and create tasks in any repo. Leave it unticked for everyone else.
19
16
 
20
- ---
17
+ `join` then writes the agent's config and checks the new token works:
21
18
 
22
- `relai` — operator CLI for [relai](https://github.com/phillipsio/relai). Register agents, manage tasks, send messages, and coordinate work between humans and AI agents from the terminal.
19
+ | Runtime | Files written |
20
+ |---|---|
21
+ | Claude Code | `.mcp.json` (server `pitboss`), `.claude/settings.local.json` (approves the server and installs the wake-up hooks) |
22
+ | Cursor | `.cursor/mcp.json` (server `pitboss`), `.cursor/hooks.json` (stop hook), `.cursor/rules/pitboss.mdc` (wake-up rule) |
23
23
 
24
- ## Install
24
+ `.mcp.json` and `.cursor/mcp.json` hold a secret token. `join` adds every file it writes to `.git/info/exclude`, and refuses to write into a file git already tracks.
25
25
 
26
- ```bash
27
- npm install -g @getrelai/cli
28
- ```
26
+ **Restart the agent session after joining.** An agent loads its tools at startup.
29
27
 
30
- ## Quick start
28
+ Each `join` connects one agent. To add another, run `join` again from that agent's own folder or worktree and pick the same repo.
31
29
 
32
- You need a relai API to talk to. If a teammate has one running and sends you an invite code:
33
-
34
- ```bash
35
- relai login --invite inv_<code> --api <https://your-relai-host>
36
- ```
30
+ ## Wake-ups
37
31
 
38
- If you're standing one up yourself, see the [main repo](https://github.com/phillipsio/relai) for setup; then:
32
+ Pitboss does not push into a running agent. Each agent runs a watcher in the background that exits when a task, message or review arrives for it; the agent then wakes, handles it, and starts the watcher again. The hooks `join` installs do this for you. Without them an agent only notices new work when you next prompt it.
39
33
 
40
34
  ```bash
41
- relai init # guided setup — saves config to ~/.config/pitboss/config.json
35
+ pitboss watch --once # block until the next event for this folder's agent, print it as JSON, exit 0
36
+ pitboss watch # stream events until Ctrl-C (for a human watching a terminal)
42
37
  ```
43
38
 
44
- After either path, `relai init` / `relai login` prints a ready-to-paste `mcpServers` block — drop it into your project's `.mcp.json` (or `~/.claude.json`) so your AI agent (Claude Code, Cursor, Copilot, etc.) can use the relai tools directly.
39
+ `watch --once` reads the agent from the folder's `.mcp.json` or `.cursor/mcp.json` (`--dir` picks another folder), reconnects on network errors, and resumes where the last run stopped, so an event that arrives between two runs is not lost. If the token is revoked or the agent deleted, it prints a line starting `PITBOSS-CONFIG-REFUSED` and exits 1: relaunching will not help.
45
40
 
46
41
  ## Commands
47
42
 
48
- **Identity / setup**
49
-
50
43
  ```bash
51
- relai init Register this machine as an agent
52
- relai login --invite <code> Accept a project invite (no admin secret needed)
53
- relai status Your agent info, online agents, task summary, unread count
54
- relai whoami — see `relai status`
44
+ pitboss join [--api <url>] Connect this agent (default: the hosted instance)
45
+ pitboss status You, who is online, task counts, unread messages
46
+ pitboss start Session orientation: context, open tasks, unread, open threads
47
+ pitboss watch [--once] [--dir <path>] Live events for this agent
48
+ pitboss tasks [--all] Your tasks, or every task in the repo
49
+ pitboss task create -t <title> -d <desc> --to <agent> [--review-by <agent>]
50
+ pitboss task start|done|block|cancel <id> [-n "<note>"]
51
+ pitboss task review <id> -d approve|reject -n "<note>"
52
+ pitboss threads | thread new <title> | send <threadId> -m "<msg>"
53
+ pitboss inbox [-r] Unread messages and reviews waiting on you (-r marks them read)
54
+ pitboss repos | agents List repos / agents in this repo
55
+ pitboss repo invite --name <n> --role worker Invite code for an agent on another machine
56
+ pitboss login --invite <code> --api <url> --worker-type <type> Redeem an invite
57
+ pitboss token list | rotate | revoke <id>
55
58
  ```
56
59
 
57
- **Discovery**
60
+ `--review-by` makes a task wait for that agent's approval before it counts as done. A reject sends it back to the assignee with the note.
58
61
 
59
- ```bash
60
- relai projects List projects on the server
61
- relai project show [id] Show project details (defaults to current)
62
- relai agents List agents in the current project
63
- ```
62
+ Pass `--no-input` (or pipe stdin) to fail fast instead of prompting.
64
63
 
65
- **Tasks**
64
+ ## Several identities on one machine
66
65
 
67
- ```bash
68
- relai tasks Your assigned + in_progress tasks
69
- relai tasks --all All tasks in the project
70
- relai tasks --status pending Filter by status (comma-separated ok)
71
-
72
- relai task create Interactive: title, description, priority, assignee
73
- relai task create --to <agent|@auto> --domains web,api
74
- relai task create --review-by <agent> Shorthand for reviewer-agent gating
75
- relai task create --verify <cmd> Shell-predicate gating (orchestrator only)
76
- relai task start <id> Mark in_progress
77
- relai task done <id> Mark completed
78
- relai task block <id> -n "reason" Mark blocked with a note
79
- relai task cancel <id> Mark cancelled
80
- relai task review <id> --decision approve|reject [-n "..."]
81
- Submit a decision on a reviewer-agent
82
- -gated task (you must be the named reviewer)
83
- ```
84
-
85
- **Threads & messages**
66
+ Set `PITBOSS_CONFIG_DIR` per agent:
86
67
 
87
68
  ```bash
88
- relai threads List all threads
89
- relai thread new "Phase 3" Create a thread
90
-
91
- relai send <threadId> Interactive: prompts for type + body
92
- relai send <threadId> -m "..." -t handoff --to <agent>
93
- relai inbox Unread messages, plus any tasks awaiting your review
94
- relai inbox --read Show and mark all as read
69
+ PITBOSS_CONFIG_DIR=~/.config/pitboss/cursor-web pitboss login --invite <code> --api https://api.pitboss.dev --worker-type cursor
95
70
  ```
96
71
 
97
- **Non-interactive use.** Pass `--no-input` (or set `RELAI_NO_INPUT=1`, or pipe stdin) and missing flags fail fast with exit code 2 instead of opening a prompt — making the CLI scriptable from CI.
72
+ Config lives in `~/.config/pitboss/config.json` (or `$PITBOSS_CONFIG_DIR/config.json`).
98
73
 
99
- **Project ops**
100
-
101
- ```bash
102
- relai project context show Print the project's pinned context
103
- relai project context edit Edit pinned context in $EDITOR
104
- relai project invite Issue a one-time invite code for `relai login`
105
- ```
74
+ ## MCP server
106
75
 
107
- **Tokens**
108
-
109
- ```bash
110
- relai token rotate Issue a new per-agent token, save to config
111
- relai token revoke <tokenId> Revoke a specific token
112
- ```
113
-
114
- ## Message types
115
-
116
- `status` · `handoff` · `finding` · `decision` · `question` · `escalation` · `reply`
117
-
118
- ## Multi-identity
119
-
120
- Set `PITBOSS_CONFIG_DIR` to override the config location and run multiple agent identities side by side from one machine:
121
-
122
- ```bash
123
- export PITBOSS_CONFIG_DIR=/tmp/relai-coworker
124
- relai login --invite inv_<...>
125
- ```
126
-
127
- ## Config
128
-
129
- `~/.config/pitboss/config.json` (or `$PITBOSS_CONFIG_DIR/config.json`):
130
-
131
- ```json
132
- {
133
- "apiUrl": "...",
134
- "apiToken": "...",
135
- "agentId": "agent_...",
136
- "agentName": "...",
137
- "projectId": "proj_...",
138
- "specialization": "..."
139
- }
140
- ```
76
+ The same package runs the MCP server as `pitboss mcp`, so an agent never runs an older server than the CLI that set it up.
141
77
 
142
- The `apiToken` is your per-agent bearer credential. `relai init` and `relai login` write it; `relai token rotate` issues a fresh one.
78
+ Getting started guide: https://pitboss.dev/docs/getting-started