| File | Owner | Purpose |
|---|---|---|
~/.claude/settings.json |
RTK + whetstone | All hooks, including whetstone's absolute .../rtk hook claude command |
~/.whetstone/settings.json |
whetstone | Global whetstone settings (Headroom telemetry/memory, default model, edit mode, Anthropic API URL) |
~/.claude/RTK.md |
RTK | RTK instructions for Claude Code context |
~/.claude/CLAUDE.md |
Claude Code | Global instructions (references @RTK.md) |
~/.headroom/models.json |
Headroom | Custom model context limits and pricing |
~/.local/share/rtk/history.db |
RTK | Token savings tracking database |
| File | Owner | Purpose |
|---|---|---|
.claude/whetstone.json |
whetstone | Manifest — provider, pinned tool versions, integration version |
.claude/commands/ |
whetstone | Slash commands (/whetstone-status, /whetstone-headroom) |
.claude/skills/ |
ICM | Skills written by icm init --mode standard |
.claude/icm.db |
ICM | Session / memory store |
STACK-SETUP.md |
whetstone setup | Per-project quick reference |
CLAUDE.md |
Claude Code | Project-specific instructions |
v3 does not bundle skills or rules. The provider (ICM) owns its own assets; whetstone only writes the v3 slash commands and the manifest. Migrating from v2? See the Migration Guide.
| Variable | Default | Purpose |
|---|---|---|
ANTHROPIC_BASE_URL |
(none) | Route API calls through Headroom proxy. Set to http://127.0.0.1:8787 |
ANTHROPIC_TARGET_API_URL |
(none) | Custom upstream Anthropic API URL the Headroom proxy targets. Whetstone exports it from the Anthropic API URL setting before launch; an externally-set value takes precedence |
OPENAI_BASE_URL |
(none) | For OpenAI-compatible tools through Headroom. Set to http://127.0.0.1:8787/v1 |
HEADROOM_LOG_LEVEL |
INFO |
Proxy logging verbosity (DEBUG, INFO, WARNING, ERROR) |
HEADROOM_PORT |
8787 |
Alternative to --port flag |
HEADROOM_BUDGET |
(none) | Daily USD spending limit |
HEADROOM_DEFAULT_MODE |
optimize |
optimize, audit (observe only), or off |
WHETSTONE_ASSETS |
(none) | Override path to assets directory |
HEADROOM_* (any) |
(varies) | External Headroom knobs (e.g. HEADROOM_TARGET_RATIO). Win over headroom_env map; HEADROOM_PORT is reserved |
whetstone settings opens an interactive TUI to edit layered settings. Each
setting can be scoped Off, Global, or Project, with project values
taking precedence over global ones.
| Setting | Effect |
|---|---|
| Headroom Telemetry | Toggle Headroom telemetry |
| Headroom Memory | Persist the --memory flag (Headroom cross-session memory) |
| Headroom Semantic Cache | Headroom replays a cached response for an identical request. An opt-out: On is the unset default; Off writes HEADROOM_CACHE_ENABLED=0 so every request reaches the model and a retry regenerates. Turn off when debugging output quality |
| API Model | Default model injected into headroom wrap claude (otherwise: newest Opus, else claude-opus-5-5). A pin that Anthropic's models list has retired or superseded draws a [WARN] line at launch naming the model, the file it lives in, and what to move to |
| Edit Mode | Claude Code --permission-mode injected into headroom wrap claude — one of acceptEdits, default, plan, bypassPermissions. When Off, no flag is injected and Claude Code uses its own default. An explicit --permission-mode on the command line always wins |
| Anthropic API URL | Custom upstream Anthropic API URL for the Headroom proxy (exported as ANTHROPIC_TARGET_API_URL) |
Values persist to:
- Global —
~/.whetstone/settings.json - Project — the
settingsblock of.claude/whetstone.json
The launch-time model-update prompt (see the CLI Reference) also writes the
project API Model when you pin a newer model. Models you permanently dismiss
from that prompt are recorded in the top-level dismissed_models array of
.claude/whetstone.json so they are not offered again for that project.
whetstone sets a small set of opinionated Headroom defaults when it launches the proxy:
HEADROOM_SAVINGS_PROFILE=agent-90(compression posture for agents)HEADROOM_CODE_AWARE_ENABLED=1(AST-aware compression for code)HEADROOM_NO_MEMORY_TOOLS=1+HEADROOM_NO_MEMORY_CONTEXT=1only when the project's memory provider is ICM (ICM owns memory)
Override any Headroom knob by adding it to a headroom_env map in
.claude/whetstone.json (project) or ~/.whetstone/settings.json (global);
project entries win over global. An externally-set HEADROOM_* env var wins
over both. HEADROOM_PORT is reserved (whetstone pins 8787) and ignored
if set via the map.
"headroom_env": { "HEADROOM_TARGET_RATIO": "0.2" }
A few keys are whetstone-owned and silently dropped from the map because they
have dedicated levers: set HEADROOM_SAVINGS_PROFILE by exporting it as an
env var before launch, and HEADROOM_TELEMETRY via the Headroom Telemetry
setting above. HEADROOM_PORT is likewise ignored. Putting any of these in the
headroom_env map has no effect.