Dragent docs

Dragent is a fast, cross-platform desktop terminal for macOS and Windows that combines a block-based terminal emulator with a first-class AI coding agent. Where a traditional terminal is a passive text buffer, Dragent actively understands what you're trying to do.

• Block-based output. Every command and its output is grouped into a distinct, addressable block you can copy, re-run, filter, and share.
• Self-healing. When a command fails, Dragent diagnoses it and offers a one-click fix.
• A real agent. Plan, read and edit files, run commands with your approval, search your codebase, and use packaged skills — right in the terminal.
• Intelligent input. One input bar handles both shell commands and natural language, with ghost-text autosuggestions and rich editing.

Install

• macOS — open the .dmgand drag Dragent into Applications, then launch it. It's notarized, so it opens without a developer warning.
• Windows — run the installer, then launch Dragent from the Start menu.

First-run onboarding

The first launch walks you through four quick steps:

• Welcome.
• A short tour of what Dragent can do.
• Choose a theme (you can change it anytime in Appearance).
• Sign in through your browser — or skip and do it later.

Signing in

Dragent signs you in through your browser— there's no password to type in the app. Start sign-in from onboarding or Settings → Account, complete it in the browser, and Dragent finishes automatically. You can also bring your own model API keys or use a local model instead.

The window has three areas: a left sidebar, the main terminal in the middle, and a right project panel.

• Left sidebar — your tabs and project intelligence (detected git repo and runnable scripts). The + button opens a new tab and lets you pick a shell.
• Main terminal — the scrolling block history, with the command input pinned at the bottom (its context row shows your directory, git branch, and change counts).
• Right panel — project context: the current branch, working-tree changes, and any errors.

Open Settings with ⌘, (Windows: Ctrl,).

Instead of an endless wall of text, Dragent groups every command and its output into a block — bundling the command, working directory, status, timing, and output.

Status & the color stripe

A block shows a colored stripe: green for success, a distinct color for signal exits (e.g. Ctrl+C), and red for other failures. A red block is your cue that self-healing can help.

Block actions

Open a block's ⋯ menu (or right-click its output) to copy the command, output, or both; scroll to it; or open its inline output filter (with a regex toggle) to trim long logs without re-running. Click a header to collapse/expand it. A sticky header keeps the current command visible as you scroll long output.

Checkpoints

When you send a message to the agent, Dragent can record an in-memory checkpoint of your files, so you can restore to that point or revert the last agent turn.

The input bar handles both shell commands and natural-language requests, and decides — per keystroke — which you mean, showing a shell / agent chip. Force a mode by clicking the chip, typing /shell or /agent, or turn autodetection off in Settings.

• Syntax highlighting and multi-line editing (Shift+Enter for a newline; optional Vim keys).
• Ghost-text autosuggestions from history, cd paths, package.json scripts, Makefile targets, git branches, and a command database — accept with →.
• Path completion with Tab, and @-mentions to point the agent at a file.
• History — ↑/↓ open a preview popover (prefix-filtered), and ⌘R opens fuzzy history search.

The "!" scratch shell

While an AI CLI (like Claude Code) owns the terminal, type ! then a command (e.g. !git status) to run it in a persistent, per-pane scratch shell shown as a resizable card — with live output, its own history, and Stop / Reset controls.

Organize work across windows, tabs, and split panes.

You can drag a sidebar tab onto a pane edge to move that live session into a split without spawning a new shell, and pop a pane back out to its own tab. ⌘ is Ctrl on Windows/Linux.

Share any tab as a live session and let others follow along in real time. Viewers see exactly what you see — the same blocks, themes, background, and full-screen apps (like an editor or a running agent) — from the Dragent desktop app or straight from a web browser.

Two roles

• View — watch only. Anyone with the link can join; no account required. Viewers are given a friendly guest name.
• Edit — run commands and type in the terminal (including inside full-screen apps). Editing requires signing in, and every action is attributed and audited.

Start sharing

Open a tab's ⋮ menu (in the tab bar or the session header) and choose Share session. In the share sheet you can invite people by email at a chosen role, copy the link, or show a QR code. A green Livechip appears in the session header while you're hosting.

Who's in the session

