Hazzel

What does this agent do, and when should you use it?

Hazzel is a terminal coding agent written in Python, roughly 10k lines long, with the entire loop in agent/core.py, every action under tools/, and the undo system in safety.py. A REPL accepts prompts, @file references and slash commands; agent/fastpath.py answers read-only lookups without a model call, then agent/dispatch.py routes work to 16 tools. Every write and shell command passes through safety.py — diff preview and approval, project-root sandboxing, and automatic checkpoints of prior bytes in ~/.config/hazzel/undo/. It ships with eight provider backends (Groq, OpenAI, Anthropic, Mistral, Gemini, DeepSeek, OpenRouter, plus keyless local Ollama), so you pay your provider directly or nothing at all locally. It also includes a minimal stdlib-only MCP stdio client, on-demand SKILL.md skills, and a non-interactive hazzel -p mode with JSON output and exit codes for pipelines. The project is at v1.6.2 under Apache-2.0 and describes itself as early-stage.

After launch you get a terminal REPL: type a prompt, pin files with @path, or type / to filter commands live. The core loop reads and searches the repo (read_file, listings, glob patterns such as **/*.py), previews and applies edits (edit_file), runs shell commands with timeouts (run_command), and starts background jobs with !cmd &, managed through /jobs. Read-only requests are served locally by the fastpath without an LLM round trip. Before any write, it renders a diff and asks y/N; one decision per turn sticks. Shell commands outside a small read-only allowlist (ls, cat, git status) go through the same gate. Before each write, prior bytes are snapshotted into ~/.config/hazzel/undo/ (200 events, 20 per file); /undo reverts only the agent's hunks while keeping your later edits, and /redo reapplies. Git commands /status, /diff, /review, /commit (auto-drafted Conventional message) and /log execute locally. /usage and /budget turn provider-reported tokens into dollars, and /session save|list|restore persists per-project sessions. In pipeline mode, hazzel -p "prompt" --output-format json emits a success object with response, model and usage, or an error object carrying exit_code.

1. Terminal-first developers who want the agent to edit code but want to inspect a diff before anything lands.
2. Individual developers using their own Groq or OpenAI key without a subscription.
3. Teams running local Ollama models in restricted environments for keyless read-and-edit work.
4. CI pipelines that need a single-turn agent turn with parseable JSON and meaningful exit codes.
5. Engineers who want /review --staged and /commit to draft a Conventional commit message before pushing.
6. Users who want to roll back only the agent's changes while preserving their own later edits.

How do you install or deploy this agent?

Try it without installing anything (no venv touched):

uvx hazzel

Or:

pipx run hazzel

To keep it:

pip install hazzel

Or:

uv tool install hazzel

pipx install hazzel

Then set at least one provider key, for example:

export GROQ_API_KEY="..."

You can skip the key entirely and pick a provider inside the session with /model; local Ollama needs no key and honors OLLAMA_HOST.

How do you use this agent?

Start it inside your project:

cd your-project
hazzel

Then describe the task in plain language, for example:

❯ Fix the failing test in tests/test_agent.py

Common commands:

❯ /review --staged
❯ /commit
❯ @screenshot.png make the nav match this
❯ /model
❯ /plan on
❯ /undo

Run a single turn non-interactively:

hazzel -p "prompt" --output-format json

Print the built-in model catalog (no key, config or network needed):

hazzel --list-models

Optional environment variables:

export HAZZEL_CODE_THEME=monokai
export HAZZEL_NO_UPDATE_CHECK=1

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