Show HN: Hazzel – A terminal coding harness that stays small on purpose

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:

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"]

Loading

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 In practice

Understands your repo Reads, searches, lists, and globs by name (**/.py, **/.{json,toml}). Lookups like "find all test files" answer locally with no model round trip. @path pins a file into context; /init drafts an AGENTS.md map so every session starts oriented.

Ships real changes Diff-preview editing, /undo checkpoints, shell with timeouts, !cmd & background jobs via /jobs, fetch <url> for docs, @image.png for vision-capable models.

Speaks fluent git /status · /diff --staged · /review · /commit (auto-drafted Conventional message) · /log — reads run instantly, zero LLM round-trip.

Extends without lock-in Minimal MCP stdio client — standard library only, any server via .hazzel/mcp.json. SKILL.md skills load on demand. Neither needs Hazzel-specific tooling to author.

Shows you the bill Provider-reported tokens parsed into real dollars, logged locally — not estimated. Live tokens · $ line every turn; /usage today|week|month --by-model, /budget.

Remembers between sessions Per-project sessions persist with /session restore. /plan on explores read-only first; /think on buys extended reasoning for hard edits.

Works in a pipeline hazzel -p "prompt" runs one turn and exits — pipe a diff in, get a summary out. --output-format json + real exit codes for CI.

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.

Group Commands

Modes /model · /plan on|off · /think on|off · /goal [@objective] · /allow

Git /status · /diff [--staged] · /review [--staged] · /commit · /log

Cost /usage [today|week|month|--by-model] · /budget

Extend /mcp [server [tool]] · /skills [name] · /init

Transcript /export · /copy · /retry · /jobs · /undo [n] · /redo · /session restore · /clear

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.

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.

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.