# Collaborait (cait) — full agent reference

DRAFT · pre-release. Schema names and fields below are the intended stable
contracts; until v1, additive evolution only and breaking changes are called
out in the changelog. The short version of this file lives at /llms.txt.

## What cait is

An open-source CLI that coordinates a fleet of AI coding sessions (OpenAI
Codex, Claude Code) the operator already has open. It drives the vendors' own
CLIs and terminals; it is not a proxy, an API relay, or an account-sharing
tool. macOS + iTerm2 for full fleet features; auth and headless verbs run on
Linux.

Design invariants an agent can rely on:

- Read-only verbs never mutate a session. Inventory and summaries are safe to
  call at any time.
- Every mutating verb is dry-run by default; `--execute` is required to act.
- Prompt injection targets only an idle tab with a proven-empty editor; busy
  targets queue in a bounded inbox; ambiguous resolution fails closed.
- Unknown outcomes are terminal for automation: a `delivery_unknown` is never
  auto-retried. Inspect before any retry.
- No secrets in output: token values, auth paths, and transcript bodies never
  appear in receipts.

## Conventions for structured output

Every verb supports `--json` (alias `--ai`). Receipts share these fields:

- `schema` — versioned contract name, e.g. `cait.handoff.v1`.
- `status` — `ok` | `warning` | `blocked`.
- `reason_code` — machine-stable snake_case explanation, e.g.
  `handoff_delivered_to_idle_tab`, `ambiguous_target`, `busy_target_queued`.
- `next_action` — what the caller should do next, e.g. `observe_target`,
  `none`, `inspect_before_retry`.
- Mutation flags — booleans such as `session_mutated`, `prompt_delivered`;
  absent means false, never unknown.

Delivery states form a fixed ladder (weakest to strongest evidence):

    queued_not_sent        accepted into the inbox; nothing delivered
    submitted_exact_tab    one guarded submission to the exact terminal
    accepted_exact_turn    provider accepted the turn (proven)
    completed_headless_turn provider completed a headless turn (proven)
    delivery_unknown       interrupted; terminal for automation

Treat `submitted_exact_tab` as delivery evidence but not acceptance evidence.
Only the two `accepted`/`completed` states prove the provider took the work.

## Receipt schema examples

### cait.handoff.v1

    {
      "schema": "cait.handoff.v1",
      "target": "billing-e2e · 019ebe1e…",       // resolved name · session uuid
      "route": "iterm_idle",                      // iterm_idle | inbox_queue
      "delivery_state": "delivered",
      "reason_code": "handoff_delivered_to_idle_tab",
      "session_mutated": true,
      "prompt_delivered": true,
      "next_action": "observe_target"
    }

Busy target variant: `route: "inbox_queue"`, `delivery_state: "queued"`,
`session_mutated: false`, `next_action: "none"` — the inbox holds it with a
TTL and supersession rules.

### cait.auth-rotate.v1

    {
      "schema": "cait.auth-rotate.v1",
      "selected": "max-main",                     // account label, never a token
      "capacity": "HIGH",                         // HIGH | MED | LOW | EMPTY
      "weekly_left_pct": 91,
      "previous_backed_up": true,
      "reason_code": "rotated_to_healthiest",
      "next_action": "none"
    }

### cait.session-recovery.v1

    {
      "schema": "cait.session-recovery.v1",
      "target": "auth-service · 019ffd1c…",
      "route": "same_tab",
      "delivery_state": "delivered",
      "reason_code": "resumed_exact_session",
      "context_preserved": true,
      "next_action": "observe_target"
    }

## Verb reference (one line + agent notes)

- `cait active [N]` — list sessions with account + working state. Read-only,
  snapshot-cached; add `--probe` only when freshness changes a decision (it
  spends a small amount of provider quota).
- `cait summary <name|uuid>` — redacted latest-progress summary, local or over
  SSH to registered workstations. Read-only. Honest freshness: results are
  labeled LIVE, CACHED, or STALE — report the label, do not upgrade it.
- `cait handoff [codex:|claude:]<target> --prompt-file <path>` — deliver one
  bounded prompt. Dry-run default; `--execute` to act. Never embed the prompt
  in the command line; use a file.
- `cait inbox <list|deliver|triage|cancel|resolve|clean>` — manage queued work.
- `cait auth <status|list|save|use|rotate|usage|capacity|burn>` — accounts and
  capacity. `usage --probe` is live and costs quota; cached reads are free.
- `cait resume|fork <name>` — exact-session recovery with UUID disambiguation.
- `cait doctor` — read-only health aggregate; safe to run anytime.

Planned (v0.4, design preview — do not call yet): `cait dash`, `cait map`,
`cait brain` render fleet, focus, and advisory-judgment TUIs from the same
receipt streams documented above.

## How an agent should behave

1. Observe before acting: `active` → `summary` before any `handoff`.
2. Preview first: run the mutating verb without `--execute`, inspect the plan,
   then execute.
3. Respect the ladder: only `accepted_*`/`completed_*` states prove work
   landed. `delivery_unknown` means stop and inspect — never blind-retry.
4. Never work around a fail-closed block. A `blocked` status with a
   reason_code is an answer, not an obstacle.
5. Do not attempt to read transcripts, tokens, or auth paths through cait; the
   tool will not emit them and asking is a smell.

## Links

- Short reference: /llms.txt
- Interactive tour (the verbs, drivable in a browser terminal): /tour
- Repository: https://github.com/msualp/collaborait
- Skills for Claude Code / Codex: skills/ in the repository