Joined participants appear as a row of avatars — in the host's share sheet and in the viewer's top bar. A viewer can press Request edit; the host gets a prompt to grant or decline, and once granted the viewer can type immediately (no extra sign-in).

Joining from a browser

Opening a share link in a browser shows a live viewer with the participant bar, a running session timer, and an Open in Dragent button. View links open with no account; edit links prompt you to sign in first. When you request edit, you get a notification that the request was sent, and a follow-up toast when the host grants or declines it — no page reload, and no second sign-in when granted.

Stop sharing

• Click the Live chip in the session header, or choose Stop sessionfrom the tab's ⋮ menu.
• A session that nobody joins is automatically stopped after 10 minutes.

The agent can plan, read and edit files, run commands (with your approval), search your codebase, and use skills. It runs in one of five modes, chosen from the input bar or a slash command:

Approvals

Anything that changes your system runs through approval. In Settings → Agent, choose an approval mode — Manual (always ask), Suggest (only destructive actions ask; the default), or Auto(nothing asks, except reading files outside your project). You can also let read-only commands auto-run, and remember "always allow / deny" per tool.

Budgets & models

The input bar shows turn count, token usage, and a context-window meter; Dragent auto-compacts long sessions so you can keep going. Switch models with /model, or add your own provider keys or a local (OpenAI-compatible) endpoint in Settings → Models & Keys.

When a command fails, Dragent attaches a Fix panel to that block. It reads any files referenced in the error, diagnoses the failure, and shows an explanation.

• If there's a simple fix, click Rerun command to run the corrected version.
• For a deeper problem, click Fix automatically — the agent searches, edits, and re-runs the failing command until it passes.

The agent works by calling tools, each shown as a labeled block, with edits rendered as diff cards. Read-only tools generally run without asking; changes and commands follow your approval policy.

• Read & inspect — read files, list directories, show a tree, get file info, list allowed roots.
• Search — grep, search_codebase (hybrid semantic + exact), and a parallel explore sub-agent.
• Edit & write — write, edit, batch-edit, apply patches, create directories, move files (with a guard against blindly overwriting unread files).
• Run & orchestrate — run_command, spawn_subagent, task management, a code repl, and skill.
• Web — web_search and fetch_url (run on the backend).
• Ask you — ask_user presents interactive multiple-choice questions.

Connected MCP (Model Context Protocol) servers add their own tools dynamically.

Skills are packaged instructions that teach the agent to do a specific task well — reviewing a PR, writing a tech spec, scaffolding a component, and more. Dragent ships a large catalog and applies a skill automatically when your request matches.

Add your own

• Per project — create .dragent/skills/<name>/SKILL.md in the repo (commit it to share with your team).
• Everywhere — place it under ~/.dragent/skills/.

A SKILL.md has optional YAML frontmatter (name, description, when-to-use, allowed tools) and a markdown body that acts as a prompt template. Project skills override bundled ones of the same name.

When you open a project, Dragent builds a local semantic index so the agent can find relevant code quickly. Embeddings are computed on your machine by default, and the index is a pure local cache.

• Control it in Settings → Code & Index: enable/disable, auto-index on changes, respect .gitignore, and ignore patterns (paths that are never indexed or sent to the model).
• The search_codebasetool blends semantic and exact matches, falling back to text search when the index isn't ready.
• Git context (branch, changes vs HEAD) is surfaced in the UI and given to the agent.

Attach images and files with the + button or by dragging them in. Images (png/jpg/webp/gif) are sent as multimodal content so the agent can see them; text files are inlined.

Voice input — click the microphone chip and speak. Voice never uses your AI budget: macOS can use a cloud engine on paid tiers and falls back to on-device; Windows uses built-in dictation. Force on-device with DRAGENT_VOICE_ENGINE=os.

Workflows are saved, parameterized command templates (commands.dev / Warp-compatible YAML). Open the command palette with ⌘⇧P, search, pick one, and press Tab to fill each {{argument}} before running.

Dragent bundles a large catalog (git, docker, kubernetes, aws, npm, and more). Add your own to ~/.config/dragent/workflows/or a project's ./.dragent/workflows/.

