@dreb/coding-agent

v2.43.3

Published

a day ago

Coding agent CLI with read, bash, edit, write tools and session management

0High
0Medium
0Low

dreb is an open-source terminal coding agent, forked from pi-mono (itself derived from Claude Code). It has fewer features than Claude Code by design — the bet is that a small, hackable core you can shape beats a large feature set you can't.

Claude Code is a great product. dreb isn't trying to compete on features — it's trying to compete on flexibility. The core is kept minimal; what you'd find baked into other tools, you build here with skills (markdown workflows), extensions (TypeScript), or install from third-party packages.

Concretely, dreb ships without things Claude Code has — and that's intentional:

No MCP. Build CLI tools with READMEs (see Skills), or build an extension that adds MCP support.
No permission popups. Run in a container, or build your own confirmation flow with extensions.
No plan mode. Write plans to files, or build it with extensions, or install a package.
No background bash in the main agent. The main agent runs commands synchronously. For parallel work, use the subagent tool — each subagent runs as an independent process with its own tools.

What you get in exchange: a skill system, an extension API, custom agent definitions, custom provider support (route through any proxy, use any API-compatible backend), and a subagent system for parallel work. From those primitives, you build what you need — and share it with others via git or npm.

Quick Start

Node.js 22 LTS is required. dreb relies on SSE streaming behavior that is stable in Node 22 LTS. Node 24 and Node 26 are known to break provider streaming due to changes in ReadableStream buffering, which causes every provider to fail with "request ended without sending any chunks". If you see that error, switch to Node 22 LTS.

Building from source (recommended)

git clone https://github.com/aebrer/dreb.git
cd dreb
npm install
npm run build
npm link -w packages/coding-agent

Installing from npm

npm install -g @dreb/coding-agent

Authenticate with an API key:

export ANTHROPIC_API_KEY=sk-ant-...
dreb

Or use your existing subscription:

dreb
/login  # Then select provider

Or use a custom provider (corporate proxy, Bedrock, etc.) — see Custom providers & models.

Then just talk to dreb. All 11 built-in tools are enabled by default: read, write, edit, bash, grep, find, ls, web_search, web_fetch, subagent, and wait. Use --tools to restrict to a subset (e.g., --tools read,grep,find,ls for read-only). Three additional tools — search, skill, and tasks_update — are always active regardless of --tools. suggest_next is active by default but excluded when --tools is specified. The model uses these to fulfill your requests. Add capabilities via skills, prompt templates, extensions, or packages.

Also available: @dreb/telegram — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (npm install -g @dreb/telegram). @dreb/dashboard — run dreb dashboard for a browser UI with fleet overview, full chat steering, subagent observability, host file browser, curated appearance themes (per-browser light/dark), and Tailscale/rotating-code pairing (npm install -g @dreb/dashboard; see docs/dashboard.md). Its top bar and persistent session header indicators report connecting, connected, retrying, resyncing, disconnected, or auth failed; bounded SSE replay plus an explicit snapshot barrier restores session state and tasks after a reload, restart, gap, backpressure disconnect, or stalled stream.

Platform notes: Windows | Termux (Android) | tmux | Terminal setup | Shell aliases

Bun users: Bun's lockfile can cache stale @dreb/* versions after upgrades, causing missing-export errors. Fix with bun pm cache rm && bunx --force dreb.

Troubleshooting

"request ended without sending any chunks" on every provider — Your Node version is likely too new. Switch to Node.js 22 LTS. Node 26 in particular changed ReadableStream buffering in a way that breaks the Anthropic and OpenAI SDK stream parsers dreb uses.

Providers & Models

For each built-in provider, dreb maintains a list of tool-capable models, updated with every release. Authenticate via subscription (/login) or API key, then select any model from that provider via /model.

Subscriptions:

OpenAI ChatGPT Plus/Pro (Codex)
GitHub Copilot
Google Gemini CLI
Google Antigravity
Kimi For Coding

API keys:

Anthropic
OpenAI
Azure OpenAI
Google Gemini
Google Vertex
Amazon Bedrock
Mistral
Groq
Cerebras
xAI
OpenRouter
Vercel AI Gateway
ZAI
OpenCode Zen
OpenCode Go
Hugging Face
Kimi For Coding
MiniMax
MiniMax (China)

See docs/providers.md for detailed setup instructions, including Kimi For Coding notes that distinguish OAuth, API-key, first-party CLI, and Moonshot Open Platform vision support.

