English | 中文
DeepReef is a terminal-native AI loop agent for making cheap, free, and local models complete real engineering work through supervised execution loops.
Most coding agents assume a strong frontier model is always available. DeepReef takes a different position: use stronger models for planning, supervision, and recovery; use cheaper or local models for the bulk of the execution; keep the loop observable, resumable, and governed by explicit safety boundaries.
The goal is not to replace good models. The goal is to make low-cost models useful enough to keep working.
DeepReef is a TypeScript/Bun CLI and TUI agent runtime with:
- a cache-aware agent loop optimized for low-cost model usage
- a Supervisor / Worker workflow for long-running engineering tasks
- adjustable harness levels for weak, local, or unreliable models
- a terminal UI built with Ink and React
- 30+ built-in tools for file operations, search, editing, shell, web, tasks, workflow, MCP, memory, and notebooks
- Skills, MCP, plugin/content-pack, and AgentMemory integration
- deny-first permission handling for shell commands and file modifications
- session persistence and recovery for interrupted work
DeepReef is currently pre-1.0. Core CLI, tools, security, memory, plugin, skills, MCP, and workflow foundations are implemented, but public APIs and configuration formats may still change.
DeepReef avoids the fragile pattern of one agent wandering through an unbounded loop. The intended workflow is a fixed two-role execution structure:
Supervisor plans
-> Worker executes
-> Worker reports
-> Supervisor reviews evidence
-> continue, correct, escalate, or ask the human
The Worker is the execution agent. It can use a local model, a free model, or a low-cost API model. In normal chat it behaves like a regular coding agent. In workflow mode, it follows Supervisor instructions and reports progress through structured checkpoints.
The Supervisor uses a stronger model. It is responsible for planning, reviewing Worker reports, reading immutable evidence bundles, detecting failure loops, and producing the next structured instruction. When the workflow cannot safely continue, the Supervisor stops and asks the user.
npm install -g @deepreef/cliYou can also use Bun:
bun install -g @deepreef/clicd your-project
deepreefInside DeepReef, run:
/help
/model
/workflow
/help is the main usage entry point. Ask it for command details, model setup, workflow usage, harness levels, or troubleshooting.
git clone https://github.com/bzcsk2/DeepReef.git
cd DeepReef
bun install
bun run dev| Command | Purpose |
|---|---|
/model |
Switch chat target without losing state; configure providers, API keys, and local models. |
/workflow |
Start the Supervisor / Worker workflow. |
/sessions |
List and restore previous sessions after exit or crash. |
/skill |
Browse and activate built-in engineering skills. |
/status |
Inspect runtime, model, provider, tool, and session state. |
/context |
Adjust context strategy. |
/thinking |
Adjust reasoning intensity. |
/harness |
Adjust execution constraints for weak or local models. |
/help |
Show command help and usage guidance. |
Most AI coding tools rely on expensive models to compensate for weak orchestration. DeepReef focuses on orchestration first:
- put expensive intelligence where it matters: planning, review, recovery, verification
- let cheap/free/local models do repeatable implementation work
- keep the loop recoverable when the Worker fails
- reduce wasted tokens with cache-aware context management and tool-call repair
DeepReef treats model weakness as a runtime condition, not a fatal limitation. The harness system lets the user choose stricter execution rails for weaker models:
- smaller steps
- stronger verification gates
- more frequent reports
- bounded retries
- Supervisor escalation on repeated failure
DeepReef is built for developers working in repositories, not for generic chatbot sessions. It emphasizes:
- file-aware edits
- shell execution with permission checks
- resumable sessions
- TUI observability
- project-local configuration
- fast model/provider switching
DeepReef uses a kernel/shell separation:
packages/core -> agent loop, API adaptation, context, cache, retry, workflow primitives
packages/tui -> Ink/React terminal UI, input, status, model picker, workflow display
packages/tools -> file, shell, search, edit, web, MCP, workflow, task, notebook tools
packages/plugin -> plugin/content-pack runtime, hooks, schema validation
packages/memory -> AgentMemory integration and memory tools
packages/security -> deny-first PermissionEngine, HookManager, FileSnapshot
packages/cli -> command-line entry point
The engine emits events through an async stream, so the CLI, TUI, tests, and future IDE/web shells can consume the same runtime without coupling UI rendering to agent execution.
CLI / TUI / future IDE shell
│
▼
AsyncGenerator<LoopEvent>
│
▼
CoreEngine
│
┌─────────┼─────────┐
│ │ │
Model Context Tools
Client Manager Executor
DeepReef includes tools for:
- reading, writing, editing, and listing files
- grep and project search
- shell execution with policy checks
- TODO/task tracking
- web access
- MCP tool discovery and invocation
- workflow control
- notebook-style operations
- memory operations
DeepReef uses layered edit safeguards:
- hash-anchored editing
- fuzzy fallback matching
- stale-read protection
- file snapshots for rollback
- dangerous command blocking
- SSRF-aware web request handling
Skills are reusable domain instruction packages. MCP support lets DeepReef connect to external tools and data sources through JSON-RPC 2.0 / stdio MCP servers.
DeepReef includes memory integration for project and agent continuity. Memory behavior should be treated as configurable runtime state and reviewed before using DeepReef in sensitive repositories.
DeepReef is designed around multiple model classes:
| Class | Intended role |
|---|---|
| Free gateway models | Low-cost Worker execution, exploration, simple implementation. |
| Local OpenAI-compatible models | Private or continuous Worker execution. |
| API models with user keys | Supervisor, recovery, review, or higher-quality execution. |
| Custom OpenAI-compatible endpoints | vLLM, Ollama, llama.cpp, local gateways, or internal routers. |
Provider configuration is available through /model. Local models are routed through OpenAI-compatible configuration.
DeepReef does not require one fixed provider. The runtime state is effectively:
{
provider: string;
baseUrl: string;
model: string;
apiKey?: string;
}DeepReef is an agent that can read files, edit files, run commands, and call tools. Treat it as a powerful local development assistant, not as a sandboxed security boundary.
Key safeguards:
- deny-first permission engine
- explicit authorization for shell and write operations
- dangerous command blocking
- file snapshots for rollback
- stale-read checks before edits
- isolated sub-agent permissions
- API key files ignored by Git
Do not run DeepReef in a repository where you are not willing to review agent-generated changes.
bun install
bun run typecheck
bun test
bun run build
npm pack --dry-runThe package is published as @deepreef/cli and exposes the deepreef binary.
Current primary docs:
Additional design and implementation notes live under docs/. Some files in docs/ are development notes rather than polished user documentation.
See ROADMAP.md.
Near-term focus:
- harden npm installation and package smoke tests
- stabilize Supervisor / Worker workflow behavior
- document provider configuration and harness levels
- improve Windows terminal compatibility
- add reliability benchmarks for weak/local models
Issues and pull requests are welcome. Start with CONTRIBUTING.md, then check open issues and roadmap items.
DeepReef is especially interested in contributions around:
- local model presets
- weak-model workflow reliability
- terminal UI polish
- provider adapters
- MCP examples
- documentation and examples
- safety hardening
MIT License. See LICENSE.