AGENTS.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 `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` = `CAVE_GATEWAY_URL` or the local proxy, exec child; known agents `claude`/`codex`/`gemini`/`aider` launch by id with install detection; an unknown/unfound target shows an install hint or the wrappable list; bare `wrap` in a TTY opens an arrow-key picker) · `compress` (shells out to `caveman-engine` via `CAVEMAN_ENGINE_BIN`; byte-safe pass-through fallback if the binary is missing; `inferred`) · `toon encode|decode` (stateless JSON⇄TOON converter via the engine binary; `encode` degrades byte-safe when the engine is missing, `decode` fails loudly — it must not emit raw TOON as JSON) · `wrap --toon` (sets `CAVE_ENGINE_TOON=best-of` on the spawned proxy so it re-encodes uniform JSON the model reads — tool results — as TOON when smaller; opt-in, implies `--compress`) · `mcp install|uninstall [agent]` (register/remove the caveman_retrieve MCP tool; compress-mode wrap injects it only when `execute.mcp = auto` and a real `caveman-mcp` executable resolves — never the npx fallback — because streams are only compressible with agent-side recovery; `execute.mcp = marker-only` or `false` stops injection while existing registrations remain visible) · `evals run` (delegates to `caveman-engine evals run`, forwards its exit code) · `stats` (delegates to `caveman-proxy stats`) · `convert` (pixel-compresses installed agent skills in place: SKILL.md **body** → `SKILL.pxN.png` pages via `caveman-engine pixel render`, frontmatter stays text so discovery/triggering still works, body becomes a stub telling the agent to read the images on invocation; dirs come from registry profiles with a `skills` block — claude + codex today; converts only when image+stub est tokens < text est tokens, else untouched; original kept byte-exact as `SKILL.orig.md`, `--revert` restores; every skip is reported with its reason; savings `inferred`, per-invocation) · `skills install [caveman|caveman-learn]` (writes embedded Caveman skills and auto-pixels by default) · `skills add <source>` (accepts official `npx skills add` Git/URL/local sources and flags, delegates download/selection to that CLI in forced copy mode, then pixelizes only new/changed Claude Code or Codex skills; resources stay untouched; third-party content is explicitly unreviewed; `--no-pixel` opts out; engine failure/not-smaller stays honest plain text).
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 
43First-run retro scan persists only closed `caveman.local_scan.v1` aggregate. Login or explicit `sync` uploads it through authenticated project `format=local-scan`; prompts, outputs, paths, session rows, free-text caveats, and anonymous telemetry never enter this lane. Dashboard labels token figures `inferred` and separates them from measured spend and verified savings.
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