Custom providers & models: Add providers via ~/.dreb/agent/models.json if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See docs/models.md and docs/custom-provider.md.

Reasoning across model switches: Exact-model signed, encrypted, or redacted reasoning state is replayed unchanged. Structured reasoning is portable only between models that share a provider and the openai-completions API when the destination accepts the source's recognized plain field (reasoning_content, reasoning, or reasoning_text). Other readable reasoning is retained as labelled plaintext in <reformatted-pre-switch-reasoning> markers with incompatible protocol metadata removed; opaque redacted or encrypted-only state is omitted for incompatible targets. This outbound conversion does not change session history, so switching back can replay the original state unless it was compacted or pruned. Custom models must also share provider identity and compatible API/signature behavior.

Interactive Mode

The interface from top to bottom:

Startup header - Shows shortcuts (/hotkeys for all), loaded AGENTS.md files, prompt templates, skills, and extensions
Messages - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
Editor - Where you type; border color indicates thinking level
Footer - Working directory, session name, total token/cache usage, cost, context usage, current model, and rolling tokens-per-second (median TPS with long-term delta)

The editor can be temporarily replaced by other UI, like built-in /settings or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). Extensions can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.

Editor

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

Standard editing keybindings for delete word, undo, etc. See docs/keybindings.md.

Transcript content is optimized for copy/paste: assistant prose, code blocks, tool output, bash output, diffs, and subagent/background-agent results use terminal soft-wrap, so selecting from scrollback preserves long logical lines without app-injected hard newlines. Fixed-width chrome such as tables, boxes, overlays, and the footer remains width-constrained.

Commands

Type / in the editor to trigger commands. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.

| Command | Description | |---------|-------------| | /login, /logout | OAuth authentication | | /model | Switch models | | /scoped-models | Enable/disable models for cycling | | /settings | Thinking level, thinking summaries (adaptive Claude models), theme, message delivery, transport | | /resume | Pick from previous sessions | | /new | Start a new session | | /name <name> | Set session display name | | /session | Show session info (path, tokens, cost) | | /tree | Jump to any point in the session and continue from there | | /fork | Create a new session from the current branch | | /compact [prompt] | Manually compact context, optional custom instructions | | /copy | Open multi-select message picker to copy any messages to clipboard. Assistant reasoning is excluded by default and offered as a separate, selectable Thinking row. | | /dream | Consolidate and prune memories — backs up, merges duplicates, scans sessions for patterns | | /export [file] | Export session to HTML file | | /buddy | Terminal companion — hatch, pet, reroll, set model, or hide. See docs/buddy.md | | /reload | Reload keybindings, extensions, skills, prompts, and context files (themes hot-reload automatically) | | /hotkeys | Show all keyboard shortcuts | | /quit, /exit | Quit dreb |

Keyboard Shortcuts

See /hotkeys for the full list. Customize via ~/.dreb/agent/keybindings.json. See docs/keybindings.md.

Commonly used:

| Key | Action | |-----|--------| | Ctrl+C | Clear editor | | Ctrl+C twice | Quit | | Escape | Cancel/abort | | Escape twice | Open /tree |

Message Queue

Submit messages while the agent is working:

Enter queues a steering message, delivered after the current assistant turn finishes executing its tool calls
Alt+Enter queues a follow-up message, delivered only after the agent finishes all work
Escape aborts and restores queued messages to editor
Alt+Up retrieves queued messages back to editor

On Windows Terminal, Alt+Enter is fullscreen by default. Remap it in docs/terminal-setup.md so dreb can receive the follow-up shortcut.

Configure delivery in settings: steeringMode and followUpMode can be "one-at-a-time" (default, waits for response) or "all" (delivers all queued at once). transport selects provider transport preference ("sse", "websocket", or "auto") for providers that support multiple transports.

Sessions

Sessions are stored as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files. See docs/session.md for file format.

Management

Sessions auto-save to ~/.dreb/agent/sessions/ organized by working directory.

dreb -c                  # Continue most recent session
dreb -r                  # Browse and select from past sessions
dreb --no-session        # Ephemeral mode (don't save)
dreb --session <path>    # Use specific session file or ID
dreb --fork <path>       # Fork specific session file or ID into a new session

Branching

/tree - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.

Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→
Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
Press L (Shift+L) to label entries as bookmarks

/fork - Create a new session file from the current branch. Opens a selector, copies history up to the selected point, and places that message in the editor for modification.

--fork <path|id> - Fork an existing session file or partial session UUID directly from the CLI. This copies the full source session into a new session file in the current project.

