Hierocode

Hierarchical coding with cost-aware model delegation.

Frontier models plan and review; local models write the code. Cost per task is $0 incremental on a bring-your-own-subscription setup. New in v0.4: an MCP server that lets Claude Code, Codex CLI, opencode, or any MCP-capable agent delegate drafting to your local model.

You bring: (1) Python ≥3.10, (2) a local Ollama server with at least one model pulled, and (3) one of — a Claude Pro / ChatGPT Plus subscription, an Anthropic API key, or (degraded) a second local model for planning. Details in Before you install below.

Why hierocode

Frontier-model APIs charge per token, and code generation is token-heavy. A single non-trivial refactor can consume thousands of output tokens across multiple retries, driving API costs into the dollars-per-task range quickly. Subscription plans (Claude Pro, ChatGPT Plus) are cheaper on a per-message basis but have soft quotas — burning them on code generation leaves nothing for the rest of your workday.

Hierocode solves this by letting you delegate bounded drafting work to a local model running on your own hardware via MCP (Model Context Protocol). This lets agents like Claude Code or Cursor handle the reasoning, while your local machine does the heavy lifting of writing code for $0. Hierocode stays completely read-only for safety—the host agent applies the resulting patches using its own sandboxed tooling.

For users who prefer a standalone experience, hierocode also includes a TUI pipeline that splits work by role. The planner (your Claude Pro or ChatGPT Plus subscription, or an API key) turns your task into a structured JSON work breakdown and QAs the result. The drafter (a local Ollama model) does the actual code writing for each bounded unit. The reviewer defaults to the planner tier. Planner calls are short — 5–20 k input tokens, 1–3 k output — so two or three of them barely dent a subscription quota. Drafter calls run entirely on your own hardware at $0.

Before you install

Hierocode needs three things on your machine. pip install hierocode is the last step, not the first.

1. Python ≥ 3.10

python3 --version

If older: brew install python@3.12 (macOS), sudo apt install python3.12 (Ubuntu/Debian), or https://www.python.org/downloads/ (Windows).

2. A local drafter — Ollama + at least one model

This is where the actual code gets written. Runs entirely on your hardware, $0 per call.

# Install Ollama (one-time):
#   macOS / Windows:  https://ollama.com/download   (GUI installer)
#   Linux:            curl -fsSL https://ollama.com/install.sh | sh

# Pull a drafter model (~2 GB for llama3.2:3b)
ollama pull llama3.2:3b

# Verify the Ollama server is running (most installers auto-start it):
curl -fsS http://localhost:11434/ >/dev/null && echo "ollama: ok"
# If not running: `ollama serve` (macOS/Linux) or start the tray app (Windows).

Model size the wizard picks for you based on RAM:

RAM	Recommended drafter
≤ 12 GB	`llama3.2:1b`
12–24 GB	`llama3.2:3b`
24–48 GB	`qwen2.5-coder:7b`
≥ 48 GB	`qwen2.5-coder:14b`

3. A planner — pick ONE

The planner breaks your task into sized units and QAs the drafter's output. You need exactly one of these paths configured:

Path	Cost per task	Setup
Claude Pro ($17/mo)	$0 incremental	Install Claude Code, run `claude /login`
ChatGPT Plus ($20/mo)	$0 incremental	Install Codex CLI, run `codex login`
Anthropic API key	~$0.01–0.15/task	`export ANTHROPIC_API_KEY=sk-...`

No subscription or API key? Hierocode falls back to using Ollama as the planner too. It works, but plan quality drops noticeably on non-trivial tasks. The wizard warns when this happens. Get a subscription or API key for any real use.

Quickstart — the $17 journey

Assumes the three prereqs above are satisfied and claude /login has been run.

pip install hierocode

First run

# Detect your environment and write a tailored config.
hierocode init --wizard

# Confirm roles and providers were detected correctly.
hierocode models show

# Sanity-check that providers are reachable.
hierocode doctor

# Estimate cost and message quota before committing.
hierocode run -t "add input validation to the login endpoint" --estimate

# Run the full plan → draft → QA pipeline.
hierocode run -t "add input validation to the login endpoint"

The wizard detects claude on PATH, picks it as the planner, reads your RAM to choose the right Ollama drafter model, and writes ~/.hierocode.yaml. Nothing is sent to an API until you run hierocode run (or hierocode plan).

Quickstart — the API journey

