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: HAZZEL_CODE_THEME code-block themes + HAZZEL_NO_UPDATE_CHECK startup opt-out (1.6.2) · /allow per-tool permissions + glob path lookup — fewer prompts, fewer model calls (1.6.1) · selective undo — /undo keeps your edits, /redo reapplies (1.6.0) · compat shim removal — panels.py gone, same imports (1.5.7) · dead UI stub removal — smaller surface, same terminal (1.5.6) · background jobs wait/clear — block until done, drop finished (1.5.5) · ask-once approvals — one y/N ends it, never asked twice (1.5.4) · NO_COLOR support — piped logs 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) — full changelog

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

_{If it fixes one failing test, star it so the next person finds it too.}

❯ 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.

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. And one decision sticks: approve or deny once per turn, never re-prompted for the same call.
• Every write is checkpointed, automatically. Prior bytes snapshotted to ~/.config/hazzel/undo/ (200 events, 20 per file) before anything lands. /undo reverts only the agent's hunks and keeps edits you made afterwards (preview to look first, --force for the old blind restore, /redo to reapply).
• 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/ — 16 actions"]
    loop --> llm["providers/ — 8 backends, your key"]
    loop --> term["ui/ package + formatter.py — your terminal"]

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

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

In hazzel -p "prompt" --output-format json, a successful turn emits {"success": true, "response": "...", "model": "...", "usage": {...}}. A missing API key, failed turn, connection failure or cancellation emits one JSON object on stdout: {"success": false, "error": "...", "exit_code": 2}. The error is non-empty and exit_code matches the process status: 1 for a failed turn, 2 for a missing key, or 130 for cancellation. Human-readable diagnostics remain on stderr; text mode is unchanged.

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

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

Set HAZZEL_NO_UPDATE_CHECK=1 to skip the interactive startup PyPI check without reading or writing its cache. Leave it unset or blank to keep the daily check.

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

• HAZZEL_CODE_THEME=monokai hazzel — any installed Pygments style for code blocks.
• HAZZEL_CODE_THEME=ansi_light hazzel — for light terminals.
• Unset, blank, or unknown values fall back to github-dark.

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.

v1.6.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.

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.

_{Star history}

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

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.

Apache-2.0. 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.}