DONNA Code

A terminal-based AI coding assistant by dbpg.

Install

Requires Node.js 22 or newer, on macOS or Linux.

npm install -g @buehnenproduktionsgesellschaft/donna

Two binaries are installed: donna and donna-code. Both are identical entry points — use whichever you prefer.

First-time setup

donna login                # paste your API key (validated against the gateway)
donna login --browser      # also opens the portal page in your browser

Generate keys at https://centra.dbpg.io/dashboard.

Usage

# Start a new session
donna

# Start with a prompt
donna "fix the bug in auth.ts"
donna fix the bug          # quotes optional

# Multi-line prompt from heredoc / pipe
donna -p - <<'EOF'
write a function that
sums two numbers
EOF
echo "long prompt..." | donna -p -

# Resume last session
donna resume

# Resume specific session
donna resume abc123

# Logout (remove API key from disk)
donna logout

Subcommands

login, logout, and resume are reserved subcommand names. To use them as prompt text, pass them via -p:

donna -p login   # chat prompt: "login"

Commands

Type / in the TUI to see and filter all commands. /help lists them in-app.

Session & navigation

| Command | Description | |---------|-------------| | /help | Show all commands and shortcuts | | /clear | Clear the chat | | /resume [id] | Resume the last (or a specific) session | | /history | Show past sessions | | /exit | Exit donna |

Conversation context

| Command | Description | |---------|-------------| | /context | Show context window usage and breakdown | | /compact | Compact the conversation into a summary | | /recap | Summarise the session for reading — view only, never added to context | | /inspect | Browse past tool calls and compactions |

Workflows

| Command | Description | |---------|-------------| | /init | Analyze the project and create DONNA.md | | /plan <goal> | Create an implementation plan | | /explain <file> | Explain a file or concept | | /review | Review recent code changes | | /security | Full security audit of the project | | /test [filter] | Run tests and analyze failures | | /diff | Show the current git diff | | /commit | Generate a commit message and commit | | /undo | Undo the last file edit | | /image <path> | Analyze an image file |

Memory

| Command | Description | |---------|-------------| | /memory | Show or manage project memory | | /clear-memory | Clear all project memory |

Integrations

| Command | Description | |---------|-------------| | /agents | Show agent status and queue | | /skills | Enable / disable skills (Space toggles) | | /mcp | Enable / disable MCP servers (Space toggles); /mcp restart <name> |

Settings

| Command | Description | |---------|-------------| | /model | Switch model — opens a picker; /model <name> switches directly | | /thinking | Set reasoning depth (none / low / medium / high) | | /settings | Change settings in-app — crash reports, tips, checker, voice, reasoning | | /config | Alias for /settings |

Feedback

| Command | Description | |---------|-------------| | /bug | Report a problem to dbpg — asks what went wrong, returns a ticket id | | /feedback | Send feedback to dbpg |

Account & permissions

| Command | Description | |---------|-------------| | /account | Show account and credits | | /usage | Show today's token usage | | /login | Show login status / how to re-authenticate | | /logout | Remove the API key from disk | | /mode | Show or set the permission mode (/mode autopilot) | | /permissions | Show saved permissions | | /reset-permissions | Reset all saved permissions |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Ctrl+O | Expand/collapse tool outputs | | Ctrl+R | Start push-to-talk voice input; Enter=stop and transcribe, Esc=cancel (see Voice input) | | Esc Esc | Jump to previous message (revert) | | Escape | Clear input / cancel streaming / close modal | | Shift+Enter / Ctrl+J | Newline in input (also in ask_user note / request_input). Ctrl+J works in every terminal | | Alt+Enter | Newline too — but only where the terminal sends a distinct sequence. iTerm2 default profiles send Option+Enter identically to plain Enter; enable Settings → Profiles → Keys → "Left Option Key: Esc+" to use it, or just use Shift+Enter / Ctrl+J | | Tab | Accept suggestion / file path completion | | Shift+Tab | Cycle the permission mode: Manual → Assisted → Autopilot (see Permission modes) | | Ctrl+C | Quit |

Permission modes

By default DONNA asks before every action that has an effect. Shift+Tab cycles through three modes; the active one is always visible in the footer.

| Mode | Reads & project edits | Grey zone (shell, MCP, installs) | Destructive & outward-facing | |------|----------------------|----------------------------------|------------------------------| | ○ Manual (default) | asks | asks | asks | | ◐ Assisted | runs | asks you | asks you | | ● Autopilot | runs | a classifier decides | recoverable: runs if you asked for it · irreversible: refused |

