Handbuch · From zero to hero

Documentation.

Installation, configuration, providers, extensions, skills, and everything Draht can be bent to do.

1. Installation

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

bun add -g @draht/coding-agent

Or run without installing:

bunx @draht/coding-agent

Verify the installation:

draht --version

2. First Run

Set up an API key and start Draht:

Set your API key (Anthropic, OpenAI, Google, etc.)
export ANTHROPIC_API_KEY=sk-ant-...
Start draht in your project directory
cd my-project
draht

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

draht
/login

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 17+ providers via the @draht/ai package. 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

Interactive model selector
Ctrl+L
Cycle through scoped models
Ctrl+P / Shift+Ctrl+P
From CLI
draht --model openai/gpt-4o "Help me refactor"
draht --model sonnet:high "Complex problem"

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.

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

Feature	How
File reference	Type `@` to fuzzy-search project files
Path completion	Tab to complete paths
Multi-line	Shift+Enter
Images	Ctrl+V to paste, or drag onto terminal
Bash commands	`!command` runs and sends output to LLM

Key Commands

Command	Description
`/login`, `/logout`	OAuth authentication
`/model`	Switch models
`/settings`	Thinking level, theme, message delivery
`/resume`	Pick from previous sessions
`/new`	Start a new session
`/tree`	Navigate session tree
`/compact`	Compress context window
`/copy`	Copy last response to clipboard
`/export`	Export session to HTML
`/share`	Upload as private GitHub gist

Keyboard Shortcuts

Key	Action
Ctrl+C	Clear editor (twice to quit)
Escape	Cancel / abort (twice for `/tree`)
Ctrl+L	Model selector
Ctrl+P	Cycle scoped models
Shift+Tab	Cycle thinking level
Ctrl+O	Collapse / expand tool output
Ctrl+T	Collapse / expand thinking blocks
Ctrl+G	External editor

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.