If you have ANTHROPIC_API_KEY set and no claude or codex CLI installed, the wizard still works: hierocode init --wizard detects the env var and routes the planner through the Anthropic Messages API using claude-haiku-4-5 by default. Run hierocode models set planner claude-sonnet-4-6 afterward if you want a stronger planner. All other steps are identical to the $17 journey above.

Use hierocode from Claude Code / Codex / opencode (MCP)

Hierocode provides an MCP server so any MCP-capable coding agent can delegate bounded, single-file drafting work to your local model.

In this mode, the host agent acts as the planner and reviewer. Hierocode exposes the local drafter as a tool. The MCP server profiles the local model, packs context into its envelope, gets a draft using SEARCH/REPLACE edit blocks to prevent truncating large files, and returns a unified diff. The host applies the diff itself. The MCP server never writes files.

Setup per host

Claude Code:

claude mcp add hierocode -- hierocode mcp

Codex CLI (~/.codex/config.toml):

[mcp_servers.hierocode]
command = "hierocode"
args = ["mcp"]

opencode (opencode.json):

{
  "mcp": {
    "hierocode": {
      "type": "local",
      "command": ["hierocode", "mcp"]
    }
  }
}

Headless usage

You can use the headless draft engine directly from the CLI without starting the full TUI pipeline:

hierocode draft --goal "add a docstring to the main function" --target src/app.py --json

This will run the draft process exactly like the MCP server and output a full DraftResult JSON object containing the unified diff.

Recommendation: how to use hierocode effectively

Hierocode's local drafter is a small model (typically 1B–14B parameters). It is not a substitute for a frontier model's judgment — used well, it's a way to offload mechanical work for $0; used carelessly, it produces confidently wrong diffs. A few practices make the difference:

Match the task to the tool. The right delegated task is bounded, single-file, and mechanical — boilerplate, a stub fill-in, a rename, a test that follows an obvious pattern. If a change needs cross-file reasoning or an architectural decision, do it in your host agent (Claude Code, opencode, etc.) directly rather than delegating it. This is exactly the "WHEN TO USE / WHEN NOT TO USE" guidance in the draft_code MCP tool's own docstring — read it once before delegating.

Pick a drafter model sized to your reliability needs. build_capacity_profile buckets your drafter into a tier by parameter count (micro < 2B, narrow < 5B, standard < 10B, capable < 20B, strong ≥ 20B), and the tier caps how many files and how much output it's trusted with per unit. A 3B model sits in narrow — capable of small edits, but prone to dropping surrounding code on anything underspecified. If your hardware allows it, a 7B–14B coding model (e.g. qwen2.5-coder:14b, deepseek-coder-v2:16b) is meaningfully more reliable for edit-block generation:

hierocode models set drafter qwen2.5-coder:14b

Write goals like acceptance tests, not tickets. "Add a docstring" leaves room for a small model to improvise badly. "Add the docstring \"\"\"Entry point.\"\"\" as the first line of main()'s body; do not otherwise modify the function" gives it nothing to interpret. The smaller the drafter, the less ambiguity it can absorb — spend the extra sentence.

Choose MCP vs. the standalone TUI deliberately.

Use MCP when you're already working in a host agent and want to offload one mechanical piece to your local model instead of spending the host's tokens on boilerplate — you stay the reviewer for that one diff.
Use the standalone hierocode run -t "..." pipeline for a whole task you want planned and executed end-to-end using your Claude Pro / ChatGPT Plus subscription as the $0-incremental planner and reviewer. It suits a batch of small, independent changes better than one large cohesive feature.

Never apply a draft unread. Leave policy.auto_apply off and read every diff before /apply — including in MCP mode, where your host agent is the reviewer. A weak local model will occasionally produce a diff that's syntactically valid and semantically wrong; catching that is the entire reason hierocode keeps a human (or a stronger model) in the loop instead of writing files on its own.

Architecture

hierocode run
    |
    +-- skeleton.py       AST symbol index of the repo (Python) / file list (other)
    |
    +-- capacity.py       Probe drafter model: num_ctx, RAM, GPU, tier
    |
    +-- Planner           (claude_code_cli / codex_cli / anthropic / ollama)
    |       Receives: task + skeleton + capacity profile
    |       Returns:  JSON Plan — list of TaskUnits
    |       Cache:    plan_cache keyed on (task, skeleton, planner_model, drafter_model)
    |
    +-- Dispatcher        Iterates TaskUnits
            |
            +-- Budget    Pack target + context files into drafter context window
            |
            +-- Drafter   (Ollama) — writes code for one bounded unit
            |       Returns: unified diff
            |
            +-- QA        (Planner tier) — reviews diff against acceptance criteria
                    verdict:
                      accept   -> emit diff to stdout
                      revise   -> loop back to Drafter (cap: max_revisions_per_unit)
                      split    -> re-plan the unit into sub-units
                      escalate -> planner drafts the unit directly (cap: max_escalations_per_task)

