A terminal-first AI coding assistant written in Go. Runs an in-process server (or a separate client/server pair over a Unix socket / Windows named pipe) with a rich TUI client built on Bubble Tea.
Go reimplementation, started as a fork of charmbracelet/crush with an extended feature set ported to Go.
- TUI client — chat, diff views, sessions, dialogs, inline commands, completions (Bubble Tea + Lipgloss).
- Client/server — HTTP-over-socket (or named pipe) server; JSON + SSE API at
/v1. In-process by default, orHERETIC_CLIENT_SERVER=1for a split server. - Many LLM providers — Anthropic, OpenAI, Google, Bedrock, Azure, OpenRouter, Vercel, OpenAI-compatible, Copilot (OAuth), Hyper; local providers (Ollama, LM Studio, OllamaX, LiteLLM) auto-discovered.
- Tools — content-addressed
hashlineedits, file/shell/grep/glob, LSP tools, sub-agents, andmcp_-prefixed MCP tools. - MCP auto-detect — discovers MCP servers from Claude Desktop, Cursor, and
Claude Code (
.mcp.json) configs at startup; user config always wins. - Embedded POSIX shell —
mvdan.cc/sh/v3on every platform (no bash/cygwin/WSL needed); in-processjq. - Hooks — user shell scripts on agent events (
PreToolUse), cross-platform. - Skills — embedded compile-time builtins (
heretic://skills/...), overridable by users. - LSP — manager + client (gopls by default); diagnostics feed back in.
- Team mode — multi-agent orchestration (worktrees, mailbox, eligibility).
- SQLite — WASM,
CGO_ENABLED=0, sqlc + goose. - Cross-platform — linux, darwin, windows, freebsd, openbsd, netbsd, android (amd64/arm64/386/arm).
- Bundled powers — caveman, ponytail, superpowers skills + slash commands mirrored into the binary; each builtin agent inherits a default power source on launch.
find_files and multi_grep are native Go ports of
fff's ranking + constraint syntax.
Same tool names as before; faster, with frecency ranking (frequent +
recent first), git-dirty boost, and the standard constraint syntax
(!glob, dir/, *.ext).
Heretic ships with four sibling repos mirrored into the binary at build time. Each builtin agent inherits a default power source on launch; users can override intensity with env vars or slash commands.
| Agent | Default power |
|---|---|
baldr |
ponytail (full) |
odin |
superpowers |
volund |
ponytail |
heimdall |
superpowers |
bragi |
caveman (lite) |
oracle |
superpowers |
librarian |
superpowers |
explore |
superpowers |
metis |
superpowers |
momus |
superpowers |
vidar |
superpowers |
multimodal-looker |
(no power — image-only) |
Every agent except multimodal-looker also receives the
using-superpowers meta-skill at session start.
HERETIC_PONYTAIL_INTENSITY=lite|full|ultra|offHERETIC_CAVEMAN_INTENSITY=lite|full|ultra|wenyan-*|off- Slash command:
/ponytail liteor/caveman ultra(runtime, per-session; takes precedence over env var).
- caveman — output compression ("why use many token when few do trick")
- ponytail — YAGNI ladder, "lazy senior dev" mode
- superpowers — full TDD/debug/verification methodology
- oh-my-openagent — agent prompts and categories
Mirrored weekly by .github/workflows/sync-powers.yml in the
heretic-meta repo.
Install or update the latest release binary (with checksum verification) via the install script:
curl -fsSL https://raw.githubusercontent.com/gedwolmen/heretic/main/install.sh | bashPin a version or choose a destination:
curl -fsSL https://raw.githubusercontent.com/gedwolmen/heretic/main/install.sh | bash -s -- --version v1.2.3 --install-dir "$HOME/.local/bin"The script downloads the matching archive from GitHub Releases. If no
prebuilt archive exists for your platform, it falls back to
go install github.com/gedwolmen/heretic@latest (requires Go). Re-running the
installer updates to the latest version. See --help for options.
Alternatively, from source (requires Go 1.26+):
go install github.com/gedwolmen/heretic@latesttask build # CGO_ENABLED=0, version from git
task dev # run with pprof at :6060
go run . # or go directly| Flag | Description |
|---|---|
-c, --cwd |
Working directory |
-d, --debug |
Debug mode |
-y, --yolo |
Auto-accept all permissions (dangerous) |
-s, --session |
Continue a session by ID |
-C, --continue |
Continue the most recent session |
-H, --host |
Connect to a specific server host |
Config is layered JSON: global ~/.config/heretic/heretic.json, data
~/.local/share/heretic/heretic.json, workspace <data_directory>/heretic.json.
Regenerate the schema with task schema.
task build · task test (race on) · task lint (golangci-lint v2 + log-cap
check) · task fmt (gofumpt) · task swag (OpenAPI) · task sqlc
(SQL codegen) · task schema · task record (VCR cassettes) · task release.
main.go → internal/cmd (cobra) → internal/workspace → internal/server
→ internal/backend → internal/app (+ agent.Coordinator) → internal/agent
The TUI is a client; heretic run (non-interactive) is always a client. Full
control flow, gotchas, and conventions are documented in
AGENTS.md (and internal/ui/AGENTS.md
for TUI work; docs/hooks/ for hooks).
Go 1.26 (CGO_ENABLED=0) · Bubble Tea/Lipgloss/
Chroma · charm.land/fantasy · mvdan.cc/sh/v3
· SQLite (WASM) + sqlc + goose · Cobra/fang
· MCP · LSP · gojq.
Read AGENTS.md first — build commands, lint rules (gofumpt
formatting, capitalized log messages, tidy go.mod), architecture, conventions.
Run task fmt and task lint before submitting.