Compaction

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

Manual: /compact or /compact <custom instructions>

Automatic: Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via /settings or settings.json.

Compaction is lossy. The full history remains in the JSONL file; use /tree to revisit. Customize compaction behavior via extensions. See docs/compaction.md for internals.

Tab Title

After a few tool calls, dreb auto-generates a terminal tab title describing the session's task — based primarily on your actual request and current-session actions, with branch/repo/cwd used only for disambiguation. Useful when multiple tabs are open. Fires once per session via a background LLM call, and never overwrites an already-named (e.g. resumed) session; failures are surfaced (shown in interactive mode, logged to stderr in RPC mode).

Disable, adjust the trigger threshold, or set a title length target in settings:

{ "tabTitle": { "enabled": false } }

Settings

Use /settings to modify common options, or edit JSON files directly:

| Location | Scope | |----------|-------| | ~/.dreb/agent/settings.json | Global (all projects) | | .dreb/settings.json | Project (overrides global) |

See docs/settings.md for all options. Dashboard Settings re-entry reloads durable global and project settings after flushing pending writes, so it sees external file edits; unreadable, invalid, or failed writes are surfaced as errors rather than showing stale values. See the RPC settings contract.

Context Files

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

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

Use for project instructions, conventions, common commands. All matching files are concatenated.

Nested context trust

At startup, dreb always performs a separate upward scan from its launch cwd and loads matching AGENTS.md/CLAUDE.md files there and in parent directories. That initial scan is not lazy nested loading and is not controlled by the settings below. A context file in a subdirectory — or in a different repo an agent later visits — is considered only when a tool operates there.

Lazy nested/out-of-cwd context loading is off by default. Configure explicit global trusted roots in ~/.dreb/agent/settings.json:

{
  "context": {
    "trustedFolders": ["~/src/my-company", "/srv/controlled-repos"]
  }
}

A trusted root permits lazy loading for that existing directory and all of its descendants. dreb resolves both the root and each tool target through canonical native realpath at decision time: relative, missing, non-directory, and broken-symlink roots fail closed; duplicate and nested roots are deduplicated/subsumed. A lexical descendant that symlinks outside the canonical root is therefore not trusted. Project .dreb/settings.json cannot add, override, or otherwise widen this policy.

Lazy loading triggers on path-bearing tools (read, edit, write, grep, find, ls) and on bash commands that begin with cd <dir>.
It walks from the target toward the applicable ceiling. A trusted root is a hard ceiling; otherwise the session cwd is used for in-tree targets, then the outermost git repo root, then the outermost directory containing a context file.
Each file is injected at most once per session, including files from the initial upward scan. The paths are realpath-deduplicated. If a triggering read or full cat/bat already returns a context file in full, dreb marks it loaded without adding a duplicate block.
Auto-loaded text is secret-scrubbed and appended after extension tool_result transforms, so those transforms intentionally do not see it.
Main agents and subagents make the same global trust decision. Global trust changes are observed by active processes for future lazy loads; already injected content cannot be removed from their conversation.

Expert trust-all override — prompt-injection warning: setting context.autoLoadNested: true in the global ~/.dreb/agent/settings.json allows lazy loading from any resolvable tool target. This can inject instructions from untrusted or third-party repositories. It is global-only; a project .dreb/settings.json cannot enable it. Leave it off and trust only folders you control whenever possible. The Files view shows the effective trust for the directory being viewed and lets you trust a folder or untrust the actual granting root; untrusting an inherited folder removes that root's trust for all of its descendants.

System Prompt

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

Memory

dreb has a persistent, file-based memory system. Memory survives across sessions and helps the model recall user preferences, past decisions, project context, and pointers to external resources.

How it works

Memory is convention-based — no dedicated tool. The system prompt teaches the model the memory format; the model uses the standard read, write, and edit tools to manage memory files. Memory indexes (MEMORY.md) are loaded at session start and injected into the system prompt.

Locations

| Scope | Directory | Loaded | |-------|-----------|--------| | Global | ~/.dreb/memory/ | Every session | | Project | <project-root>/.dreb/memory/ | When working in that project |

Project identity is determined by git repo root. The global memory directory is auto-created on first session; project directories are created on demand by the model.

Memory entries

Each memory is a Markdown file with YAML frontmatter:

---
name: descriptive-name
description: One-line description for relevance matching
type: user-preferences
---

Content of the memory entry.

Four types: user-preferences (who the user is), good-practices (how to approach work), project (ongoing work context), navigation (pointers to external resources).

