dirac-run/dirac

Dirac – an open‑source AI coding agent

Dirac is a programmable AI assistant designed to help developers write, refactor, and manage code across large codebases. It can run inside VS Code (or any editor that supports the Agent Client Protocol), from the command line, or via any ACP‑compatible IDE such as JetBrains or Zed.

What makes Dirac different?

Feature	Why it matters
Provider‑agnostic	Works with dozens of LLM providers (OpenAI, Anthropic, Gemini, Groq, Mistral, etc.) and any custom endpoint. You keep the credentials you already have.
Goal‑mode	Give a single high‑level objective (/goal <objective>) and let Dirac keep working for hours, creating and coordinating sub‑tasks until the goal is met. You can pause, steer, or stop it at any time.
Hash‑anchored file editing	Instead of fragile search‑and‑replace, Dirac tags each line with a stable hash. Edits target the exact anchor, so they survive other nearby changes and cost far fewer tokens.
AST‑based inspection & manipulation	The agent can request an outline of a file, fetch a specific function implementation, or replace/rename symbols across the whole repository using the abstract‑syntax‑tree, not raw text.
Parallel batch operations	Multiple independent reads, searches, edits, and shell commands can be bundled into a single model response, reducing round‑trips and latency.
Sub‑agents	Separate agents can run concurrently (e.g., one researching, another editing) with their own prompts, tools, and time‑outs, while Dirac tracks freshness to avoid stale writes.
Utility model	A cheaper “utility” model can handle cheap work like context compaction, commit‑message generation, or permission checks, keeping the main model focused on heavy coding.
Low‑verbosity mode	Turn off the model’s chatter so you only see decisions, verification results and final diffs.
Permission & approval workflow	Automatic approvals can be governed by a natural‑language policy; anything uncertain is escalated to the user and logged in the transcript.
Continuity & checkpoints	Long‑running tasks are saved with checkpoints; you can resume later, restore a previous workspace state, or replay a task from a saved point.

Typical workflow

1. Install – VS Code extension, npm CLI (npm install -g dirac-cli), or add Dirac from your editor’s ACP registry.
2. Configure a provider – Pick a model and supply the API key (environment variables like OPENAI_API_KEY, ANTHROPIC_API_KEY, etc., are supported).
3. Start a session – In the UI or terminal type /goal "Add logging to all HTTP handlers".
4. Watch it work – Dirac plans tasks, inspects the AST, makes precise edits, runs tests, and reports a multi‑file diff.
5. Steer or approve – If you need a change, send a message; if a permission request appears, approve or reject according to your policy.
6. Finish – The agent verifies acceptance criteria, creates a checkpoint, and can automatically commit the changes.

Benchmarks

Dirac was compared against several open‑source agent harnesses on eight multi‑file refactoring tasks from real repositories (VS Code, Transformers, Django). Using the same gemini‑3‑flash‑preview model, Dirac:

• Completed all 8 tasks (100 % success) while the next best harness succeeded on 6‑8 tasks.
• Achieved the lowest average token cost – $0.18 per task versus $0.38‑$0.73 for competitors.

Installation quick‑start

Interface	Command / Link
VS Code / Open VSX	Install Dirac from the Visual Studio Marketplace or Open VSX.
CLI	npm install -g dirac-cli (requires Node 22‑24).
ACP editors	Install from the editor’s ACP registry or run dirac --acp.

Example CLI usage

# Authenticate once
dirac auth
# Simple analysis
ndirac "Analyze the architecture of this project"
# Goal mode – unattended
ndirac --yolo "Fix the failing tests"
# Pipe a git diff into Dirac for review
git diff | dirac "Review this"

Extensibility

• Custom tools – /new-tool <description> lets you describe a small utility; Dirac generates, compiles, validates and makes it instantly available.
• Sub‑agents – Run multiple agents in parallel, each with its own toolset and timeout.
• Repository‑aware hooks – Define path‑based rules, skills, and workflows that automatically influence every task.

Community & development

• Open source under Apache 2.0 – fork of the Cline project.
• Contributions are welcomed; see CONTRIBUTING.md for linting, testing, and build steps (npm run install:all, npm run compile).
• Star history shows steady community interest.

---

In short: Dirac is a full‑featured, provider‑agnostic AI coding agent that gives large language models the tooling they need to edit real codebases reliably, at scale, and with fine‑grained control over cost and autonomy.