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. Roughly 8 MB RAM idle, 15 MB working, 36 MB binary (approximate, measured on a Linux release build: 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. Define your own opt-in agent profiles (a named model + prompt + tool-policy bundle) and switch personas mid-session with /agent.
• Self-improving project memory. Persistent per-project memory (plus a global cross-project tier for durable user preferences) and a post-session orchestrator that extracts learnings and curates memory + skills.
• Long-horizon sessions that resume where they left off. Every conversation keeps a durable, incrementally-refreshed checkpoint, anchored to a stable identity so resuming a long, compacted session recovers its live state instead of a stale snapshot. Autonomous runs can be held to a natural-language stop condition with --goal. Adapted from MiMo-Code.
• 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.
• Delegate to dirge from another agent. Run dirge mcp to expose dirge as an MCP server: a planner agent (e.g. Claude Code) hands implementation tasks to dirge on a persistent per-project session, then reviews the summary + changed files it returns.

See the full feature catalog for everything else.

No embeddings, on purpose

dirge ships no vector index: code search is plain grep delivered inline, and cross-session memory search is SQLite FTS5. A recent empirical study of agentic search — Is Grep All You Need? How Agent Harnesses Reshape Agentic Search (Sen et al., 2026) — supports these defaults:

• Inline grep beat vector retrieval for every harness/model pair tested on long-term conversational memory QA (LongMemEval) — the same task dirge's session memory and FTS5 session search are built for.
• The harness mattered as much as the retriever: moving the same model between agent stacks shifted accuracy by ~16 points. In the authors' words, retrieval in an agent loop "is really retrieval-plus-orchestration" — and the orchestration layer is where dirge invests.
• Weaker models degraded the most under vector search and under file-based result delivery that turns each hit into a multi-step read-and-integrate workflow. Inline lexical search was the most forgiving combination, which fits dirge's goal of keeping cheaper models on the rails.

The study covers conversational memory, not code semantics. For structural code questions dirge reaches for tree-sitter semantic tools and LSP rather than embeddings.

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

Or install a prebuilt binary with Homebrew (macOS + Linux):

brew install dirge-code/dirge/dirge
# equivalently: brew tap dirge-code/dirge && brew install dirge

Homebrew also makes upgrades a one-liner (brew upgrade dirge), and on macOS it installs without the Gatekeeper quarantine prompt you'd get from double-clicking a downloaded tarball.

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

# Resume a specific session by id/prefix — or create one with that exact id
# if it doesn't exist yet (a stable id for scripting and the shell plugin)
dirge --session my-refactor

# Browse and pick a session interactively
dirge -r

# Run dirge as an MCP server so another agent can delegate tasks to it
# (register with `claude mcp add dirge -- dirge mcp`). See docs/mcp-server.md
dirge mcp

# 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.

Shell integration (the : prefix)

An optional zsh plugin lets you talk to dirge without leaving your shell. Type :<prompt> at your normal prompt and press Enter — the prompt runs through dirge headlessly, the answer prints, and you're back at the shell. Every : command in a shell shares one dirge session, so follow-ups keep context. :resume opens the full TUI on that session; :new starts a fresh one.

$ : what does this repo's build pipeline do?   # asks dirge, prints the answer
$ git status                                    # normal shell — unaffected
$ : now add a clippy step to CI                 # same session → has context

Install by sourcing it from ~/.zshrc; see shell-plugin/README.md. (It's built on dirge --session <id>, which creates the session on first use and resumes it thereafter.)

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.
• MiMo-Code by Xiaomi — a long-horizon coding agent. dirge's long-horizon session work is adapted from its design: the durable per-conversation checkpoint, incremental background checkpointing on a 20%-of-window cadence, the stable conversation identity that lets a resumed session pick up where it left off, the goal gate (a judge-verified natural-language stop condition for autonomous runs), and the global cross-project memory tier.