Blazecode

A lightweight terminal coding agent.

Blazecode streams responses from OpenAI-compatible APIs, edits your project with a small set of tools, and keeps configuration local.

blaze (•‿•) ❯

---

Install

Linux & macOS

curl -fsSL https://raw.githubusercontent.com/thealokverse/blazecode/main/install.sh | bash

This creates an isolated venv in ~/.local/share/blazecode and links blazecode to ~/.local/bin.
Your config and sessions in ~/.blazecode are never touched.

Action	Command
Update	curl -fsSL https://raw.githubusercontent.com/thealokverse/blazecode/main/install.sh | bash
Uninstall	curl -fsSL https://raw.githubusercontent.com/thealokverse/blazecode/main/install.sh | bash -s -- --uninstall
Pin version	curl -fsSL ... | bash -s -- --version v1.3.2

Requirements: Python 3.11+, curl (or wget), tar.

Windows

In PowerShell (5.1+ or PowerShell 7):

irm https://raw.githubusercontent.com/thealokverse/blazecode/main/install.ps1 | iex

This creates an isolated venv in %LOCALAPPDATA%\blazecode and places a blazecode.cmd shim in %LOCALAPPDATA%\blazecode\bin, which is added to your user PATH.
Your config and sessions in ~/.blazecode are never touched.

Action	Command
Update	re-run the irm ... | iex line above
Uninstall (local file)	.\install.ps1 -Uninstall
Uninstall (piped)	$env:BLAZECODE_UNINSTALL = '1'; irm https://raw.githubusercontent.com/thealokverse/blazecode/main/install.ps1 | iex
Pin version	.\install.ps1 -Version 1.3.2

Requirements: Windows 10+, Python 3.11+ (winget install Python.Python.3.12 or from python.org). The installer prefers the py launcher, then falls back to python/python3.

Other install methods

# pip (from GitHub)
pip install git+https://github.com/thealokverse/blazecode.git

# uv
uv tool install git+https://github.com/thealokverse/blazecode.git

---

Quick start

blazecode                          # interactive REPL (onboarding on first run)
blazecode --resume                 # resume the most recent session directly
blazecode -p "Explain this repo"   # one-shot prompt
blazecode --version

First launch walks you through a provider (OpenAI, Anthropic, Google, OpenRouter, Groq, Z.ai, Kimi, DeepSeek, MiniMax, Ollama, or custom) and writes ~/.blazecode/config.json.

---

Features

• Streaming responses with live markdown, syntax-highlighted code, and diffs
• Multiline input: enter to send, shift+enter for a new line
• Tools: read, write, edit, bash, grep, todo (bash streams live output)
• Providers: OpenAI-compatible endpoints with curated text/code model selection
• Approvals: /approval on to confirm every tool; /approval off for autonomous runs
• Workspace trust: first visit asks before mutating a directory; separate from approvals
• Skills: optional SKILL.md folders, discovered locally and loaded on demand
• Sessions: append-only JSONL under ~/.blazecode/sessions; resume latest via blazecode --resume
• Context: repository map, compact git state, and AGENTS.md / BLAZECODE.md
• Todos: multi-step task tracing when the agent needs it
• Compaction: structured summaries with a safe fallback on long chats

Menus (/models, /provider, /resume) use Esc to go back. Ctrl+C interrupts the current operation or agent run. At the idle prompt, Ctrl+C exits.

---

Configuration

{
  "default_provider": "openai",
  "default_model": "gpt-5.6",
  "approval_mode": "on",
  "providers": [
    {
      "name": "openai",
      "base_url": "https://api.openai.com/v1",
      "api_key": "env:OPENAI_API_KEY",
      "models": ["gpt-5.6", "gpt-5.6-luna"]
    },
    {
      "name": "ollama",
      "base_url": "http://localhost:11434/v1",
      "api_key": "none",
      "models": ["qwen2.5-coder:7b"]
    }
  ]
}

Prefer env:VARIABLE for API keys. Inline keys are stored with 0600 permissions and never printed in full.

approval_mode	Behavior
on	Confirm before every tool (default, safe)
off	Autonomous: run all tools without prompts

Existing configs are migrated automatically: v2 on (autonomous) becomes off; v2 off (confirm all) becomes on. Older ask/auto/plan values normalize the same way.

---

Terminal commands

Type / for fuzzy completion.

Command	Purpose
/status	Provider, model, approval, trust, tokens, mascot
/approval on|off	Confirm every tool, or autonomous mode
/provider	Add or switch provider
/models	Switch models
/skills	List skills; /skill name loads one
/compact	Summarize older context now
/export	Export session to Markdown
/clear	Start a fresh session
/resume	Resume a saved session
/exit	Quit

---

Tools

Tool	Role
read	Read a file (offset/limit)
write	Create or replace a file
edit	Exact string replacement
bash	Foreground shell command (timeout)
grep	Regex search
todo	Session task list for multi-step work

Paths stay inside the working directory. When approval is on, every tool asks first. Untrusted directories still allow read/grep; writes, edits, and shell need a trusted workspace (asked at startup).

Project guidance is loaded from AGENTS.md or BLAZECODE.md (nearest file up to the git root, plus ~/.blazecode/AGENTS.md). Skills live in skills/*/SKILL.md (project) or ~/.blazecode/skills/*/SKILL.md (global).

---

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m blazecode

See CONTRIBUTING.md for how to help, and DEVELOPMENT.md for current direction.

---

Uninstall notes

install.sh --uninstall (Linux/macOS) removes only the program (~/.local/share/blazecode and the blazecode link).
install.ps1 -Uninstall (Windows) removes the venv (%LOCALAPPDATA%\blazecode), the blazecode.cmd shim, and its PATH entry.

Neither installer ever deletes ~/.blazecode. To wipe user data:

rm -rf ~/.blazecode      # Linux/macOS
Remove-Item -Recurse -Force ~/.blazecode   # Windows PowerShell

---

License

MIT