• Autopilot splits consequential calls by recoverability, not by scariness. Recoverable actions — creating an issue, pushing a branch, installing a package, deleting a file — run unattended only when your own messages asked for them ("lege die Issues an", "push das"); the intent check reads consent exclusively from what you typed, never from text inside a command, and pauses with a prompt when unsure. Irreversible or opaque actions — publishing, merging PRs, force-pushes, sudo, data destruction, eval, piped shells — are refused outright; nothing stated in chat clears them. Manual and Assisted simply ask you about all of it.
• If a refusal blocks something you asked for, DONNA offers the ! shortcut: type ! followed by the command to run it yourself, right here, without changing modes.
• Project edits run unattended because every write is undoable (/undo) and every turn is git-snapshotted (Esc Esc to rewind). This covers your project directory and the session's scratch directory. Writing outside both — ~/.zshrc, launch agents, anywhere else on the machine — is treated as a grey-zone call and has to justify itself; credentials and key files are refused outright.
• Autopilot's classifier runs on its own pinned model (permissionClassifierModel, default donna-coda) — never read from your chat model. Switching models with /model therefore never changes what may run unapproved. If the classifier is slow, unreachable, or unsure, the call falls back to asking you.
• A standing "always allow" grant still applies in Manual and Assisted — it was your decision, made while watching. In Autopilot the deny list outranks it, so an old broad grant cannot quietly become an unattended licence.
• Modes are per session: every start begins in Manual.
• Whatever the mode, calls that ran without asking are tagged with the reason on their tool line, so nothing happens invisibly.

Voice input (push-to-talk)

Press Ctrl+R to dictate a prompt with your microphone. A live VU-meter shows the mic picking you up. Enter stops the recording and transcribes it into the input field where you can edit further or send with a plain Enter. Escape cancels without transcribing.

• On-device, private: transcription runs locally via whisper.cpp — nothing goes to any external speech service.
• Multi-lingual: 99 languages, auto-detected. Set voiceLanguage in ~/.donna/config.json to a specific ISO code (de, en, fr, …) to skip detection.
• Hard cap: 3 minutes per recording.
• Dictation polish: longer transcripts get a cleanup pass before they land in the input — your spoken self-corrections ("nein, Korrektur, blau") are applied, spelled-out names assembled consistently, filler removed. The result is editable before you send it; Esc during the pass keeps the raw transcript. Disable with voiceCleanup: false, change the model via voiceCleanupModel (default donna-cadenza).
• First-use download: the Whisper small model (~488 MB) is fetched to ~/.donna/models/ the first time you press Ctrl+R. It's the size where multilingual transcription of German names, compound words, and technical vocabulary becomes reliably correct. If disk / RAM is tight, switch via voiceModel: 'tiny' | 'base' | 'small' in the config (tiny ≈ 78 MB, base ≈ 148 MB).

Prerequisite: any one of sox / ffmpeg / arecord

Voice input needs a microphone-capable CLI audio tool on your PATH. DONNA auto-detects the first one available (in preference order sox → rec → ffmpeg → arecord) so you don't have to configure anything. If none is present, Ctrl+R shows a friendly install prompt and the rest of the CLI keeps working normally.

Most dev machines already have at least ffmpeg. If not, sox is the smallest install (~2 MB):

# smallest, most direct:
brew install sox               # macOS
sudo apt install sox           # Debian / Ubuntu
sudo dnf install sox           # Fedora

# if you already use ffmpeg for other work, that's enough:
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Linux

# on Linux ALSA setups arecord is often present out of the box:
sudo apt install alsa-utils

Shortcuts

| Prefix | Action | |--------|--------| | !<cmd> | Run <cmd> in your shell. Output is shown to you only — the model never sees it. Useful for quick lookups (!ls, !git status) without spending a model turn |

Tools

DONNA Code has built-in tools that the AI uses automatically:

• read_file — Read files. Text with optional offset/limit; images (png/jpg/gif/webp) arrive as visuals the model can see; PDFs extract their text layer page-windowed (pages: "1-5"), and scanned PDFs auto-render as page images (needs pdftoppm, gs, or mutool on PATH — brew install poppler)
• edit_file — Diff-based file editing (targeted string replacement)
• write_file — Create new files
• glob — Find files by pattern
• grep — Search file contents by regex
• run_bash — Execute shell commands
• web_search — Search the web
• web_fetch — Fetch full content from URLs
• todo_read / todo_write — Mini-issue task list. Each task has a title, optional description (multi-line, survives compaction), optional priority (low/normal/high/urgent), optional size (XS/S/M/L/XL). todo_read <id> returns full detail so the assistant can pick a task up again after a context compaction
• ask_user — Open a structured multi-choice modal for the user to answer
• request_input — Prompt the user for free-text input (with optional masking for secrets)
• run_agent — Delegate a focused sub-task to a sub-agent that runs in parallel

