Hazzel

A terminal coding agent you can actually read.
Bring your own key. No subscription. Every change shown as a diff before it touches disk.

First external PR merged in v1.5.1 — good first issues are open.

Recently shipped: NO_COLOR support — piped logs and dumb terminals stay plain (#12, @DYNOSuprovo) · v1.5.3 SEO landing page · confirmation prompts accept yes — first external contribution (@Gambit-Checkmate, 1.5.1) · /review (1.5.0) · background !cmd & jobs (1.4.9) — full changelog

Try it in your project

Every agent claims transparency. Hazzel is ~10k lines of Python you can trace end to end — agent/core.py is the whole loop, tools/ is every action it can take, safety.py is the entire undo system — and it stops before every write to show you what's about to happen.

uvx hazzel                  # try it — nothing installed, no venv touched (or: pipx run hazzel)
pip install hazzel          # to keep it (or: uv tool install hazzel · pipx install hazzel)
export GROQ_API_KEY="..."   # or skip this and pick a provider inside with /model
cd your-project
hazzel

❯ Fix the failing test in tests/test_agent.py

  ● read_file   tests/test_agent.py
  ● edit_file   src/hazzel/agent/core.py
  ● run_command pytest -q — passed

Things you can say on day one

❯ /review --staged
❯ /commit
❯ what does agent/fastpath.py do — is it just caching?
❯ @screenshot.png make the nav match this

No project quiz, no config ceremony — the read-only commands answer instantly, and anything that touches disk stops at a diff first.

Why it's built this way

Most agents ask you to trust a black box. Hazzel asks you to trust three specific, inspectable mechanisms instead:

• Every write is a diff you approve, first. Shell commands too — except a small allowlist of true read-onlys (ls, cat, git status) that skip the queue.
• Every write is checkpointed, automatically. Prior bytes snapshotted to ~/.config/hazzel/undo/ (200 events, 20 per file) before anything lands. /undo restores them.
• Commands are sandboxed to your project root. git reset --hard and clean are blocked outright; raw git commit is steered into /commit with its own diff preview.

You can verify all three claims in about 200 lines: src/hazzel/safety.py, src/hazzel/tools/run_command.py.

flowchart LR
    you["you — prompt, @file, slash command"] --> repl["__main__.py"]
    repl --> loop["agent/core.py — the whole loop"]
    loop --> fast["agent/fastpath.py — zero-LLM answers for reads"]
    loop --> dispatch["agent/dispatch.py"]
    dispatch --> gate["safety.py — approve · sandbox · checkpoint"]
    gate --> tools["tools/ — 15 actions"]
    loop --> llm["providers/ — 8 backends, your key"]
    loop --> term["ui.py + formatter.py — your terminal"]

How it compares

Where Hazzel stands out, measured against the tools people actually compare it to:

Aider is excellent — this is about fit, not superiority.

What it actually does

Worked transcripts of /review, /commit, @image, background jobs, and hazzel -p live in docs/EXAMPLES.md.

Providers — bring your own key, no subscription

Eight providers, one env var each. Set the one you want and skip the in-app prompt:

Switch anytime with /model. Nothing is metered by Hazzel — you pay your provider directly, or nothing at all if you're running local.

Commands at a glance

Type / to filter live, @ to attach a file, /docs to page the full guide without leaving the terminal — see docs/EXAMPLES.md for worked transcripts.

What it's honest about not being

v1.5.3 + NO_COLOR (unreleased), early-stage. No autonomous PRs, no cloud dashboard, no session sync across machines. It doesn't replace your editor — it sits in the terminal next to it, and it stays small on purpose.

If you need a heavier, more automated agent, better options exist. If you want to see exactly what's about to happen to your files before it happens, this is built for that.

Support Hazzel

If Hazzel is useful, the cheapest support costs nothing — use it, report what breaks, or send a PR. It's free and open-source, and it plans to stay both.

If you'd rather throw money at the problem, that works too. It goes straight into maintainer time for docs, fixes, and reviews:

_{Star history}

Contributors

_{every PR lands through the same door — reviewed, CI-verified on four Python versions, credited in the release notes.}

Contributing

Issues and PRs genuinely welcome — ROADMAP.md tracks what's next, CONTRIBUTING.md has the ground rules (small, inspectable, no new deps without asking), and good first issues are labeled as such.

License

AGPL-3.0-or-later. See LICENSE.

Why AGPL? It keeps hosted clones open — if you run Hazzel as a service, share your changes back. Normal use (install it, use it at work, ship code it helped you write) is unaffected — only re-hosting Hazzel itself triggers share-alike. If the license blocks adoption at your company, open an issue — dual-licensing is on the table with enough demand.

_{Small tools stay small because people who find them useful say so.
If Hazzel is now sitting in your terminal next to your editor, a star is how the next person finds it too.}