MEMORY.md index

Each memory directory has a MEMORY.md file that serves as an index. Only the first 200 lines are loaded at session start — keep it concise:

- [User role](user_role.md) — Python dev, generative art background
- [CI parity](feedback_ci_parity.md) — run tsgo --noEmit locally, not just tests

Claude Code compatibility

dreb reads existing Claude Code memory for the current project from ~/.claude/projects/ (read-only), with source labeling and a warning about Claude Code-specific references that may not apply to dreb.

Task Tracking

The tasks_update tool lets the model maintain a visible task list during multi-step work. Tasks appear in a TUI panel with status indicators (☐ pending, ⧖ in progress, ☑ completed).

The tool uses a full-replacement model — the model sends the complete task list on each call, no incremental updates. The TUI panel is visible by default and renders when active tasks exist. It auto-hides when the task list is empty or all tasks are completed. Toggle visibility with the app.tasks.toggle keybinding (unbound by default, configurable in keybindings). The panel displays up to 10 tasks at a time; overflow shows as "... and N more".

Task tracking is prompt-driven: the system prompt includes guidelines for when to use it (3+ step work), concise titles, and a maximum of 20 tasks.

Subagents

The subagent tool delegates tasks to independent child agent processes. Each subagent runs in its own process with its own context window, and notifies the parent when complete.

Modes:

Single (task): One background agent
Parallel (tasks): Up to 8 concurrent agents (max 4 at a time)
Chain (chain): Sequential pipeline where each step can reference the previous step's output via {previous}

Agent type inheritance: The top-level agent parameter is inherited by parallel tasks and chain steps that don't specify their own. Precedence: per-task agent > top-level agent > default ("Explore"). The model parameter follows the same inheritance.

Agent definitions live in ~/.dreb/agents/ (global) and .dreb/agents/ (project). Each is a markdown file with YAML frontmatter specifying name, model (with provider fallback list), and optional systemPrompt. Built-in agents include Explore (read-only codebase exploration), Sandbox (restricted to /tmp), feature-dev (strong-tier coding), and several review agents.

Model availability probes: When an agent definition specifies a fallback list (comma-separated models), each model is verified with a lightweight API call via the same streamSimple path the agent loop uses before the subagent is spawned. The probe uses normal coding-agent thinking defaults and does not pass a synthetic maxTokens override, which keeps the request shape representative for reasoning models as well as non-reasoning models. Models that fail the probe (rate limit, quota exhaustion, auth failure, timeout) are skipped with a loud log line, and the next fallback is tried. If all configured models fail, the parent session's model is used as a last resort. Per-invocation model overrides and single-model configs skip probing entirely.

Per-agent model overrides: The model used by each agent type can be overridden via the agentModels.models setting (a map of agent name → ordered fallback list) without copying or editing the agent definition .md files. Configure it in settings.json or via /settings → Agent Models. Resolution order: per-invocation model override → agentModels setting → agent definition model → parent session model. See docs/agent-models.md.

Model identity in system prompt: The parent session's running model is exposed in its own system prompt as You are running on: provider/id. This lets the model make self-aware routing decisions (e.g. delegate vision tasks to a multimodal subagent, or use a differently-architected model as a critic). The line updates automatically on mid-session model switches.

Session metadata: Each child process records its agent type in the session JSONL header (agentType field), providing an audit trail of which agent definition executed the work.

Background-agent guardrail: Background subagents run asynchronously and return control to you while they work. To stop the parent agent from spinning ahead of results, a guardrail pauses it after backgroundAgents.parentTurnLimit turns (default 3) while subagents are still running. When this happens, dreb surfaces a friendly, non-error notification in the TUI and Telegram — explaining that background agents are still working and the parent paused intentionally, and that it resumes when they report back or when you send a message to steer it. This is a frontend/session event, not a model-context steer, so it can't go stale. Set backgroundAgents.parentTurnGuardrail to false to let the parent run unbounded while subagents work, or raise parentTurnLimit to relax the guardrail. See settings.

Semantic Search

The search tool provides natural language queries over the codebase using embeddings and full-text search. It supports identifier queries (e.g., AuthMiddleware), natural language (e.g., where is rate limiting handled), and path queries (e.g., src/auth/).

Parameters: query (required), searchDir (directory to index and search — each unique value gets its own independent index; defaults to cwd, but should be set explicitly in Telegram sessions where cwd is ~/), restrictToDir (filter results to files under this subdirectory within the already-built index — does not affect which files are indexed), limit (max results, default 20), rebuild (force a clean re-index when results look stale or corrupt).

