dirge

A minimal, fast coding agent written in Rust — inspired by pi, opencode, and maki.

A dirge is a song to keep the dead from losing their way. It turns grief into something that is remembered. Agents are like mayflies awoken for a moment to work and to forget, with every new session effacing the old one. Dirge keeps watch over things said and done, always folding context into memory to carry past mistakes and preferences across the gulf between sessions. It sings the past forward, so that no grave need be dug twice. Dirge grieves for nothing, since nothing is truly buried under its care, and its lament is a promise that what was built here once will be remembered.

Why dirge

What sets dirge apart from other agentic editors:

• Tiny and fast. ~8 MB RAM idle, ~15 MB working, ~36 MB binary (speed-optimized: opt-level=3 + LTO) — versus ~300 MB for JS-based agents. Native Rust, no runtime.
• Built to keep weaker/cheaper models on the rails. A robust agent loop repairs malformed tool calls, validates every write through tree-sitter before it touches disk, escalates to a stronger model on repeated failure, and trips circuit breakers on non-progressing loops.
• One explainable permission engine. All authorization flows through a single Policy Decision Point with four modes, op-based rules, session allowlists, and a /why command that traces exactly which policy decided and why. See docs/permissions.md.
• Role-based multi-provider routing. Point the main loop, review, escalation, summarization, and subagent roles at different models — mix DeepSeek, GLM, Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint in one session.
• Self-improving project memory. Persistent per-project memory plus a post-session orchestrator that extracts learnings, curates memory + skills, and promotes patterns recurring across sessions.
• Code intelligence baked in. Tree-sitter semantic tools and LSP diagnostics for 10+ languages, surfaced inline so the agent fixes compile errors on the same turn.
• Extensible at runtime. A Janet plugin system hooks the full lifecycle, and Claude-compatible skills load instructions on demand.

See the full feature catalog for everything else.

Installation

The crate is published as dirge-agent (the short dirge name was already taken on crates.io). The installed command is still dirge.

# Batteries included — MCP, LSP, ACP, plugins, and every tree-sitter
# language are on by default.
cargo install dirge-agent

Want a leaner binary? Opt out of the defaults and pick only what you need:

# Minimal: just the core agent + MCP, no semantic tools / plugins / ACP
cargo install dirge-agent --no-default-features --features "loop,git-worktree,mcp,lsp"

# Core + only the languages you use
cargo install dirge-agent --no-default-features \
  --features "loop,git-worktree,mcp,lsp,semantic-rust,semantic-python"

Prebuilt binaries for Linux (glibc + static musl), macOS (Intel + Apple Silicon), and Windows are attached to each GitHub Release.

Optional: sandbox mode

Install bubblewrap for --sandbox, which runs every bash command inside an isolated environment:

# Debian/Ubuntu:  apt install bubblewrap
# Fedora:         dnf install bubblewrap
# Arch:           pacman -S bubblewrap

Quick start

# Set your API key (OpenRouter is default)
export OPENROUTER_API_KEY="[api_key]"

# Interactive session (default prompt: code)
dirge

# One-shot mode
dirge -p "Explain this project"

# Continue last session
dirge -c

# Explicit provider/model
dirge --provider openrouter --model openai/gpt-4o

# DeepSeek and GLM are first-class providers
export DEEPSEEK_API_KEY="sk-..."
dirge --provider deepseek  # defaults to deepseek-v4-pro

export GLM_API_KEY="..."
dirge --provider glm       # defaults to glm-4

# Verbose mode — debug-level dirge logs + warn-level plugin hook errors
dirge --verbose

Avoid --api-key <key> outside one-off testing — it's visible to other processes via ps and emits a startup warning. Prefer a key file, stdin, or the provider's env var:

dirge --provider openai --api-key-file /run/secrets/openai_key
pass openai-key | dirge --provider openai --api-key-stdin

Slash commands

For key bindings, the inline avatar, and tool-output display, see docs/tui.md.

Supported providers

OpenRouter (default), OpenAI, Anthropic, Gemini, DeepSeek, GLM (ZhipuAI), Ollama, and any custom OpenAI-compatible endpoint.

Providers are declared once in $XDG_CONFIG_HOME/dirge/config.json and referenced by alias from role-assignment keys (provider, review_provider, escalation_provider, summarization_provider, subagent_provider) — so each role can run on a different model. See docs/config.md for the schema, provider aliases, role-assignment table, permission rules, and MCP setup.

Documentation

License

GPL-3.0-only

Acknowledgements

This project builds on and is deeply indebted to:

• zerostack by Giuseppe Della Vedova — the original minimal coding agent that dirge was forked from. Provides the core agent architecture, permission system, TUI, and prompt infrastructure.
• maki by Tony Solomonik — a feature-rich Rust coding agent. The Claude-compatible skills system, bash tree-sitter permissions, memory tool, bang commands (!/!!), /cd command, /btw query, rewind picker, and task/subagent tool were all ported from maki.
• Hermes Agent by Nous Research — a reasoning-aware coding agent with structured thinking patterns.
• pi coding-agent by Earendil Works — a developer agent with robust tool-use and workflow automation.
• vix — a battle-tested Go coding agent. dirge's phased plan workflow (the /plan command: explore → plan → implement → reviewer-runs-code loop), the minified tree-sitter read/edit family, the hard read-before-edit gate, the thinking-stall watchdog, mandatory reason/intent fields on navigation tools, and the todo-completion nudge were all ported from vix.