Diffs are printed to stdout; they are not applied automatically.

Supported providers

Type	Auth required	Typical role
`claude_code_cli`	`claude` binary, logged in to Pro	Planner, Reviewer
`codex_cli`	`codex` binary, logged in to Plus	Planner, Reviewer
`anthropic`	`ANTHROPIC_API_KEY` env var	Planner, Reviewer
`ollama`	none	Drafter (and fallback Planner)
`openai_compatible`	bearer token env var	Planner or Drafter
`lmstudio`	none	Drafter
`transformers_local`	none	Drafter

Model IDs in each provider:

claude_code_cli / anthropic: claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5
codex_cli: gpt-5, gpt-5-codex, o4-mini
ollama: whatever you have pulled; wizard recommends based on RAM

Cost model

The drafter is always local ($0). Only planner calls have a cost.

Planner path	Cost per task	Notes
`claude_code_cli` (Pro, $17/mo)	$0 incremental	Counts against subscription quota
`codex_cli` (Plus, $20/mo)	$0 incremental	Counts against subscription quota
`anthropic` Haiku API	~$0.01–0.03	4 calls x ~10 k input + ~2 k output
`anthropic` Sonnet API	~$0.05–0.15	4 calls x ~10 k input + ~2 k output

The 4-call estimate breaks down as:

Plan cache hit: 0 planner calls.
Plan cache miss + typical 3 QA rounds: 1 planning call + 3 QA calls = 4 calls.

Token counts use a char/4 heuristic (not tiktoken) with a 20% safety margin.

Pricing can be overridden — drop ~/.hierocode/pricing.yaml with your own model prices and subscription limits. Useful when Anthropic ships a new model before hierocode does, or when you want to track quota math for a different subscription tier. See plan.md or broker/pricing.py for the schema.

Advanced: active exploration — set routing.planner.exploration: active in your config to let Claude Code / Codex use their Read/Grep/Glob tools during planning. Plans get noticeably better; token cost goes up (still 1 message against your Pro/Plus quota, but input tokens compound within that message). Off by default to preserve the predictable cost story.

Commands

Setup

hierocode init                  # Write default ~/.hierocode.yaml
hierocode init --wizard         # Auto-detect environment, write tailored config
hierocode init --force          # Overwrite existing config
hierocode doctor                # Validate config and ping all providers

Inspection

hierocode providers list        # List configured providers and their types
hierocode models list           # Query each provider for available model names
hierocode models show           # Show planner / drafter / reviewer role bindings
hierocode resources             # Print CPU count and RAM (total / available)
hierocode workers suggest       # Suggest safe / balanced / aggressive worker counts

Execution

hierocode plan -t "..."                      # Generate and print a JSON plan (no drafting)
hierocode plan -t "..." --planner-model <m>  # Override planner model
hierocode run -t "..."                       # Full pipeline: plan -> draft -> QA
hierocode run -t "..." --estimate            # Print cost/quota estimate, then exit
hierocode run -t "..." --drafter-model <m>   # Override drafter model
hierocode run -t "..." --repo ./path         # Set repo root for skeleton builder
hierocode draft --goal "..." --target path/to/file  # Headless single-file draft (diff on stdout)
hierocode mcp                                # Run the stdio MCP server
hierocode review -t "..." --file path/to/file # Review a single file

Maintenance

hierocode models set planner claude-sonnet-4-6          # Set planner model
hierocode models set drafter llama3.2:3b                # Set drafter model
hierocode models set planner claude-haiku-4-5 -p claude_pro  # With explicit provider
hierocode cache clear                                   # Delete all cached plans
hierocode version                                       # Print installed version

Interactive TUI

Run hierocode with no arguments to enter a persistent REPL (requires a config to exist; run hierocode init --wizard first). The TUI provides slash commands for every one-shot subcommand above plus a few extras:

/run <task>                     Full plan → draft → QA pipeline, with live
                                progress panel (plan units, elapsed time,
                                token counts, quota bar).
