Metadata-Version: 2.4
Name: hazzel
Version: 1.4.6
Summary: A small terminal coding agent — bring your own keys (Groq, OpenAI, Anthropic, Mistral).
Author: Mukund Jha
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/mukundzha/hazzel
Project-URL: Repository, https://github.com/mukundzha/hazzel
Project-URL: Issues, https://github.com/mukundzha/hazzel/issues
Project-URL: Changelog, https://github.com/mukundzha/hazzel/blob/main/CHANGELOG.md
Keywords: ai-agent,coding-agent,terminal,cli,llm,developer-tools,groq,openai,anthropic,ollama
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: groq>=1.7
Requires-Dist: openai>=1.0
Requires-Dist: mistralai>=1.0
Requires-Dist: anthropic>=0.40
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="Hazzel" width="160" />
</p>

# Hazzel

A small terminal coding agent. Bring your own key.

[![PyPI](https://img.shields.io/pypi/v/hazzel)](https://pypi.org/project/hazzel/) [![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/) [![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-green)](LICENSE)

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

![Hazzel demo](assets/demo.gif)

```bash
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](LICENSE).

---

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