How it works: The first query builds a project index (typically 10–60s, longer for very large repos). Subsequent queries use the cached index, with incremental re-indexing for changed files (mtime-based). Each unique searchDir gets its own independent index.

Indexing pipeline:

AST-aware code chunking via tree-sitter (TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, GDScript) — extracts functions, classes, methods, and exports as individual chunks
Format-aware text chunking for non-code files (Markdown by heading, YAML/JSON/TOML by top-level key)
Local embeddings via all-MiniLM-L6-v2 (~23MB model, auto-downloaded on first use, cached at ~/.dreb/agent/models/)

Ranking: Uses POEM (Pareto-Optimal Embedding-based Multiranking) with 6 metrics: FTS5 BM25, vector cosine similarity, path match, symbol match, import graph proximity, and git recency. Short identifier queries bias toward exact text matches; long natural language queries bias toward vector similarity.

Storage: Project index at .dreb/index/, memory files indexed alongside code. Add **/.dreb/ to your project's .gitignore. Works offline after the initial model download.

Requirements: Node.js 22+ (uses built-in node:sqlite). On older Node versions the tool is silently unavailable — no crash, it simply doesn't register. Zero native addons — uses web-tree-sitter (WASM) and @huggingface/transformers (WASM).

Customization

Prompt Templates

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

<!-- ~/.dreb/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

Place in ~/.dreb/agent/prompts/, .dreb/prompts/, or a package to share with others. See docs/prompt-templates.md.

Skills

On-demand capability packages following the Agent Skills standard. Invoke via /skill:name, or the agent invokes them automatically via the built-in skill tool when a task matches.

<!-- ~/.dreb/agent/skills/my-skill/SKILL.md -->
---
name: my-skill
description: Use this skill when the user asks about X.
argument-hint: "<topic>"
---

## Steps
1. Do this with $1
2. Then that

Skills support content substitution ($1, $ARGUMENTS, ${DREB_SKILL_DIR}, etc.) and frontmatter fields like argument-hint, user-invocable, and disable-model-invocation.

Place in ~/.dreb/agent/skills/, ~/.agents/skills/, .dreb/skills/, or .agents/skills/ (from cwd up through parent directories) or a package to share with others. See docs/skills.md.

dreb ships with mach6 — a built-in development workflow (issue → plan → push → review → fix → publish) that uses GitHub as shared memory and multi-agent code review. See docs/mach6.md.

Extensions

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

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

What's possible:

Custom tools (or replace built-in tools entirely)
Plan mode and custom agent workflows
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
Make dreb look like Claude Code
Games while waiting (yes, Doom runs)
...anything you can dream up

Place in ~/.dreb/agent/extensions/, .dreb/extensions/, or a package to share with others. See docs/extensions.md and examples/extensions/.

Themes

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

Place in ~/.dreb/agent/themes/, .dreb/themes/, or a package to share with others. See docs/themes.md.

Packages

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

Note: Third-party packages can include extensions (arbitrary code) and skills (model instructions). Skim what you're installing, same as any other dependency.

dreb install npm:@foo/my-tools
dreb install npm:@foo/[email protected]      # pinned version
dreb install git:github.com/user/repo
dreb install git:github.com/user/repo@v1  # tag or commit
dreb install git:[email protected]:user/repo
dreb install git:[email protected]:user/repo@v1  # tag or commit
dreb install https://github.com/user/repo
dreb install https://github.com/user/repo@v1      # tag or commit
dreb install ssh://[email protected]/user/repo
dreb install ssh://[email protected]/user/repo@v1    # tag or commit
dreb remove npm:@foo/my-tools
dreb uninstall npm:@foo/my-tools          # alias for remove
dreb list
dreb update                               # skips pinned packages
dreb config                               # enable/disable extensions, skills, prompts, themes

Packages install to ~/.dreb/agent/git/ (git) or global npm. Use -l for project-local installs (.dreb/git/, .dreb/npm/). If you use a Node version manager and want package installs to reuse a stable npm context, set npmCommand in settings.json, for example ["mise", "exec", "node@20", "--", "npm"].

Create a package by adding a dreb key to package.json:

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

Without a dreb manifest, dreb auto-discovers from conventional directories (extensions/, skills/, prompts/, themes/).

See docs/packages.md.

Programmatic Usage