/plan <task>                    Plan only; /plan show re-displays the last plan.
/estimate <task>                Cost/quota preview without executing.
/draft <task> <file>            Single-file escape hatch.
/review <task> <file>           Single-file review.
/diff                           Re-display the last diff.
/apply                          Apply the last diff to disk with per-file
                                confirmation (y / yes-all / skip / abort).
/usage                          Per-role token/message usage for the session,
                                with a quota bar if on a subscription path.
/models                         Show current role bindings.
/models set <role> <model>      Update routing, persists to YAML.
/cache clear                    Wipe cached plans.
/config edit                    Open ~/.hierocode.yaml in $EDITOR.
/doctor /resources /repo        Diagnostics.
/task save <name> <desc>        Save a named task alias (persisted).
/task <name>                    Run a saved alias.
/task list / /task delete <n>   Alias CRUD.
/history /clear /help /exit

Plain-text input (no leading /) can either prompt before running or dispatch directly to /run — set tui.interaction_mode in your config to prompt (default, safer) or immediate.

Configuration reference

hierocode init --wizard writes ~/.hierocode.yaml. A representative example for a Claude Pro user with 16 GB RAM:

# Generated by hierocode init --wizard
default_provider: local_ollama

providers:
  local_ollama:
    type: ollama
    base_url: http://localhost:11434
    auth:
      type: none
  claude_pro:
    type: claude_code_cli
    auth:
      type: none
  codex_plus:
    type: codex_cli
    auth:
      type: none
  anthropic_api:
    type: anthropic
    auth:
      type: bearer_env
      env_var: ANTHROPIC_API_KEY

routing:
  planner:
    provider: claude_pro
    model: claude-sonnet-4-6
  drafter:
    provider: local_ollama
    model: llama3.2:3b
  reviewer:
    provider: claude_pro
    model: claude-sonnet-4-6

policy:
  max_revisions_per_unit: 2
  max_escalations_per_task: 3
  warn_before_escalation: true

parallelization:
  default_strategy: balanced
  max_local_workers: 4
  max_remote_workers: 8

hierocode init (no wizard) writes a minimal config that points every role at local_ollama with llama3.2:3b. That works out of the box for pure-local setups but runs in degraded mode (Ollama-as-planner). Use hierocode init --wizard for any real setup so the three prereqs above are actually wired up.

v0.1 YAML files still parse — legacy keys like default_model, small_model, routing.draft_model, and routing.review_model are silently ignored. Run hierocode init --wizard --force once to upgrade cleanly.

Current limitations

Not an autonomous agent. Hierocode does not apply patches, run tests, or iterate on failures without user intervention. Every diff must be reviewed and applied manually.
Diffs are printed, not applied. The run and draft commands emit unified diffs to stdout. There is no --apply flag in v0.2.
AST skeleton is Python-only. Non-Python files are listed by name and size; their symbols are not extracted. The planner sees less context for non-Python repos.
Token counting uses a char/4 heuristic. The budget module does not use tiktoken for Ollama-side estimation; a 20% safety margin compensates but is not exact.
Single-file draft and review commands do not use the QA loop. They call the provider once and return raw output. Use hierocode run for the full pipeline.

Contributing

See CONTRIBUTING.md for development setup, linting, and test instructions.

Acknowledgements

Built with the help of Claude Opus 4.7 (Anthropic).

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github/workflows		.github/workflows
docs		docs
src/hierocode		src/hierocode
tests		tests
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Hierocode

Why hierocode

Before you install

1. Python ≥ 3.10

2. A local drafter — Ollama + at least one model

3. A planner — pick ONE

Quickstart — the $17 journey

First run

Quickstart — the API journey

Use hierocode from Claude Code / Codex / opencode (MCP)

Setup per host

Headless usage

Recommendation: how to use hierocode effectively

Architecture

Supported providers

Cost model

Commands

Setup

Inspection

Execution

Maintenance

Interactive TUI

Configuration reference

Current limitations

Contributing

Acknowledgements

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Hierocode

Why hierocode

Before you install

1. Python ≥ 3.10

2. A local drafter — Ollama + at least one model

3. A planner — pick ONE

Quickstart — the $17 journey

First run

Quickstart — the API journey

Use hierocode from Claude Code / Codex / opencode (MCP)

Setup per host

Headless usage

Recommendation: how to use hierocode effectively

Architecture

Supported providers

Cost model

Commands

Setup

Inspection

Execution

Maintenance

Interactive TUI

Configuration reference

Current limitations

Contributing

Acknowledgements

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages