Skip to main content

Migrating from Aider

Aider pioneered the repo map (PageRank over a tree-sitter symbol graph) and edit-format-per-model (whole / diff / udiff / editor formats). Caveman Code ships both, with the same defaults and ablation tables.

TL;DR​

# 1. Install
npm install -g @juliusbrussee/caveman-code

# 2. Use your existing API keys
export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...

# 3. Tell Caveman Code what files you'd manually /add in Aider
caveman @src/main.py @src/utils.py "Help me with this"

# 4. Use it
caveman

What maps​

AiderCaveman CodeNotes
/add <file>@file in TUIAdds to chat context
/drop <file>/dropRemoves from chat context
/run <cmd>!cmd (in TUI)Or use Bash tool directly
/diff/diffShow pending diff
/architect/architectArchitect/editor split
--map-tokens N/repomap set mapTokens=NSame default (1024)
--edit-format--edit-formatwhole/diff/udiff/editor-diff/editor-whole
.aider.conf.yml~/.cave/settings.jsonDifferent format, same options
Conventions fileCAVE.md / CLAUDE.mdRead on session start

Repo map​

Aider's repo map is best-in-class. Caveman Code matches it:

  • Tree-sitter parsers for TS/JS/Python/Go/Rust/Java/C++/Ruby/PHP.
  • Symbol graph: files = nodes, references = edges.
  • PageRank with chat-state personalization (added files + recently mentioned files = personalization vector).
  • Send signatures only; bodies on demand.
/repomap set mapTokens=2048    # bigger map
/repomap                  # show the current ranked list

Edit formats​

Auto-selected per model based on proof-bench ablation results. Override with --edit-format:

FormatDescriptionBest for
wholeReplace entire filesmall files, clean state
diffSearch/replace blocksmost tasks
diff-fencedFenced search/replacemodels that strip fences
udiffUnified diffweak models, stable across revisions
editor-diffEditor model emits diff after architectarchitect/editor split
editor-wholeEditor model emits whole filesarchitect/editor split

Caveman Code's defaults are pinned to Aider's published ablation winners and updated when new models ship. See Models.

Architect / editor split​

Same UX as Aider:

/architect set architectModel=claude-opus-4-7 editorModel=claude-haiku-4

Architect plans, editor executes. Drops cost ~3-5× on long sessions. See Plan Mode.

Differences​

Caveman Mode compression​

Aider compresses by selecting smaller context (repo map). Caveman Code additionally compresses tool output post-hoc (~85% reduction on bash, grep, file reads). The two are complementary; both are on by default.

Watch mode​

Aider's // ai! and // ai? magic comments — Caveman Code has the same with // cave! and // cave?:

caveman --watch

Trailing ! triggers code edits with cwd + comment + surrounding lines as context.

Session model​

Aider sessions are tied to a chat history file. Caveman Code sessions are JSONL files in ~/.cave/sessions/<cwd-hash>/<id>.jsonl. Branchable via /tree and /fork.

Conventions file​

Aider reads <repo>/.aider/conventions.md. Caveman Code reads CAVE.md, AGENTS.md, and CLAUDE.md in priority order, layered. Move your conventions file to one of those names and you're done.

Cost tracking​

Aider was first to surface per-message cost inline. Caveman Code does the same:

[$0.0042 (cached: $0.0001)] Sonnet 4 · 12,431 in / 412 out

/tokens opens a live breakdown. Daily totals in ~/.cave/usage.json.