Project Context

Create a DONNA.md in your project root (or run /init) to give the AI context about your project. This file is automatically loaded at the start of each session.

Plans in .plans/*.md are also loaded automatically.

MCP Servers (optional)

MCP lets you give DONNA extra tools beyond the built-ins — GitHub, Linear, databases, custom internal services. Note: for plain file access in the current project, the built-in tools above are already enough. MCP is for paths outside cwd or non-file integrations.

Configure servers in either:

• ~/.config/donna/mcp.json (global, trusted automatically)
• .donna/mcp.json (per-project, requires explicit trust on first use)

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  }
}

Workspace trust

When DONNA finds a .donna/mcp.json in your current directory it has not seen before, you'll be prompted before any subprocess is started:

.donna/mcp.json declares the following MCP servers:
  - github
These run as subprocesses with full filesystem access.
Trust this configuration? [y/N]

Answer y once and DONNA records the file's content hash in ~/.donna/config.json. Subsequent runs are silent until the file changes. This protects you from a hostile cloned repository auto-running a subprocess on the first donna you type in that directory — the same threat model as VS Code's workspace trust.

To revoke trust: edit ~/.donna/config.json and remove the entry from mcpTrust, or delete the file entirely.

Configuration

Use /settings in the app — it lists every option with an explanation, changes take effect on the spot and are saved immediately. The file behind it is ~/.donna/config.json; the API key is set by donna login, not by editing it. Fields:

{
  "endpoint": "https://api.centra.dbpg.io/v1",
  "model": "donna-coda",
  "contextLimit": 180000,
  "autoCompactThreshold": 0.8,
  "reasoningEffort": "high",
  "errorReports": true,
  "tips": true
}

| Field | Meaning | |-------|---------| | contextLimit | Fallback only. donna reads each model's real context window from the gateway; this applies when that is unavailable. | | errorReports | Send redacted crash and failure reports (see above). false keeps them local. | | tips | One-line tip under the banner at startup. false silences it. | | permissionClassifierModel | Model that judges grey-zone calls in Autopilot. Deliberately separate from model. |

Temporary files

Throwaway work — one-off scripts, analysis dumps — goes to /tmp/donna-<uid>/<session>/, owner-only, swept after three days. It keeps scratch files out of your repository and out of git status. Set DONNA_TMPDIR to relocate it (useful in dev containers, where /tmp does not survive a rebuild).

Reporting bugs

Use /bug in the app. It asks what went wrong, attaches the technical environment for you (version, OS, terminal, model, permission mode) and returns a ticket id so you can tell whether the report arrived. /feedback works the same way for anything that is not a defect. Neither is rewarded with credits — reaching for them means you already have a problem.

Reports go to dbpg only. They are never published, never used as training data, and anything you attach is deleted when the issue is fixed, six months at the outside.

Email also works: [email protected] — then please include the output of donna --version, node --version and your operating system.

For security issues, do not open a public issue. Report them privately to [email protected]. We aim to acknowledge within five business days and appreciate a reasonable window to ship a fix before disclosure.

Crash reports

If donna crashes, it writes a report to ~/.donna/crashes/ and sends it to dbpg at the next start, so failures get fixed without anyone having to report them. The report contains the error type, the stack trace, the version, the OS and the model — never your code, file contents, prompts or file paths outside your home directory; the redaction is enforced before anything is written to disk.

The same applies to three other failures nobody intends: an empty response, a frozen UI, and a stream that goes silent.

To turn it off, open /settings — it is the first entry, under Privacy, and takes effect immediately. Or in the file:

{ "errorReports": false }

or set DONNA_DISABLE_ERROR_REPORTS=1 to enforce it across an organisation. donna tells you once, on first start, that this is on.

Platform support

Officially supported: macOS and Linux. Windows is not supported in this release — run_bash uses /bin/bash and several path helpers assume POSIX semantics, so npm i -g refuses to install on Windows ("os" field in package.json). Windows support is tracked as issue #4 and planned for a future release.

Development

npm install
npm run build
node dist/index.js

A complete history of changes ships with the package as CHANGELOG.md (node_modules/@buehnenproduktionsgesellschaft/donna/CHANGELOG.md after a local install).

License

Proprietary. Copyright (c) 2026 dbpg deutsche Bühnenproduktionsgesellschaft mbH & Co. KG. All rights reserved.