ClaudeBoss

Cut Claude Code's own token consumption by up to 90% — delegate the heavy lifting to free opencode agents, keep Claude in the reviewer's or manager's seat.

Every step Claude Code takes itself — reading files, writing code, running commands, iterating — burns its own context window. ClaudeBoss routes that grinding work to opencode's free-tier models (OpenCode Zen, zero login required) and hands Claude back only the finished result. Claude still reviews, verifies, and decides — it just stops paying token-rate for every intermediate step.

The number, measured

On a real multi-step coding task (write a function, save it, run it, verify the output) delegated through ClaudeBoss:

| | Tokens (approx.) | |---|---| | Full opencode reasoning/tool-call trace | ~3,726 | | What Claude actually reads (final answer only) | ~44 | | Reduction | 99% |

That's one real, reproducible run — see claudeboss stats below to measure your own. We publish "up to 90%" as the honest, conservative baseline; plenty of real tasks land higher.

Install (one command)

npm install -g claudeboss
claudeboss install

claudeboss install checks for the opencode CLI (installs it via npm if missing) and confirms at least one free model is reachable. It never creates third-party accounts on your behalf — if OpenCode Zen's free tier is ever unavailable, you get exact manual steps for a free OpenRouter key instead of silent browser automation.

Via the Claude Code plugin marketplace

/plugin marketplace add xWael9/ClaudeBoss
/plugin install claudeboss@claudeboss

The three modes

| Command | Role | What it does | |---|---|---| | /claudeboss:plan | Architect | Delegates a design/scoping question to opencode's dedicated plan agent before anything gets built. | | /claudeboss:team | Pair programmer | Opencode drafts, Claude reviews like a second engineer and finishes the implementation. Two failed drafts → Claude just does it. | | /claudeboss:boss | Manager | Claude doesn't write code. It delegates, reviews, requests revisions (max 3 rounds), shows you a summary, waits for your explicit approval, then supervises deployment end-to-end. |

Track your own savings

claudeboss stats

ClaudeBoss stats
================
Runs recorded:            1
Est. tokens w/o delegation: ~3,726
Est. tokens w/ delegation:  ~44
Est. tokens saved:          ~3,682
Avg. reduction per run:     ~99%

Every claudeboss run records its estimated before/after token footprint locally (~/.claudeboss/stats.json) — nothing leaves your machine.

Stay up to date

claudeboss update

Updates both the claudeboss npm package and the opencode CLI to their latest versions in one command. Check your installed version any time with claudeboss --version. See CHANGELOG.md for release notes.

How the model gets picked

claudeboss model <task-type> queries opencode models live and ranks by task type — coding tasks prefer code-tuned free models (OpenCode Zen's own first, since they've proven more reliable for multi-step agentic work; OpenRouter free tier as fallback), prose/research prefer larger general-reasoning free models. Nothing is hardcoded to a specific model ID — free-tier catalogs change without notice, so every run re-checks what's actually available.

claudeboss model code     # -> e.g. opencode/north-mini-code-free
claudeboss model write    # -> e.g. opencode/nemotron-3-ultra-free

Manual CLI usage (outside Claude Code)

claudeboss run code "add input validation to the signup form"
claudeboss run plan "should this feature be a new service or extend the existing API?"
claudeboss run write "draft a 3-paragraph changelog entry for v0.2.0"

Boss mode + deployment

Boss mode looks for a .claudeboss.yml in your project root to know how to deploy:

deploy: ./scripts/deploy.sh

If it's missing, Claude asks once what "deploy" means for your project and suggests saving it there so future runs don't ask again.

Requirements

• Node.js >= 18

Limitations

• Free models are weaker than Claude — they're not meant to solve hard, ambiguous problems unsupervised. Both modes cap revision loops (2 in team mode, 3 in boss mode) and escalate to you instead of grinding forever.
• Runs use opencode's --auto flag to auto-approve tool permissions (file writes, bash execution) inside the task's working directory, since there's no human present during headless delegation to click "allow." This is what makes non-interactive delegation possible at all — know that opencode's worker model can read/write files and run commands unattended, scoped to wherever Claude invokes it.
• Free-tier model catalogs are provider-controlled and can shrink or change without notice. claudeboss install and every claudeboss run re-check live.
• Boss mode's deployment step assumes you've told Claude (or .claudeboss.yml) what "deploy" means for your project — it doesn't invent a deploy pipeline for you.

Contributing

Issues and PRs welcome: https://github.com/xWael9/ClaudeBoss/issues

License

MIT