![](\"https://github.com/dirac-run/dirac/blob/master/assets/media/diraccli1.png?raw=true\")
\n\n \n
\n GitHub |\n NPM |\n Discord\n
\n\n## What is Dirac?\n\nDirac is an efficiency-focused open-source coding agent built for complex, real-world codebases. It supports **dozens of providers and hundreds of models**, and combines long-running autonomous work with hash-anchored editing, AST inspection and refactoring, parallel operations, subagents, continuous steering, and configurable permission controls.\n\nThe CLI provides an interactive terminal UI as well as scriptable plain-text and JSON modes. See the [full Dirac overview](https://github.com/dirac-run/dirac#what-is-dirac) for the feature walkthrough and reproducible harness comparison.\n\n## Requirements\n\n- Node.js 22.13 through 24.x\n- npm\n\nNode.js 25 is not supported because of known memory issues.\n\n## Installation\n\n```bash\nnpm install -g dirac-cli\ndirac auth\n```\n\nFrom a source checkout, install dependencies and build the executable from the repository root:\n\n```bash\nnpm run install:all\nnpm run cli:build\nnode cli/dist/cli.mjs --help\n```\n\n## Running Dirac\n\nDirac has two terminal paths.\n\n### Interactive mode\n\nWith an interactive stdin and stdout, Dirac renders the Ink interface. Run it without a prompt to open the composer, or provide a prompt to submit the first turn immediately:\n\n```bash\ndirac\ndirac \"Analyze this codebase\"\ndirac --plan \"Design an implementation\"\n```\n\nInteractive mode supports task approvals, follow-up messages, history, settings, model selection, skills, file mentions, image paste, and task resumption. `--auto-approve-all` keeps this interface while automatically approving actions.\n\n### Goals, custom tools, and steering\n\nStart a long-running Goal directly from an interactive terminal:\n\n```bash\ndirac \"/goal Upgrade the application to the next major framework version\"\n```\n\nDirac can continue working toward that objective for hours or days, create and coordinate its own tasks, and pause when it needs input. Goals require the interactive Ink CLI; plain-text mode and ACP do not support them.\n\nBuild a reusable tool without leaving the conversation:\n\n```bash\ndirac \"/new-tool Build a workspace-scoped tool that checks our deployment status\"\n```\n\nDirac generates, compiles, validates, and smoke-tests the tool. Task-scoped tools are immediately available; workspace and global tools appear in the **Tools** settings and default to disabled until you enable them.\n\nWhile a regular task or Goal is working, type and submit another message to steer it. Dirac queues the message for the next safe model turn instead of cancelling the active work. Use `/settings` to configure low-verbosity responses, the Utility model, approval behavior, subagents, and other task features.\n\n### Standalone mode\n\nDirac uses plain output when `--yolo` or `--json` is present, stdin is piped, or either terminal stream is redirected. `--yolo` auto-approves actionable cards and is intended for unattended execution:\n\n```bash\ndirac --yolo \"Run the tests and fix failures\"\ngit diff | dirac \"Review these changes\"\ndirac --json \"List the relevant files\" > events.ndjson\n```\n\nIn plain text mode, the final result is written to stdout. Progress, tool activity, summaries, warnings, and errors are written to stderr, so stdout can be safely piped into another command. Without `--yolo`, a standalone task exits with an error if it needs an approval or user feedback.\n\nPiped bytes are preserved and placed before an optional prompt. Image-only tasks are valid.\n\n## Agent Client Protocol (ACP)\n\nDirac can run as an external coding agent in ACP-compatible editors. The ACP Registry is the recommended installation path because the editor can install and update the agent package.\n\n### Install from the ACP Registry\n\n- **JetBrains IDEs 2025.3 and later**: open **Settings → Tools → AI Assistant → Agents**, or select **Install From ACP Registry…** in the agent picker. Find Dirac and select **Install**.\n- **Zed**: open **Agent Settings → External Agents**, select **Add Agent → Install from Registry**, and install Dirac.\n\nStart a Dirac thread after installation. If the selected provider is not already configured, Dirac offers the authentication methods supported by the client:\n\n- **Configure a Dirac provider** opens a local browser page for provider, model, and API-key setup. This supports API-key providers such as DeepSeek.\n- **Sign in with ChatGPT** configures the optional ChatGPT subscription provider.\n- **Configure with environment variables** accepts explicit provider configuration from clients that support ACP environment authentication.\n- **Configure Dirac in a terminal** runs the interactive setup when the client supports ACP terminal authentication.\n\nChatGPT is not required. Dirac's provider credentials and billing are separate from the editor's own model/provider settings.\n\n### Configure DeepSeek or another provider with environment variables\n\nThe generic `DIRAC_*` variables select one provider explicitly for both Act and Plan modes:\n\n```bash\nDIRAC_PROVIDER=deepseek \\\nDIRAC_MODEL=deepseek-flash \\\nDIRAC_API_KEY=\"$DEEPSEEK_API_KEY\" \\\ndirac --acp\n```\n\n- `DIRAC_PROVIDER`: Dirac provider ID, such as `deepseek`, `anthropic`, or `openrouter`.\n- `DIRAC_MODEL`: Exact model ID for that provider.\n- `DIRAC_API_KEY`: API key for API-key providers.\n- `DIRAC_BASE_URL`: Optional custom endpoint for providers that support one.\n\nFor registry installations, enter these values through the client's environment authentication method or its per-agent environment settings. Explicit `DIRAC_*` values override persisted provider and model defaults for that ACP process.\n\n### Configure before starting the editor\n\nIf an ACP client does not render Dirac's authentication methods, configure the shared Dirac home from a terminal first:\n\n```bash\ndirac auth\n```\n\nThe next `dirac --acp` process reads that persisted configuration. When using a non-default home, pass the same `--config