Dragent ships a large catalog (~335 themes), including background-image themes. Choose one in Settings → Appearance — search the full catalog, or browse the featured set and image themes, each shown as a live preview card.

• Image themes keep the picture visible everywhere while popovers, menus, and cards stay solid and readable; each theme's designed opacity is respected.
• Custom themes — drop a .yaml into ~/.config/dragent/themes/ (same format as bundled; a matching name overrides a bundled theme).
• Fonts — pick a family (bundled Fira Code + system monospace), size, and line height; typography scales across the whole app together.

Open Settings with ⌘,. Sections:

• Account — sign in, plan, usage, billing.
• Agent — approval mode, auto-run safe commands, max steps, self-healing, context scope; Models & Keys; and MCP servers.
• Workspace— Appearance, Terminal & Input (shell, fonts, cursor, Vim keys, autodetection), Code & Index, Keyboard Shortcuts.
• System — Privacy and About.

Dragent uses a credit model for AI usage (1 credit = 1¢). Everyone gets a monthly free allowance; paid plans add a plan allowance, and you can buy credits (which never expire).

• Funds are spent plan → free → credits. A "Use my credits" setting controls whether credits are billed after allowances run out.
• When your premium funds are exhausted, the model selector locks to the free model until your allowance resets or you enable/buy credits. You can always use your own provider key instead.
• Billing (subscription, payment, buying credits) is managed in the web dashboard.

Dragent's core principle: your machine executes, the server orchestrates. Commands run locally, the client has final say, and changes require approval.

• Stays local — terminal history, the codebase index and embeddings, credentials, agent memory, and your own provider keys.
• Leaves only when you use AI— self-healing sends the failing command, directory, truncated output, and exit code; agent tasks send your request plus needed context. There's no background telemetry of your commands.
• Never sent — anything matched by .gitignore, a repo .dragentignore, or your ignore patterns.

For maximum control, use your own provider keys or a local model, and set provider fallback to off so platform keys are never used.

⌘ (Cmd) on macOS corresponds to Ctrl on Windows/Linux.

Dragent runs on macOS and Windows. zsh, bash, and Windows PowerShell get full shell integration (blocks, exit codes, directory tracking); other shells run without it. Updates are delivered over HTTPS and applied on the next restart.

• Windows— defaults to PowerShell (with PowerShell 7 and Git Bash in the "+" picker), draws its own titlebar, and settles a block's output a moment after completion (a ConPTY correctness mechanism, not a hang).
• Linux is not an officially supported target in this release.

• Commands don't become blocks— use a shell with integration (zsh, bash, PowerShell); set it in Settings → Terminal & Input.
• Ctrl+C doesn't copy — by design; copy is ⌘C / Ctrl⇧C.
• Model selector is locked — your premium funds are exhausted; enable/buy credits, upgrade, wait for reset, or use your own key.
• Agent won't edit / run — check the mode (Ask is read-only, Plan waits for approval) and your approval settings.
• Hard-to-read image theme — pick a theme whose text suits the image, or a solid theme.
• Microphone silent— grant OS microphone permission (macOS: System Settings → Privacy & Security → Microphone).

Which platforms are supported?

macOS and Windows. Linux isn't an official target yet.

Do I need an account to use the AI?

Sign in to use the Dragent platform's models, or bring your own provider key or a local model.

Will the agent change files without asking?

Not unless you allow it — every change and command runs through approval, and Ask mode is read-only.

Where is my code indexed?

Locally — the index and embeddings are computed and stored on your machine.

How much does it cost?

Everyone gets a monthly free allowance; paid plans add more, and credits (1 credit = 1¢) never expire.

Is voice a paid feature?

No — voice never uses your AI budget.

Dragent is proprietary, closed-source commercial software and an original, clean-room implementation. Like most commercial software, it incorporates some third-party open-source components under their own licenses, which it credits and whose notice requirements it honors — including the Apache License 2.0.

No copyleft (GPL / LGPL / AGPL / MPL) code is included. These third-party licenses apply only to their respective components, never to Dragent's own proprietary code. Product logos shown in the app are trademarks of their owners, used only to identify those products.

For the complete license notices and attributions, see the Open-Source Licenses & Notices page.