Migrating from v1
v2 is a complete rewrite: a single Python CLI distributed on PyPI. The npm package coderrr-cli is deprecated and the hosted backend is retired.
Switch
npm uninstall -g coderrr-cli
pipx install coderrr # or: uv tool install coderrr
coderrr config # pick a provider and model
rm ~/.coderrr/config.json # the old config; v2 uses config.tomlWhat changed
| v1 | v2 |
|---|---|
| npm i -g coderrr-cli | pipx install coderrr |
| Node CLI + hosted Python backend | Single Python CLI, no backend |
| Keys POSTed to coderrr-backend.vercel.app | Keys stay local; the CLI calls providers directly |
| Model emits a whole plan up front, blind | Agent loop: read → act → observe → repeat |
| File edits applied with no confirmation | Spec written and approved before anything is edited |
| run_command against your working tree | run_in_sandbox against an isolated copy |
| ~/.coderrr/config.json, mode 0644 | OS keyring, or config.toml at mode 0600 |
| Conversation history as memory | Spec artifacts as memory |
Command mapping
| v1 | v2 |
|---|---|
| coderrr / coderrr start | coderrr |
| coderrr exec "<request>" | coderrr run "<request>" |
| coderrr analyze "<request>" | coderrr run "<request>", then decline the plan |
| coderrr config | coderrr config |
| coderrr config --show | coderrr config show |
| coderrr config --clear | coderrr config clear |
| coderrr doctor | coderrr doctor |
| coderrr market / install / skills | coderrr skills search — skills are fetched on demand now |
| coderrr rollback | git revert; v2 never auto-commits |
Behaviour that will feel different
You approve a plan, not individual edits. v2 writes requirements.md, design.md and tasks.md into .coderrr/specs/NNN-slug/, shows you the plan, and stops. Nothing is modified until you say yes — and you can edit the spec files before approving to steer the work. See Spec-Driven Flow.
Nothing runs against your working tree. run_command is gone. Commands run in a sandbox — a scratch copy of the project by default, a container when Docker is available. coderrr doctor reports which tier is active. See Sandbox.
Skills are guidance, not code. v1 skills shipped Python tools that were installed and executed. v2 skills are markdown documents fetched when relevant and deleted after use. They add no executable capability. See Skills.
No auto-commit. v1's --auto-commit ran git add ., which swept unrelated work into [Coderrr] commits. v2 leaves version control to you.
edit_file requires an exact, unique match. The three fuzzy-matching fallbacks are gone. With a real agent loop the model reads the file before editing it, so fuzzy matching bought inaccuracy for nothing.
Config migration
There is no automatic import — the shapes differ too much. Run coderrr config once:
coderrr config # pick provider, model, key
coderrr config show # verify (the key is masked)Keys go to the OS keyring when the keyring extra is installed (pipx install 'coderrr[keyring]'), otherwise to ~/.coderrr/config.toml at mode 0600. Environment variables override both.
Delete the old file when you are done: rm ~/.coderrr/config.json
Azure AI / GitHub Models is gone
v1 reached those models through the hosted backend, which no longer exists, and the GITHUB_TOKEN setting went with it. Use OpenRouter if you want many models behind one key. See Providers.
Add specs to version control
.coderrr/specs/ is meant to be committed — it is project documentation and reviewable in pull requests. The generated .coderrr/.gitignore already excludes cache/ and session/.
What the rewrite fixed
A v1 audit found a set of issues that the rewrite closes structurally rather than patching:
| Issue in v1 | Closed by |
|---|---|
| Unconfirmed file writes | The approval gate; write tools absent until then |
| No path containment | Deterministic workspace containment with symlink resolution |
| Shell injection in the skill runner and git commit messages | The skill runner and auto-commit are both gone |
| Backend SSRF and open-proxy abuse | There is no backend |
| API keys transiting a third party | Keys go straight from your machine to the provider |
| Command steps reporting success before completion | The agent reads the real exit code from the sandbox |
| Predictable temp-file paths | Sandbox roots created mode 0700 with random names |
| PID-based termination of unrelated processes | Process-group kills scoped to what the sandbox spawned |
Retiring v1
The coderrr-backend.vercel.app deployment stays up through the v2 beta, then shuts down. The Node implementation is preserved on the v1-legacy branch if you need to read it.