SDK

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@dreb/coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: AuthStorage.create(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("What files are in the current directory?");

See docs/sdk.md and examples/sdk/.

RPC Mode

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

dreb --mode rpc

RPC mode uses strict LF-delimited JSONL framing. Clients must split records on \n only. Do not use generic line readers like Node readline, which also split on Unicode separators inside JSON payloads.

See docs/rpc.md for the protocol.

CLI Reference

dreb [options] [@files...] [messages...]

Package Commands

dreb install <source> [-l]     # Install package, -l for project-local
dreb remove <source> [-l]      # Remove package
dreb uninstall <source> [-l]   # Alias for remove
dreb update [source]           # Update packages (skips pinned)
dreb list                      # List installed packages
dreb config                    # Enable/disable package resources

Modes

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

In print mode, dreb also reads piped stdin and merges it into the initial prompt:

cat README.md | dreb -p "Summarize this text"

Model Options

| Option | Description | |--------|-------------| | --provider <name> | Provider (anthropic, openai, google, etc.) | | --model <pattern> | Model pattern or ID (supports provider/id and optional :<thinking>) | | --api-key <key> | API key (overrides env vars) | | --thinking <level> | off, minimal, low, medium, high, xhigh | | --models <patterns> | Comma-separated patterns for model 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 | | --fork <path> | Fork specific session file or partial UUID into a new session | | --session-dir <dir> | Custom session storage directory | | --no-session | Ephemeral mode (don't save) |

Tool Options

| Option | Description | |--------|-------------| | --tools <list> | Comma-separated list of tools to enable (default: all) | | --no-tools | Disable all built-in tools (extension tools still work) |

Available built-in tools: read, bash, edit, write, grep, find, ls, web_search, web_fetch, subagent, wait, search

Three additional tools are always active but don't appear in --tools:

skill — invokes skills programmatically
tasks_update — session task tracking with TUI panel
suggest_next — suggests a next command shown as ghost text (Tab to accept)

Resource Options

| Option | Description | |--------|-------------| | -e, --extension <source> | Load extension from path, npm, or git (repeatable) | | --no-extensions | Disable extension discovery | | --skill <path> | Load skill (repeatable) | | --no-skills | Disable skill discovery | | --prompt-template <path> | Load prompt template (repeatable) | | --no-prompt-templates | Disable prompt template discovery | | --theme <path> | Load theme (repeatable) | | --no-themes | Disable theme discovery |

Combine --no-* with explicit flags to load exactly what you need, ignoring settings.json (e.g., --no-extensions -e ./my-ext.ts).

Other Options

| Option | Description | |--------|-------------| | --system-prompt <text> | Replace default prompt (context files and skills still appended) | | --append-system-prompt <text> | Append to system prompt | | --verbose | Force verbose startup | | --offline | Disable startup network ops (same as DREB_OFFLINE=1) | | -h, --help | Show help | | -v, --version | Show version |

File Arguments

Prefix files with @ to include in the message:

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

Examples

# Interactive with initial prompt
dreb "List all .ts files in src/"

# Non-interactive
dreb -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | dreb -p "Summarize this text"

# Different model
dreb --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix (no --provider needed)
dreb --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
dreb --model sonnet:high "Solve this complex problem"

# Limit model cycling
dreb --models "claude-*,gpt-4o"

# Read-only mode
dreb --tools read,grep,find,ls -p "Review the code"

# High thinking level
dreb --thinking high "Solve this complex problem"

Environment Variables

| Variable | Description | |----------|-------------| | DREB_CODING_AGENT_DIR | Override config directory (default: ~/.dreb/agent) | | DREB_PACKAGE_DIR | Override package directory (useful for Nix/Guix where store paths tokenize poorly) | | DREB_CACHE_RETENTION | Set to long for extended prompt cache (Anthropic: 1h, OpenAI: 24h) | | DREB_OFFLINE | Disable startup network ops (same as --offline) | | DREB_SEARCH_BACKEND | Search backend: ddg (default), searxng, or brave | | DREB_SEARXNG_URL | Base URL for SearXNG backend (default: http://localhost:8888) | | DREB_BRAVE_API_KEY | API key for Brave search backend | | DREB_WEB_SEARCH_RATE_LIMIT_MS | Minimum delay between web searches in milliseconds (default: 10000) | | DREB_DEBUG | Show debug-level messages in the TUI chat feed (default: suppressed) | | VISUAL, EDITOR | External editor for Ctrl+G |

Contributing & Development

See docs/development.md for setup, forking, and debugging.

License

MIT