Documentation.

1. Installation

Draht requires Bun (v1.1+). Install globally:

Or run without installing:

Verify the installation:

2. First run

Set up an API key and start Draht:

Or use an existing subscription (Claude Pro/Max, ChatGPT Plus/Pro, Copilot, Gemini CLI):

Draht gives the model four tools by default: read, bash, edit, and write. Type a request and the model uses these to fulfill it.

3. Providers & models

Draht supports 42 providers via the @draht/ai package, carrying 1,529 chat models in the regenerated catalog. Each provider's model list is updated with every release.

Subscriptions (OAuth)

• Anthropic Claude Pro / Max
• OpenAI ChatGPT Plus / Pro (Codex)
• GitHub Copilot
• Google Gemini CLI
• Google Antigravity

API keys

• Anthropic
• OpenAI
• Azure OpenAI
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI
• Hugging Face
• Kimi For Coding
• MiniMax

Switching models

Custom providers

Add providers via ~/.draht/agent/models.json if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions.

Virtual models

An extension can register a virtual model: a selectable entry that picks a physical model for each request, for example to send quick questions to a small model and hard problems to a large one. It shows up in /model, --model, and settings like any other model; providers only ever receive the physical model.

Prompt cache warming

An idle session periodically re-sends its cached prefix so the next turn doesn't pay a cold-cache penalty. Tune retention with DRAHT_CACHE_RETENTION.

4. Interactive mode

The Draht TUI from top to bottom:

• Startup header — shortcuts, loaded AGENTS.md files, prompt templates, skills, extensions
• Messages — your messages, assistant responses, tool calls and results
• Editor — where you type; border color indicates thinking level
• Footer — working directory, session, token usage, cost, model

Editor features

Key commands

Keyboard shortcuts

Message queue

Submit messages while the agent is working:

• Enter — queues a steering message (interrupts remaining tools)
• Alt+Enter — queues a follow-up (delivered after agent finishes)
• Escape — aborts and restores queued messages
• Alt+Up — retrieves queued messages back to editor

5. Sessions & branching

Sessions auto-save as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files.

Branching

/tree — navigate the session tree in-place. Select any previous point and continue from there. Search by typing, page with arrows. Filter modes with Ctrl+O. Press l to label entries as bookmarks.

/fork — create a new session file from the current branch point.

Compaction

Long sessions exhaust context windows. Compaction summarizes older messages while keeping recent ones.

• Manual: /compact or /compact <instructions>
• Automatic: triggers on context overflow or when approaching the limit

Compaction is lossy. The full history remains in the JSONL file; use /tree to revisit.

6. Context files

Draht loads AGENTS.md (or CLAUDE.md) at startup from:

• ~/.draht/agent/AGENTS.md — global
• Parent directories (walking up from cwd)
• Current directory

Use these for project instructions, conventions, and common commands. All matching files are concatenated into the system prompt.

System prompt

Replace the default system prompt with .draht/SYSTEM.md (project) or ~/.draht/agent/SYSTEM.md (global). Append without replacing via APPEND_SYSTEM.md.

7. Prompt templates

Reusable prompts as Markdown files. Type /name to expand.

Place in ~/.draht/agent/prompts/, .draht/prompts/, or a Draht package.

8. Skills

On-demand capability packages following the Agent Skills standard. Invoke via /skill:name or let the agent load them automatically based on trigger descriptions.

Skill directories searched: ~/.draht/agent/skills/, ~/.agents/skills/, .draht/skills/, .agents/skills/ (walking up from cwd).

9. Extensions

TypeScript modules that extend Draht with custom tools, commands, keyboard shortcuts, event handlers, and UI components.

What extensions can do

• Custom tools (or replace built-in tools entirely)
• Sub-agents and plan mode
• Custom compaction and summarization
• Permission gates and path protection
• Custom editors and UI components
• Status lines, headers, footers
• Git checkpointing and auto-commit
• SSH and sandbox execution

