clawborrator-cli 0.0.45 → 0.0.47

package/README.md

@@ -0,0 +1,288 @@
+# clawborrator-cli
+
+`claw` — command-line client for [clawborrator](https://next.clawborrator.com),
+a control plane for Claude Code sessions.
+
+What you can do with it from a terminal:
+
+- Attach to any CC session you can see (yours or shared with you), watch
+  prompts and tool calls stream in, type your own prompts, approve or
+  deny permission gates, chat with other operators on the side.
+- Send one-shot prompts to a session non-interactively (CI-friendly).
+- Mint channel tokens (`ck_live_…`) and drop a ready-to-use `.mcp.json`
+  block so a CC running on this machine appears on the hub.
+- Route prompts across sessions (`claw route @backend "what time is it"`)
+  with reply tracking.
+- Share sessions with teammates at viewer / prompter / approver role.
+- Publish a session as a public expert agent (`@<owner>/<slug>`,
+  callable from any prompt).
+- Subscribe to webhooks for chat / permission / file / agent events.
+
+The hub is at <https://next.clawborrator.com> by default — point at a
+self-hosted instance with `claw login --hub <url>` (persists per
+machine).
+
+---
+
+## Install
+
+```bash
+# one-off (no global install)
+npx clawborrator-cli@latest login
+
+# or pin globally
+npm install -g clawborrator-cli
+claw login
+```
+
+Requires Node 20+.
+
+---
+
+## First-time setup
+
+```bash
+# 1. Authenticate (opens a browser → GitHub → back to a localhost
+#    callback that hands you a 30-day session token).
+claw login
+
+# 2. Confirm.
+claw whoami
+# logged in as @your-github-login
+
+# 3. (optional) Mint a channel token + drop the .mcp.json block so
+#    your local Claude Code registers a session against the hub.
+claw token mint --name "$(hostname)" --mcp-snippet --out .mcp.json
+# → now restart `claude code` in this directory and it'll appear in
+#   `claw session list`.
+```
+
+The session token is stored at `~/.clawborrator/config.json` (mode
+0600). To talk to a different hub, pass `--hub <url>` once on login;
+the URL persists.
+
+---
+
+## Cheatsheet
+
+### Sessions
+
+```bash
+claw session list                              # your sessions + ones shared with you
+claw session ls --connected                    # only currently-online ones
+
+claw session attach @backend                   # interactive TUI: live tail + send prompts + approve gates
+claw session attach 6d04…uuid
+
+claw session info @backend                     # one-shot detail dump
+claw session events @backend --kind chat       # transcript history (--limit / --after / --before)
+claw session messages @backend                 # operator-to-operator chat (op-messages)
+
+claw session prompt @backend "deploy to staging"   # fire-and-forget
+claw session prompt @backend "@MRIIOT/rust-expert what is a lifetime?"  # public-agent dispatch
+claw session prompt @backend "@alice/frontend ..."  # cross-account peer (if shared)
+
+claw session share @backend alice --role prompter  # grant access (viewer | prompter | approver)
+claw session shares @backend                       # list current shares
+claw session unshare @backend alice                # revoke
+
+claw session archive @backend                  # soft-delete (auto-resurrects on next CC start in the same project)
+claw session prune --dry-run                   # find duplicate-routing-name rows
+claw session delete @backend --hard            # permanent (cascades events / op-messages / shares)
+```
+
+`<ref>` in any subcommand accepts the session UUID, the `@routingName`
+for sessions you own, or `@owner/routingName` for sessions shared with
+you.
+
+### Cross-session routing
+
+```bash
+claw peers                                     # sessions reachable for routing (yours + shared)
+
+claw route @backend "what time is it"          # ask-mode: blocks up to 60s for the reply
+claw route @alice/frontend "..." --tell        # tell-mode: fire-and-forget
+
+claw probe "do you have a User model" --peers @backend,@frontend   # parallel fan-out
+claw probe "..."                               # implicit: every online reachable peer
+```
+
+Routing requires prompter+ on the target. Peer's CC must be online
+and not mid-turn for someone else (driver-claim contention returns a
+409 and you retry in a moment).
+
+### Channel tokens
+
+For your local Claude Code to register a session against the hub,
+clawborrator-mcp needs a `ck_live_…` token in the project's
+`.mcp.json`:
+
+```bash
+claw token mint --name "alice-laptop" --mcp-snippet --out .mcp.json
+# → writes a ready-to-use .mcp.json
+# → prints the plaintext token to stderr ONCE — copy it if you didn't redirect
+
+claw token list                                # list active tokens
+claw token revoke <id>                         # revoke (cascade-archives sessions registered with it)
+```
+
+> **Windows note:** prefer `--out <path>` over PowerShell `>`
+> redirection. PowerShell's default redirection writes UTF-16 LE with
+> BOM, which CC rejects when parsing `.mcp.json`. `--out` writes UTF-8
+> without BOM.
+
+### Public expert agents
+
+A session you own can be published as `@<your-login>/<slug>`,
+callable by any signed-in user:
+
+```bash
+claw agents publish --session <uuid> --name "rust expert" --tagline "answers Rust questions" --published
+# → @MRIIOT/rust-expert is live; rate-limited per-user, capped at
+#   1000 queries/day by default.
+
+claw agents list                               # discover everyone's published agents
+claw agents list --mine                        # your own agents (any status, includes draft)
+
+claw agents update @MRIIOT/rust-expert --budget 5000
+claw agents update @MRIIOT/rust-expert --composable        # opt out of isolation (cross-session routing tools enabled while answering)
+claw agents update @MRIIOT/rust-expert --status draft      # take it offline without unpublishing
+
+claw agents inbound @MRIIOT/rust-expert --days 7  # who's been calling: ok / denied / latency / top askers / recent
+
+claw agents unpublish @MRIIOT/rust-expert
+```
+
+Default mode is `--isolated` (recommended): the agent's CC cannot
+use cross-session routing tools while answering a public dispatch.
+Use `--composable` only for orchestrator-style agents that need to
+reach other peers.
+
+Anyone can also call your agent over the
+[A2A protocol](https://a2a-protocol.org) at
+`/api/a2a/v1/agents/<owner>/<slug>` — see the
+[A2A bridge reference](https://next.clawborrator.com/demos/a2a-docs/).
+
+### Webhooks
+
+Subscribe to events for sessions you can see:
+
+```bash
+claw webhook add --url https://your-server/hook \
+  --events 'chat.event,permission.requested,permission.resolved'
+
+claw webhook list
+claw webhook test <id>                         # queue a synthetic webhook.test delivery
+claw webhook rm <id>
+```
+
+The signing secret is shown ONCE on `add`. HMAC-SHA256 in the
+`X-Clawborrator-Signature: t=…,v1=…` header (Stripe-style).
+Verification recipes for Node + Python and the full event catalog
+live at the
+[webhooks reference](https://next.clawborrator.com/demos/webhooks/).
+
+### Auth
+
+```bash
+claw login                                     # browser-based GitHub OAuth (PKCE)
+claw login --hub https://your-hub.example.com  # point at a different hub; persists
+claw whoami
+claw logout                                    # revokes the session token + clears local config
+```
+
+---
+
+## `claw session attach` — the TUI
+
+This is the killer feature. Three or more humans attached to the
+same Claude Code session, seeing each other's prompts in real time,
+racing on tool-permission approvals, talking to each other in a side
+channel that doesn't pollute Claude's context.
+
+```
+$ claw session attach @backend
+
+  attached to @backend (cwd /home/alice/repo, role: prompter, alice (you), bob)
+  ───────────────────────────────────────────────────────────────────────────
+  [10:42] @bob ›       deploy to staging
+  [10:42] claude       I'll start by running the test suite first…
+  [10:42] → Bash       npm run test
+                       ↳ permission gate: /y to approve, /n to deny  (alice can decide)
+  /y
+  [10:42] ✓ Bash       (allowed by @alice)
+  [10:43] ✓ Bash       (npm run test exited 0)
+  [10:43] claude       Tests pass. Running deploy now…
+  ───────────────────────────────────────────────────────────────────────────
+  > _                                                          [/help for commands]
+```
+
+In-TUI commands:
+
+| | |
+|---|---|
+| `<text>` | send a prompt to the attached session |
+| `@peer <text>` | route to a peer session and wait for the reply |
+| `/op <text>` | operator-to-operator chat (visible to peers, not to Claude) |
+| `/y` `/n` | approve / deny the most recent permission gate |
+| `/peers` | show currently-reachable peer sessions |
+| `/help` | full list |
+| `Ctrl-C` | detach (the session keeps running) |
+
+---
+
+## Configuration
+
+| Path | Contents |
+|---|---|
+| `~/.clawborrator/config.json` | hub URL + session token (mode 0600) |
+| `$CLAWBORRATOR_HUB` | env override for hub URL (one-shot, doesn't persist) |
+
+---
+
+## Troubleshooting
+
+**"can't connect to localhost:8787" after login.** You're on a
+pre-0.0.45 install pointed at the dev default. Upgrade to
+`@latest` and re-run `claw login`; the new default points at
+`https://next.clawborrator.com`. Or pass `--hub` explicitly.
+
+**OAuth callback hangs / "state is required" in the browser.** On
+Windows the callback URL contains `&` which CMD's `start` builtin
+treats as a separator. Upgrade to a recent version of the CLI
+(0.0.41+); we now quote the URL through `windowsVerbatimArguments`.
+
+**`.mcp.json` written via `>` doesn't work.** PowerShell encodes
+redirected output as UTF-16 LE with BOM. CC's MCP parser doesn't
+handle the BOM. Use `claw token mint … --mcp-snippet --out .mcp.json`
+instead — that writes UTF-8 without BOM directly to disk.
+
+**`claw session attach` shows "auth failed".** Your session token
+expired (30-day hard cap, no refresh). Run `claw login` again and
+re-attach.
+
+**Cross-session routing returns "is offline" or "is processing a
+turn for another user".** The peer's CC needs to be online (channel
+WS open) and not mid-turn for someone else. Wait or pick a different
+peer.
+
+---
+
+## Where to look next
+
+- **Hub home & demos:** <https://next.clawborrator.com/>
+- **REST API (OpenAPI):** <https://next.clawborrator.com/docs>
+- **WebSocket (AsyncAPI):** <https://next.clawborrator.com/ws-docs>
+- **Webhook reference:** <https://next.clawborrator.com/demos/webhooks/>
+- **A2A bridge reference:** <https://next.clawborrator.com/demos/a2a-docs/>
+- **Source / issues / contributing:** <https://github.com/clawborrator/hub_v1>
+
+The CLI source is in `cli/` of the same repo; it's a thin shell over
+the REST + WS surface, so anything `claw` does you can do directly
+from any HTTP client.
+
+---
+
+## License
+
+MIT.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "clawborrator-cli",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "type": "module",
-  "description": "claw — command-line client for clawborrator hub_v1. Manages PATs, channel tokens, sessions, cross-session routing, and webhooks; ships an inline TUI for live multi-operator session attach.",
+  "description": "claw — command-line client for clawborrator. Attach to remote Claude Code sessions, send prompts, resolve permission gates, route across sessions, manage public agents and webhooks. Auth via GitHub OAuth + PKCE.",
   "license": "MIT",
   "homepage": "https://github.com/clawborrator/hub_v1",
   "repository": {