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.

Recently shipped: confirmation prompts accept yes — first external contribution (@Gambit-Checkmate, 1.5.1) · /review (1.5.0) · background !cmd & jobs (1.4.9) · git /commit with auto-drafted messages (1.4.8) · stdlib-only MCP client (1.4.7) — 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.

pip 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/ — 13 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

Providers — bring your own key, no subscription

Eight providers: OpenAI, Anthropic, Mistral, Gemini, DeepSeek, OpenRouter (100+ models, one key), Groq (default: openai/gpt-oss-120b) — set one env var (OPENAI_API_KEY, GROQ_API_KEY, …) and skip the prompt entirely.

Ollama runs fully local and needs no key at all. 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 for the full guide without leaving the terminal.

What it's honest about not being

v1.5.2, 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

Hazzel is free and open-source. If it finds its way into your daily terminal, you can help keep it maintained and dependency-light:

Every contribution helps fund continued development and maintenance.

Who's behind this

Mukund Jha creator

ronaldsterners

Gambit-Checkmate

Contributions land reviewed and CI-verified, and every external contributor is 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.

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.