@caveman-ai/cli 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +210 -0
- package/dist/agent-mcp.js +645 -0
- package/dist/agent-skills.generated.js +113 -0
- package/dist/agents.generated.js +315 -0
- package/dist/binaries.generated.js +4 -0
- package/dist/caveman-delegate-mcp.mjs +178 -0
- package/dist/index.js +14654 -0
- package/dist/learn-tui.js +61 -0
- package/dist/native-hook-fast.js +456 -0
- package/dist/native-pack.generated.js +168 -0
- package/dist/portable-command.js +30 -0
- package/dist/portable-process.mjs +79 -0
- package/dist/practices.generated.js +3030 -0
- package/dist/recipes.generated.js +148 -0
- package/dist/reserved-verbs.generated.js +60 -0
- package/dist/verified-methods.mirror.js +8 -0
- package/package.json +39 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Julius Brussee
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# @caveman-ai/cli
|
|
2
|
+
|
|
3
|
+
The `caveman` (alias `cave`) CLI. Wrap supported coding agents so their LLM
|
|
4
|
+
traffic can use local metering and recoverable context compression:
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
caveman claude # shorthand for `caveman wrap claude`; bootstraps signed runtime on first TTY run
|
|
8
|
+
caveman learn # interactive local Setup Score + grouped top moves
|
|
9
|
+
caveman setup # show which companion binaries are installed
|
|
10
|
+
caveman stats # local spend, savings labeled `inferred`
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`caveman learn` shows animated progress, compact result cards, and a keyboard
|
|
14
|
+
menu for implementation, full detail, or the visual report. Use `--plain` for
|
|
15
|
+
stable compact text, `--all` for every sink and detector id, `--json` for automation, or
|
|
16
|
+
`caveman learn implement [claude|codex] --prompt "<focus>"` to open an agent
|
|
17
|
+
that reviews fixes one by one. Agent path installs the existing learn guide when
|
|
18
|
+
missing, never edits load-bearing findings, and asks before every edit.
|
|
19
|
+
|
|
20
|
+
Claude Code configured for Bedrock has an explicit native Runtime lane:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
CAVEMAN_WRAP_PROVIDER=bedrock \
|
|
24
|
+
AWS_REGION=us-east-1 \
|
|
25
|
+
AWS_BEARER_TOKEN_BEDROCK=… \
|
|
26
|
+
caveman wrap claude
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
IAM credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optional
|
|
30
|
+
`AWS_SESSION_TOKEN`) work too. Mantle remains opt-in with
|
|
31
|
+
`CAVEMAN_BEDROCK_ENDPOINT=mantle`; it is a distinct Bedrock endpoint contract,
|
|
32
|
+
not an alias for normal Anthropic traffic. Runtime uses the attributed
|
|
33
|
+
`/bedrock` base; Mantle uses `/bedrock/anthropic` because Claude Code appends
|
|
34
|
+
`/v1/messages` to its Mantle override.
|
|
35
|
+
|
|
36
|
+
When the gateway URL is managed, wrap merges exactly one
|
|
37
|
+
`x-cave-api-key: <CAVE_API_KEY>` into Claude Code's documented
|
|
38
|
+
`ANTHROPIC_CUSTOM_HEADERS`, preserving unrelated custom headers and replacing
|
|
39
|
+
any stale case variant. If `AWS_BEARER_TOKEN_BEDROCK` is present, wrap also
|
|
40
|
+
merges it as `x-cave-upstream-key`; otherwise a complete IAM environment is
|
|
41
|
+
encoded as
|
|
42
|
+
`AWS_ACCESS_KEY_ID:AWS_SECRET_ACCESS_KEY[:AWS_SESSION_TOKEN]`. Bearer wins when
|
|
43
|
+
both forms are present. Runtime still uses Claude Code's documented AWS
|
|
44
|
+
credential chain; there is no supported Runtime equivalent of
|
|
45
|
+
`CLAUDE_CODE_SKIP_MANTLE_AUTH`. With neither explicit environment form, no
|
|
46
|
+
upstream header is added, but Claude Code must still resolve a local AWS
|
|
47
|
+
credential/profile before the managed gateway can substitute the project's
|
|
48
|
+
stored credential. For stored-only, server-injected Claude Code auth, select the
|
|
49
|
+
opt-in Mantle lane, whose gateway auth bypass is documented. Stale
|
|
50
|
+
`x-cave-upstream-key` variants are removed so they cannot override stored
|
|
51
|
+
credentials. Newlines and incomplete IAM pairs fail before launch.
|
|
52
|
+
|
|
53
|
+
Local Bedrock wrap never adds Caveman gateway headers and keeps the inherited
|
|
54
|
+
AWS environment. This header-backed seam is repository-tested; a live Claude
|
|
55
|
+
Code → AWS smoke remains a release gate. See the official [custom-header reference](https://code.claude.com/docs/en/env-vars)
|
|
56
|
+
and [Bedrock gateway setup](https://code.claude.com/docs/en/bedrock-vertex-proxies).
|
|
57
|
+
|
|
58
|
+
## What this package is (and is not)
|
|
59
|
+
|
|
60
|
+
This npm package ships **only the JavaScript front-end** — one CLI entrypoint
|
|
61
|
+
plus a lazy 25 KB interactive-learn chunk, with zero runtime dependencies.
|
|
62
|
+
The heavy lifting (compression, metering, streaming
|
|
63
|
+
recovery, browsing) runs in caveman's companion **Go binaries**:
|
|
64
|
+
|
|
65
|
+
| Binary | Powers |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `caveman-proxy` | `start` · `wrap` · `stats` — local compression + truthful metering |
|
|
68
|
+
| `caveman-engine` | `compress` · `shrink` · `retrieve` · `toon` · `evals` |
|
|
69
|
+
| `caveman-mcp` | agent-side recovery so streaming requests can compress |
|
|
70
|
+
| `cavemem` | local remember · recall · learned-context offload |
|
|
71
|
+
| `caveman-browse` | compressed page snapshots (optional) |
|
|
72
|
+
| `caveman-shrink` | `tools compress catalog` — tool-schema compression, lint, and recovery (optional) |
|
|
73
|
+
|
|
74
|
+
Two shrink surfaces stay explicit: `caveman tools shrink -- <command>` compresses
|
|
75
|
+
command output; `caveman tools compress catalog [lint|recover]` delegates to
|
|
76
|
+
`caveman-shrink` for MCP/OpenAI tool catalogs.
|
|
77
|
+
|
|
78
|
+
On first interactive local wrap, `caveman <agent>` installs signed runtime bundle
|
|
79
|
+
and continues same command. Explicit `CAVEMAN_*_BIN` overrides and non-interactive
|
|
80
|
+
runs stay unchanged. Without binaries CLI degrades affected commands to explicit
|
|
81
|
+
pass-through: nothing is compressed, savings report 0, and warning says why. Run
|
|
82
|
+
`caveman setup` to see what works and how to repair missing pieces.
|
|
83
|
+
|
|
84
|
+
`wrap` is the one exception to "pass-through": it points the agent's
|
|
85
|
+
`ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` at the proxy, so with no proxy listening
|
|
86
|
+
the agent's requests **fail to route** rather than passing through. An
|
|
87
|
+
interactive wrap catches this and offers to launch the agent directly instead;
|
|
88
|
+
a non-interactive wrap prints the warning and still launches, so scripted/CI
|
|
89
|
+
callers must ensure the proxy is up (or use `--no-proxy`).
|
|
90
|
+
|
|
91
|
+
## Getting the binaries
|
|
92
|
+
|
|
93
|
+
Normal install:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
npm i -g @caveman-ai/cli
|
|
97
|
+
caveman claude
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
First interactive wrap downloads key-signed release artifacts, verifies the
|
|
101
|
+
checksum manifest plus every SHA-256, installs atomically into
|
|
102
|
+
`~/.caveman/bin`, then launches the agent. Manual install/repair is
|
|
103
|
+
`caveman setup --install`.
|
|
104
|
+
|
|
105
|
+
Contributors may still build from source with
|
|
106
|
+
`./scripts/install-local-cli.sh` on macOS/Linux or
|
|
107
|
+
`pwsh -File scripts/install-local-cli.ps1` on Windows. Lookup order:
|
|
108
|
+
`CAVEMAN_*_BIN` env override → `PATH` → `~/.caveman/bin`.
|
|
109
|
+
|
|
110
|
+
## Honesty rules
|
|
111
|
+
|
|
112
|
+
- Local savings are always labeled `inferred`; `verified_savings` stays 0 until
|
|
113
|
+
an optimizer runs in active mode on real traffic.
|
|
114
|
+
- Recoverable compression: lossy transforms store original before replacement.
|
|
115
|
+
Missing safe recovery path, parse failure, or non-smaller output passes through
|
|
116
|
+
unchanged and claims nothing. `record` mode is byte-preserving.
|
|
117
|
+
|
|
118
|
+
Connected verbs (`login`, `plan`, `score`, `costs`, …) talk to Caveman Cloud
|
|
119
|
+
over HTTP and need no binaries.
|
|
120
|
+
|
|
121
|
+
Connected telemetry imports stay under existing `cloud audit` governance verb:
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
caveman cloud audit import --format langfuse traces.json
|
|
125
|
+
caveman cloud audit eval-import evidence.jsonl --dry-run
|
|
126
|
+
caveman cloud audit eval-import evidence.jsonl
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Eval JSONL accepts one canonical external-evidence object per line, at most
|
|
130
|
+
1,000 records / 4 MiB per batch. Server stamps org/project, `observed` basis,
|
|
131
|
+
and `external_observed` authority; imported evidence cannot approve rollout or
|
|
132
|
+
mint verified savings.
|
|
133
|
+
|
|
134
|
+
## Agent-native setup
|
|
135
|
+
|
|
136
|
+
Install complete native Caveman integration into Codex or Claude Code: local
|
|
137
|
+
routing, lifecycle hooks, architecture-first Core, recovery MCP, project-scoped
|
|
138
|
+
read tools, and setup/discovery/review/optimization/management skills:
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
caveman setup --agent-native codex
|
|
142
|
+
# or
|
|
143
|
+
caveman setup --agent-native claude
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
This writes an MCP command, not an access token, into the agent config. Runtime
|
|
147
|
+
requests use the existing `caveman login` credential store and still pass through
|
|
148
|
+
control-api authentication, project scope, RBAC, audit, and tenant isolation.
|
|
149
|
+
Read tools expose structured reports, Cave Plan, trace metadata/spans, and
|
|
150
|
+
experiment evidence. Agent MCP intentionally exposes no lifecycle mutation:
|
|
151
|
+
control-api needs server-authoritative transition and evidence gates first.
|
|
152
|
+
Agent-facing CLI experiment commands are read-only for same reason.
|
|
153
|
+
|
|
154
|
+
Core changes coding behavior but remains independently controllable. Compression,
|
|
155
|
+
recovery, and telemetry continue when Core is off:
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
caveman tools config get think.core
|
|
159
|
+
caveman tools config set think.core off
|
|
160
|
+
caveman tools config set think.core on
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Run `caveman doctor codex` or `caveman doctor claude` to see active Core state,
|
|
164
|
+
source, profile, and pack version. Changes affect later hook events; start a new
|
|
165
|
+
agent session to clear Core already delivered into model context. Aider's shallow,
|
|
166
|
+
static Core read cannot apply `think.core`; `caveman disable aider` removes it.
|
|
167
|
+
`caveman disable <agent>` removes native routing/hooks while preserving unrelated
|
|
168
|
+
host edits.
|
|
169
|
+
|
|
170
|
+
Agent-native setup preflights host/runtime requirements before writes, journals
|
|
171
|
+
bundle ownership, validates installed components, and rolls back failed installs.
|
|
172
|
+
Rerunning converges journal-owned drift. Remove only bundle-owned pieces and
|
|
173
|
+
restore prior skill/MCP bytes with:
|
|
174
|
+
|
|
175
|
+
```sh
|
|
176
|
+
caveman setup --agent-native codex --remove
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Inspect before install:
|
|
180
|
+
|
|
181
|
+
```sh
|
|
182
|
+
caveman tools skills list --json
|
|
183
|
+
caveman tools skills preview caveman-evidence-review
|
|
184
|
+
caveman tools skills install --suite agent-native --agent codex --no-pixel
|
|
185
|
+
caveman tools mcp install codex --server caveman-cloud
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Install any third-party skill through the official Skills CLI, then store its
|
|
189
|
+
instruction body as profitable pixel pages automatically:
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
caveman tools skills add mattpocock/skills --skill tdd --agent codex -y
|
|
193
|
+
caveman tools skills add https://github.com/vercel-labs/agent-skills --agent claude-code --global -y
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
GitHub shorthand, Git/GitLab URLs, direct skill URLs, local paths, and upstream
|
|
197
|
+
`--skill`/`--agent`/`--global`/`--list`/`--all` flags pass through unchanged.
|
|
198
|
+
Caveman forces upstream copy mode when pixelizing, converts only new or changed
|
|
199
|
+
Claude Code/Codex skills, keeps `SKILL.orig.md` for byte-exact revert, and
|
|
200
|
+
reports measured estimated-token reduction as `inferred` per invocation.
|
|
201
|
+
`--no-pixel` keeps upstream plain-text behavior. Third-party instructions and
|
|
202
|
+
resources are installed as supplied; Caveman does not security-review them.
|
|
203
|
+
Official Skills CLI telemetry behavior also applies; set
|
|
204
|
+
`DISABLE_TELEMETRY=1` to opt out upstream.
|
|
205
|
+
|
|
206
|
+
Dated local smoke on Matt Pocock's 35-skill repository converted 27 profitable
|
|
207
|
+
skills and left eight safely as text. Sum across one invocation of each
|
|
208
|
+
converted skill: 32,314 → 9,537 estimated tokens (−70% `inferred`). This is
|
|
209
|
+
estimator output, not provider-reported billing or a skill-quality benchmark;
|
|
210
|
+
see [`docs/research/skill-pixel-install-2026-08-09.md`](../../docs/research/skill-pixel-install-2026-08-09.md).
|