# Collaborait (cait)

> Open-source CLI that coordinates a fleet of AI coding sessions (OpenAI Codex,
> Claude Code) the operator already has open: read-only inventory and progress
> summaries, fail-closed handoff of bounded prompts to idle sessions, an inbox
> queue for actionable work, multi-account auth profiles with live usage
> probing and rotation, and exact-session recovery after auth/usage stops.
> macOS + iTerm2 for full fleet features; auth and headless tools run on Linux.
> Every mutating command is dry-run by default and returns a versioned JSON
> receipt. North star: AI-first, developer-friendly — agents query the same
> view models humans see; no information asymmetry. DRAFT — pre-release; names and schemas may change before v1.

## What cait is not

- Not a proxy or API relay; it drives the vendors' own CLIs and sessions.
- Not an account-sharing or limit-bypass tool; it manages credentials the
  operator already owns, and never prints token values.
- Not an autonomous orchestrator; a human (or an agent acting for one)
  invokes every verb, and busy sessions are never interrupted.

## Verbs (one line each)

- `cait` — interactive recent-session picker; resume in current tab or open tabs.
- `cait active [N]` — list recent sessions as ready-to-run summary commands.
- `cait inventory` — snapshot open iTerm agent tabs to a local cache (read-only).
- `cait summary <name|uuid>` — redacted latest-progress summary, local or over SSH.
- `cait handoff [codex:|claude:]<target>` — deliver one bounded prompt-file to a
  resolved session; idle → visible delivery, busy → inbox queue, ambiguous →
  fail closed. Dry-run default; `--execute` to act.
- `cait inbox <doctor|list|deliver|triage|cancel|resolve|clean>` — manage the
  actionable-work queue (TTL, supersession, pending caps).
- `cait delegate <target>` — one bounded no-tab turn against an exact session UUID.
- `cait auth <status|list|save|use|rotate|usage|capacity|burn|…>` — multi-account
  profile manager; `usage --probe` runs a live per-account check.
- `cait login <status|rotate|use|watch|capture|…>` — operator shortcuts over auth,
  plus the autorecovery watcher.
- `cait resume|fork <name>` — human-driven session recovery with exact-UUID
  disambiguation.
- `cait retention <inventory|plan|maintain|verify|restore|archive>` — verified
  local retention and client-encrypted cold archive of session transcripts.
- `cait doctor [--session-e2e|--handoff-e2e]` — read-only health aggregate;
  opt-in isolated end-to-end scenario tests.

## Safety contract (enforced, not advisory)

- Dry-run is the default for every mutating verb; `--execute` is explicit.
- Prompt injection targets only an idle tab with an empty editor; busy targets
  queue in the inbox; ambiguous resolution fails closed with a reason code.
- Summaries and inventory are read-only and never steer a session.
- Auth operations never print token values; switches back up prior state first.
- Interrupted deliveries become `delivery_unknown` and never auto-replay.

## Structured output

Every verb supports `--json` (alias `--ai`). Receipts carry a versioned
`schema` field (e.g. `cait.handoff.v1`), a `delivery_state`, a `reason_code`,
and a `next_action`. Treat schema names as stable contracts; additive evolution
only within a major version.

## Links

- Interactive tour (drive the verbs in a browser terminal): /tour
- Repository: https://github.com/msualp/collaborait
- Install: `brew install msualp/tap/collaborait` · `pipx install collaborait`
- Full agent reference (receipt schemas, delivery-state ladder): /llms-full.txt
- Skills for Claude Code / Codex: skills/ in the repository
- From the maker of Sociail: https://sociail.com