draht -c
Continue most recent session
draht -r
Browse and select from past sessions
draht --no-session
Ephemeral mode (don't save)

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.

~/.draht/agent/prompts/review.md
Review this code for bugs, security issues, and performance.
Focus on: {{focus}}

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.

~/.draht/agent/skills/my-skill/SKILL.md
# My Skill
Use this skill when the user asks about X.
## Steps
1. Do this
2. Then that

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.

export default function (draht: ExtensionAPI) {
 draht.registerTool({ name: "deploy", ... });
 draht.registerCommand("stats", { ... });
 draht.on("tool_call", async (event, ctx) => { ... });
}

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 server integration

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.

draht install npm:@foo/draht-tools
draht install git:github.com/user/repo
draht install https://github.com/user/repo
draht remove npm:@foo/draht-tools
draht list
draht update
draht config

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

Security: Draht packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action. Review source code before installing third-party packages.

Creating a Package

Add a draht key to package.json:

{
 "name": "my-draht-package",
 "keywords": ["draht-package"],
 "draht": {
 "extensions": ["./extensions"],
 "skills": ["./skills"],
 "prompts": ["./prompts"],
 "themes": ["./themes"]
 }
}

12. SDK & Programmatic Usage

Embed Draht in your own apps or scripts:

import { createAgentSession, SessionManager } from "@draht/coding-agent";
const { session } = await createAgentSession({
 sessionManager: SessionManager.inMemory(),
});
await session.prompt("What files are in this directory?");

RPC Mode

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

draht --mode rpc

13. Model Router Under Construction

Role-based model selection with automatic fallback. Architect tasks use Claude Opus, boilerplate uses DeepSeek. Direct API calls with no OpenRouter latency.

draht router show
draht router set architect anthropic/claude-opus-4-6
draht router set boilerplate deepseek/deepseek-coder

The router inspects task characteristics (complexity, domain, cost sensitivity) and routes to the appropriate model. Fallback chains ensure availability.

14. Invoicing Under Construction

Lexoffice API integration for German invoicing. Toggl time tracking. Generate invoices from your terminal.

draht invoice create --client "Acme GmbH" --hours 40
draht invoice send --id INV-2026-042
draht toggl sync

Built for German freelancers: proper VAT handling, Lexoffice sync, and legally compliant invoice templates.

15. Compliance Under Construction

Automated compliance checks for GDPR and EU AI Act requirements.

GDPR PII scanner — detects personal data in code and config
EU AI Act documentation — checks required documentation for AI systems
German legal templates — Impressum, Datenschutzerklaerung, AGB

draht compliance scan
draht compliance report

16. Deploy Guardian Under Construction

Pre-deploy validation and rollback automation. Runs checks before deployment and automatically rolls back on failure.

draht deploy check
draht deploy push --stage production

17. GSD Workflow & Built-in Commands

Draht ships with the GSD (Get Shit Done) methodology pre-installed: 16 slash commands, 7 specialist subagents, and 3 workflow skills for taking a project from idea to shipping with TDD and DDD discipline. Everything below is built in — no install, no config.

Project lifecycle

Command	Use
`/new-project <idea>`	Greenfield: questioning → domain model → requirements → roadmap
`/init-project <goal>`	Existing codebase: map → extract domain → roadmap
`/map-codebase`	Standalone codebase analysis (parallel architect + verifier subagents)
`/next-milestone`	Plan the next milestone after all current phases are verified

Per-phase cycle

Command	Use
`/discuss-phase N`	Capture decisions and gray areas
`/plan-phase N`	Atomic execution plans (parallel architect subagents)
`/execute-phase N`	TDD red→green→refactor (parallel implementer subagents)
`/verify-work N`	Parallel verifier + security-auditor + reviewer + quality gate

Session continuity

Command	Use
`/pause-work`	Create handoff document
`/resume-work`	Read handoff, verify state, continue
`/progress`	Show current position in the roadmap

Ad-hoc

Command	Use
`/quick <task>`	Small tracked task with TDD cycle
`/fix <bug>`	Diagnose → reproducing test → minimal fix (debugger + implementer subagents)
`/review [scope]`	Parallel code review + security audit
`/atomic-commit`	Analyze diff, split into atomic conventional commits
`/orchestrate <task>`	Decompose work and dispatch the right mix of specialist subagents

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.

Agent	Use
`architect`	Reads codebase, produces structured implementation plans
`implementer`	Writes code following TDD cycle from plan tasks
`reviewer`	Reviews changes for correctness, types, conventions, domain language
`debugger`	Reproduces and diagnoses bugs to root cause
`verifier`	Runs lint + typecheck + tests, reports results without fixing
`git-committer`	Stages and commits with conventional commit messages
`security-auditor`	Scans for injection, auth, secrets, unsafe patterns

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
/new-project a team calendar with slot-based booking

Draht will question you through problem, audience, and MVP scope, then generate .planning/PROJECT.md, .planning/DOMAIN.md, .planning/TEST-STRATEGY.md, .planning/REQUIREMENTS.md, .planning/ROADMAP.md, and .planning/STATE.md.

Quick start — existing codebase

draht
/init-project refactor the billing module

Per-phase cycle in practice

/discuss-phase 1
capture decisions
/new
/plan-phase 1
parallel architect subagents produce atomic plans
/new
/execute-phase 1
parallel implementer subagents run TDD cycles
/new
/verify-work 1
parallel verifier + security + reviewer + quality gate

Between every step, run /new to start a fresh session. This is by design — each cycle step is meant to run in a clean context.

Pause and resume

/pause-work
creates .planning/CONTINUE-HERE.md
/resume-work
reads handoff, checks state, continues

Configuration

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

{
 "hooks": {
 "coverageThreshold": 80,
 "tddMode": "advisory",
 "qualityGateStrict": false
 }
}

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.

18. CLI Reference

Basic Usage

draht [options] [@files...] [messages...]

Modes

Flag	Description
`(default)`	Interactive mode
`-p`, `--print`	Print response and exit
`--mode json`	Output all events as JSON lines
`--mode rpc`	RPC mode for process integration
`--export <in> [out]`	Export session to HTML

Model Options

Option	Description
`--provider <name>`	Provider (anthropic, openai, google, etc.)
`--model <pattern>`	Model pattern or ID (supports `provider/id`)
`--api-key <key>`	API key (overrides env vars)
`--thinking <level>`	`off`, `minimal`, `low`, `medium`, `high`, `xhigh`
`--models <patterns>`	Comma-separated patterns for Ctrl+P cycling
`--list-models [search]`	List available models

Session Options

Option	Description
`-c`, `--continue`	Continue most recent session
`-r`, `--resume`	Browse and select session
`--session <path>`	Use specific session file or partial UUID
`--no-session`	Ephemeral mode (don't save)

Tool & Resource Options

Option	Description
`--tools <list>`	Enable specific built-in tools (default: `read,bash,edit,write`)
`--no-tools`	Disable all built-in tools
`-e`, `--extension <source>`	Load extension (repeatable)
`--no-extensions`	Disable extension discovery
`--skill <path>`	Load skill (repeatable)
`--no-skills`	Disable skill discovery

File Arguments

Prefix files with @ to include in the message:

draht @prompt.md "Answer this"
draht -p @screenshot.png "What's in this image?"
draht @code.ts @test.ts "Review these files"

Environment Variables

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key
`OPENAI_API_KEY`	OpenAI API key
`GOOGLE_API_KEY`	Google Gemini API key
`DRAHT_CODING_AGENT_DIR`	Override config directory
`DRAHT_SKIP_VERSION_CHECK`	Skip version check at startup
`VISUAL`, `EDITOR`	External editor for Ctrl+G