CLAUDE.md

1# packages/cli — `caveman` CLI
2 
3TypeScript CLI (`src/index.ts`) driving the local proxy and wrapping control-api
4REST calls. Published package has zero runtime dependencies. Build emits
5`dist/index.js`, dependency-free `dist/caveman-delegate-mcp.mjs`, and a lazy
6bundled `dist/learn-tui.js` Clack chunk, then
7`scripts/shebang.mjs` adds shebang + chmod. `bin` exposes both `caveman` and `cave`. Non-secret config lives at
8`~/.caveman-cloud/config.json` (0o600); the **auth token lives in the OS keychain** (macOS
9`security`) or a `~/.caveman/credentials` (0o600) fallback — never plaintext config.
10 
11## Layout
12- `src/index.ts` — entire CLI: arg dispatch, HTTP helpers (`get`/`post`), token storage, all commands
13- `src/learn-tui.ts` — bounded interactive learn view; bundled with Clack and loaded only for a real TTY
14- `tests/*.runtime.mjs` — Node `--test` runtime tests; spawn the built binary against HTTP stubs (`providers-verify`, `wrap`, `login`, `compress`)
15- `scripts/bundle-delegate.mjs` — copies canonical dependency-free delegate server into published `dist/`
16- `scripts/bundle-tui.mjs` — bundles Clack into the self-contained learn TUI chunk
17- `scripts/shebang.mjs` — post-build: prepends shebang, marks executable
18- `package.json` — bin: `caveman`/`cave → dist/index.js`; build: registries → `tsc` → delegate/TUI bundles → shebang
19 
20## Command surface
21`caveman <agent>` (e.g. `caveman claude`) is shorthand for `caveman wrap <agent>` — any known agent id or binary name works as a top-level command; it is dispatched **last**, so real commands always shadow an agent name, and everything after the agent name goes to the agent verbatim.
22`cave` is a permanent byte-compatible bin alias. Relocated verbs keep their bare
23spellings as silent legacy aliases: no deprecation text may alter piped output.
24 
25Printed porcelain is `run`, `learn`, `login`, `status`, plus the agent shortcut.
26Local capabilities live under `caveman tools`; account- or network-dependent
27operations live under `caveman cloud`. `dev` and `deploy` are undocumented
28maintainer aliases. `tools` is capped at 15 printed verbs and `cloud` at 15;
29current counts are 15 and 14. Internal/advanced `shrink-hook`, `practices`, and
30`check` remain callable through existing paths but are unprinted, including in
31legacy `help tools --all` output.
32 
33Caveman's own Go binaries (proxy/engine/mcp/mem/browse/shrink) resolve via `cavemanBin()`: env override (`CAVEMAN_*_BIN`) → PATH → `~/.caveman/bin` (where `scripts/install-local-cli.sh` or `scripts/install-local-cli.ps1` builds them) → bare name (so missing-binary panels still trigger).
34`caveman setup` prints per-binary install status — what works, what degrades to a loud byte-safe pass-through, and the one install command — and exits non-zero when a required binary (proxy/engine/mcp/mem; browse and shrink are optional) is missing. `caveman tools compress catalog` delegates to the dedicated `caveman-shrink` binary; `caveman tools shrink` remains command-output compression. It's the anti-silent-degrade front door for npm installs (the package ships JS only); every degraded path also prints its own warning line pointing at it. Publish checklist lives in `PUBLISHING.md`.
35Local (no account): `start` (launch the proxy via `CAVEMAN_PROXY_BIN`; if the binary is missing or the port is already served it renders a status panel — build/`make dev`+live docker status/env — instead of a bare spawn error) · `wrap [agent]` (inject route and exec child; Claude, Codex, Hermes, Gemini, OpenCode, Aider, and OpenClaw launch by id; native-capable hosts get temp pack/home/config only, removed after exit; no user/project config write) · `enable|disable <agent>` (explicit user-scoped native install with atomic journal, lock, reversible owned-path restore, component doctor) · `inspect` / `why <decision-id>` (content-blind native receipt and Decision Ledger explanation) · `compress` (shells out to `caveman-engine`; byte-safe missing-binary pass-through; `inferred`) · `mcp install|uninstall [agent]` (explicit persistent recovery registration; wrap uses temporary recovery configuration only when `execute.mcp = auto` and a current local MCP binary exists; `marker-only` or `false` suppresses injection without silently removing user registrations) · `skills add <source>` (same Git/URL/local sources and flags as official `npx skills add`; download/selection stays upstream, forced copy mode lets Caveman pixelize only new/changed Claude Code/Codex `SKILL.md` bodies; resources remain untouched and third-party content remains explicitly unreviewed; `--no-pixel` opts out) · `skills import <dir|SKILL.md>` (blocked unevaluated native-skill draft; imported resources never execute) · `evals run` · `stats` · `convert`.
36Connected namespace: `whoami · projects · keys · providers · billing · score ·
37costs · plan · traces · experiments · receipts · audit · sync · agent`.
38`doctor`, `opportunities`, `snippets`, `dev`, and `deploy` remain unprinted legacy
39aliases; `status`, `plan`, and `tools sdk snippets` absorb their public jobs.
40 
41`login` polls control-api `/api/v1/auth/device/{code,token}`; `organization_id` is bound from the returned token. `CAVE_TOKEN` is the non-interactive CI path. Logged-out connected verbs print one line + exit non-zero (CI skips, never crashes).
42 
43**First-run experience** (TTY only, once per machine, marker `firstRunAt` in config): on the first interactive wrap — banner, 30-day retrospective scan (`caveman-proxy learn scan --retro`, read-only over local Claude Code/Codex session logs; base behavior pass capped at 20s, retro pass at 60s, child timeout derived as 90s including margin), count-up reveal of tokens sent / would-have-cut / rides-every-turn stream figure (sums over scanned sessions, never extrapolated; `inferred`; tokens never dollars; sent is deduped once per API response, base cut carries no ratio against sent, only the stream figure shares sent's basis), telemetry disclosure, one `[y/N]` account question (yes → device login → existing span backfill). CLI persists only the closed, content-free aggregate; login or explicit `sync` uploads it to the authenticated project's `local-scan` import lane. Prompts, outputs, paths, session rows, free-text caveats, and anonymous telemetry never enter that upload; dashboard keeps it `inferred` and separate from spend/verified savings. Every failure degrades to one dim line and the agent still launches. Replay with the **unprinted** `caveman welcome` (porcelain caps unchanged). Anonymous **telemetry defaults ON (opt-out)**: persisted v1 decisions and `DO_NOT_TRACK`/`CAVEMAN_TELEMETRY=0`/`caveman telemetry off` always win; CI/non-TTY never sends and never persists the default; the first eligible interactive run persists a stable anonymous id and prints the disclosure line.
44 
45`providers verify <conn>` → real POST `/api/v1/projects/{id}/providers/{conn}/verify` (no hardcoded status).
46 
47`plan` renders the Cave Plan in plain English (one operator voice); `--json` prints the raw response. There is **no** caveman voice / `--engineer` flag — the dual-voice was deliberately removed. Headline is labeled `basis` ("inferred"), savings are per-day — never reprojected to monthly. (honesty rule: no-fake-savings)
48 
49`learn` is summary-first: real terminals get animated progress, bounded score
50and move cards, then one keyboard action menu. `--plain` restores compact text,
51`--all` restores every sink id/class/practice/suggestion, while `--json` and
52`--md` stay complete. `learn implement [claude|codex]
53[--prompt <focus>]` installs the existing `caveman-learn` safety guide when
54missing and launches the chosen interactive agent. The guide's per-edit consent,
55load-bearing protection, re-measurement, and inferred-only rules remain binding.
56Presentation contract: [`TERMINAL_UX.md`](TERMINAL_UX.md).
57 
58## Conventions
59- Dispatch uses handler tables. Every handler receives its own rebased argv slice;
60  never read process-global argv positionally inside a handler.
61- `flag("--name", fallback)` parses named args from current invocation.
62- Tests use `node --test` (Node built-in runner); run `tsc` first, test spins a real HTTP server
63- Build: `pnpm build` (tsc + shebang); install locally: `scripts/install-local-cli.sh` (macOS/Linux) or `scripts/install-local-cli.ps1` (Windows) at repo root
64 
65## Capability promotion rule
66 
67A capability may default on only when it is byte-safe, or when protected by the
68applicable path-specific gate: managed gateway uses an eval gate; local wrap
69uses recovery + CCR — **not** an account or entitlement. There is
70no eval gate in local `run`.
71Any PR flipping a default must name the clause and path.
72 
73A verb enters porcelain only when its capability is automatic-by-default-safe
74inside `run` and users no longer need to type it. Porcelain stays capped at four
75verbs + agent shortcut + exactly two namespaces. A fifth verb, or a 16th printed
76verb in either namespace, requires a retirement decision. `record` mode is always
77pass-through.
78 
79Capability config is grouped in `~/.caveman-cloud/config.json` as `think`,
80`remember`, and `execute`. `./.caveman/config.json` may only narrow its allowlisted
81project-local keys; it cannot change `think.mode`, pixel settings, account state,
82consent, or entitlement. Resolution is default < proxy YAML < legacy `wrap` <
83global groups < project overlay < env. Env parity is knob-specific. Inspect
84per-key source with `caveman tools config get`.
85 
86## Gotchas
87- `providers verify` must NOT return a hardcoded status; the test asserts the CLI echoes the server's value (no-placeholder rule)
88- `plan` savings display must stay per-day; never multiply to monthly projection
89- Non-PAYG coverage includes Claude Pro/Max, Codex ChatGPT, Gemini OAuth, and routed compatible agents. Codex subscription mode keeps provider config ephemeral under `CODEX_HOME`, auto-installs its MCP recovery, and starts `/chatgpt/responses` in compress mode instead of forcing record/pass-through. Plain OpenAI `/responses` and Gemini `generateContent` requests with MCP explicitly disabled have no server-retrieval grammar, so they must remain byte-identical with zero compression accounting; the compression conformance matrix pins these protocol-specific fail-closed cases instead of requiring every profile to emit a CCR marker.
90- Subscription/OAuth wrap sessions (Claude Pro/Max) compress **locally only**, live zone only, and with **no account**: `CAVEMAN_WRAP_ENTITLED` is gone from both doors and from the proxy, and both doors `delete` any inherited copy so a stray export cannot resurrect it. What both doors DO stamp is the recovery path (`CAVEMAN_RECOVERY`), explicitly (`"mcp"` or empty, never inherited): `wrap` answers it from the **agent's own** MCP install (an exported `CAVEMAN_RECOVERY=mcp` can't outlive that answer — it would have the proxy elide bytes behind markers this agent has no `caveman_retrieve` tool to expand), `start` from machine-wide MCP install evidence plus an explicit `CAVEMAN_RECOVERY=mcp` counted as the operator's own opt-in, re-stamped so the disclosure line and the proxy can never disagree; the compression disclosure line prints only when recovery holds, and no-MCP says compression is off and names `caveman mcp install <agent>`. The `subscription_compress: off` operator switch stays the operator's. Their savings are **tokens only** — a seat has no per-token price, so no dollar figure may ever appear for them, locally or in the synced span (no-fake-savings). The session-savings line treats `oauth` like `subscription` (OAuth is list-price-eligible on Vertex alone) and qualifies unconditionally when its capped auth-mode window is truncated
91- Published runtime dependencies stay zero. TUI libraries must be bundled,
92  lazy-loaded, and measured; do not move them onto ordinary command startup.
93- `learn` uses bundled Clack only when stdin/stdout/stderr are TTYs. `--plain`,
94  `CAVEMAN_PLAIN=1`, `TERM=dumb`, machine modes, and pipes must never prompt.
95- Remaining terminal UX (status panels + `wrap` picker) lives in the small toolkit
96  at the bottom of `src/index.ts`. Piped/non-interactive paths remain plain; runtime
97  tests assert them.
98- Current official Skills CLI installs global Codex sources at
99  `~/.agents/skills`, despite older/direct Caveman installs using
100  `~/.codex/skills`; third-party post-install discovery must scan both.
101 
102See ../../CLAUDE.md (root)
103