MCP and codemode are built in — see §15 and §14 — not something an extension needs to add.

Place in ~/.draht/agent/extensions/, .draht/extensions/, or a Draht package.

10. Themes

Built-in: dark, light. Themes hot-reload: modify the active theme file and Draht immediately applies changes.

Place custom themes in ~/.draht/agent/themes/, .draht/themes/, or a Draht package.

11. Draht packages

Bundle and share extensions, skills, prompts, and themes via npm or git.

Use -l for project-local installs. Packages install to ~/.draht/agent/git/ (git) or global npm.

Creating a package

Add a draht key to package.json:

12. SDK & programmatic usage

Embed Draht in your own apps or scripts:

RPC mode

For non-Node.js integrations, use RPC mode over stdin/stdout:

13. Model router

Role-based model selection with ordered fallback chains. Direct API calls — no OpenRouter in the hot path.

Roles (architect, implement, boilerplate, quick, review, docs) map to a primary model with fallbacks, configured in .draht/router.json (project) or ~/.draht/router.json (global).

14. Codemode

For tasks that benefit from loops or branching over many tool results, the model can write a script against the active tool set instead of calling tools one at a time. The script runs in a QuickJS sandbox; nested tool calls and their results stay inside the script's execution and never enter the model's context — only the script's own output comes back.

Scripts can call every active direct, codemode, or deferred tool, carry state across calls with store()/load(), and reach the model catalog through models.*. See packages/codemode and packages/coding-agent/src/extensions/codemode.

15. MCP

A built-in Model Context Protocol client — no extension required. draht mcp configures servers and signs in to OAuth servers outside a session; running sessions pick up new credentials on their next turn.

Reads ~/.draht/agent/mcp.json (global) and, in trusted projects, .draht/mcp.json. MCP tools are exposed through codemode by default (--exposure also accepts deferred, direct, or hidden).

16. GSD workflow & built-in commands

Draht includes the GSD (Get Shit Done) workflow: slash commands, specialist subagents, and bundled skills for planning and shipping projects with TDD and DDD. The workflow is built in; it needs no separate installation.

Project lifecycle

Per-phase cycle

Session continuity

Ad-hoc

Specialist subagents

All seven are invokable through the built-in subagent tool. Use /agent <name> to route your prompts through one, or call them directly via the tool with { agent, task }, { tasks: [...] } for parallel, or { chain: [...] } for sequential pipelines.

Workflow skills

Auto-loaded when relevant; also invokable as /skill:<name>:

• gsd-workflow — complete GSD methodology reference (directory structure, cycle, hooks, config)
• tdd-workflow — red→green→refactor discipline, commit conventions, cycle violations
• ddd-workflow — bounded contexts, ubiquitous language, aggregates, domain events

Quick start — greenfield

Draht asks about the problem, audience, and MVP scope, then generates .planning/PROJECT.md, .planning/DOMAIN.md, .planning/TEST-STRATEGY.md, .planning/REQUIREMENTS.md, .planning/ROADMAP.md, and .planning/STATE.md.

Quick start — existing codebase

Per-phase cycle in practice

Run /new between steps. Each cycle step is designed to start with a clean context.

Pause and resume

Configuration

Tune the workflow hooks via .planning/config.json:

• tddMode: "strict" aborts on green: commits without a preceding red:; "advisory" logs a warning
• qualityGateStrict: true fails the gate on any lint/type/test/coverage miss
• coverageThreshold — minimum coverage percent required by the quality gate

Override a built-in

All commands ship as Markdown templates. Drop a same-named file into ~/.draht/agent/prompts/ or .draht/prompts/ to override the built-in for your user or for the project.

Also available in Claude Code

The same workflow ships as a Claude Code plugin via draht-claude: npx draht-claude install.

17. CLI reference

Basic usage

Modes

Model options

Session options

Tool & resource options

File arguments

Prefix files with @ to include in the message:

Environment variables