hazzel

Hazzel

A small terminal coding agent. Bring your own key.

Hazzel lives in your terminal. It reads code, edits files, and runs commands — always with your approval first.

Hazzel demo

pip install hazzel
cd your-project
hazzel

Run /model, pick a provider, paste your key. Keys are stored at ~/.config/hazzel/config.json with 0600 permissions. Env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY) work too. Ollama runs local models with no key (OLLAMA_HOST overrides the default http://localhost:11434/v1).

Windows works too (PowerShell or cmd) — the full-screen menus gracefully fall back to plain prompts, no new dependencies.

❯ Fix the failing test in tests/test_agent.py

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

Why Hazzel?

Most coding agents keep getting bigger. Hazzel stays small on purpose.

The model suggests what to do. Hazzel decides whether and how to do it. Every mutation goes through you: file changes show a diff before they apply, shell commands ask first, and destructive commands stay blocked.

If you want the most feature-heavy agent, there are better options. If you want a terminal agent you can see through, that's Hazzel.

What it does

Read, search, and list your codebase. Tag files with @path to put them in context.
Create and edit files with diff preview and approval. Undo with /undo.
Run shell commands with approval and timeout, sandboxed to your project root. Read-only cmds (ls, cat…) skip approval.
Plan mode (/plan on): read-only exploration. Hazzel proposes a numbered plan, changes nothing until you run /plan off.
Think mode (/think on): lets supported models reason step-by-step before answering — costs more tokens, wins on hard edits.
Goal (/goal): pin an objective, run it with /goal run; every turn steers toward it until done.
Model thinking stays collapsed behind an Enter-to-expand prompt — peek only when curious.
Read the web: fetch <url> pulls public docs and references into context (read-only).
AGENTS.md support: Hazzel reads the repo-level AGENTS.md on startup and merges it into the system prompt so repo-specific instructions are always in context. Edits made mid-session take effect after /clear or a restart.
Multiline input: Ctrl+J for newlines, full multiline paste.
Extras: /docs prints the full usage guide, /init drafts an AGENTS.md project map, /export saves the transcript, /copy grabs the last reply, /retry re-runs your last message.
Streams responses with per-turn token usage (/usage).
One-shot scripting: hazzel -p "summarize this diff" < changes.diff runs once and prints the reply — read-only by default, -y allows writes/runs, --output-format json for scripts.
Real cost visibility: provider-reported tokens priced into dollars, persisted locally (~/.config/hazzel/usage.jsonl) across restarts — /usage today|week|month, /usage --by-model, /usage export, /budget warns (never blocks). Unknown models show token counts with cost unknown, never a guessed price.

Providers

Bring your own key. No subscription.

Groq (default: openai/gpt-oss-120b)
OpenAI
Anthropic
Mistral
Gemini
DeepSeek
OpenRouter (100+ models through one key)
Ollama (local, no key)

Switch anytime with /model.

What it is not

Early-stage (v1.4.3). Expect rough edges.

No deploys, no background agents. It doesn't replace your editor — it stays in the terminal next to it.

Contributing

Issues and pull requests welcome.

License

AGPL-3.0-or-later. See LICENSE.

If it fits your workflow, star the repo. It helps other terminal-first developers find it.

Release files for hazzel 1.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hazzel 1.4.6
File	Size	Uploaded
hazzel-1.4.6.tar.gz	362.5 kB	Sep 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hazzel 1.4.6
File	Interpreter	ABI	Platform	Reset
hazzel-1.4.6-py3-none-any.whl 110.8 kB Sep 17, 2026	Python 3	none	any	Details

Total release size: 473.4 kB

Release files / hazzel-1.4.6.tar.gz

Download URL	hazzel-1.4.6.tar.gz
Size	362.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`e9488c90a5f59ff9c464c3ad08af47a917612b374414250592afb94432ea3ca3`
BLAKE2b-256 checksum How to use checksums	`95a8bb39452cc27d1be8fa187d7f5d798f73315c2b04cb0f73ce5d93c34a9c2e`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.9`

Release files / hazzel-1.4.6-py3-none-any.whl

Download URL	hazzel-1.4.6-py3-none-any.whl
Size	110.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ce852b31350710a6b583867e9889802e2de6cd522d12a277f4481f8c887649b7`
BLAKE2b-256 checksum How to use checksums	`92b0874dbf3caa5d9e1d35094b0690489d4ef8a0ee8331d03008c754f4588c18`
Upload date	Sep 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.9`