DCode

A Coding Agent Built from Scratch

中文文档

DCode is an experimental Coding Agent and a developer-facing Agent Harness. It exposes real model context, the Agent Loop, tool execution, and long-horizon context maintenance as parts of the product.

DCode currently provides three main capabilities:

1. Context Debugging & Hacking — observe and intervene in real model requests.
2. Self-Adaptive Context — adaptively manage context through Tool Result externalization, Tool Result Snip, and working-memory-based context compression.
3. Plan Workflow — support a Plan-then-Execute mode for long-running tasks with explicit state, milestones, and completion conditions using a single Agent.

The TUI and Web client share the same Agent algorithm. The Web interface adds developer debugging capabilities and provides a richer user experience than the TUI.

DCode is under active development. Persistence formats and public interfaces may change without backward compatibility.

Quick Start

Requirements

• Node.js 22 or newer is recommended.
• pnpm 10 or newer.
• A model provider and API key with an OpenAI-compatible API. DCode is developed against the DeepSeek V4 model family; full compatibility with other models is not guaranteed.

Install

git clone https://github.com/Albert-Vanderboom/dcode.git
cd dcode
pnpm install

Create a .env file in the repository or any parent directory:

DCODE_API_KEY=your-api-key
DCODE_BASE_URL=https://openrouter.ai/api/v1
DCODE_MODEL=deepseek/deepseek-v4-flash

DCode uses an OpenAI-compatible provider boundary. The default configuration connects to a DeepSeek V4-family model through OpenRouter, but the model and endpoint are configurable.

Web Client and Debugger

pnpm web

Open the address printed by the server. The default is http://127.0.0.1:4317.

Create a Session, select its working directory, and use:

• Run — execute automatically;
• Step — advance one complete model-and-tools Round;
• Trace — inspect the execution tree;
• Model input — inspect or Hack a historical request;
• Context — observe the budget, Payloads, and Memory lifecycle;
• Plan — enter Plan Workflow mode, declare explicit state, milestones, and completion conditions in the Plan, and drive a long-running task through execution.

TUI

pnpm dcode

One-shot CLI

pnpm dcode --prompt "Explain this repository"

Run pnpm dcode --help to see model, endpoint, Session resume, host, port, and other configuration options.

1. Context Debugging & Hacking

DCode persists an exact Request Snapshot for every model-inference Round. The Web Debugger organizes execution as:

Session -> Turn -> Round -> Event

A Turn is the complete flow from one user input until the model produces a final Message containing no tool calls.

For every Round, developers can inspect:

• the complete list of messages sent to the Provider;
• the System Prompt and Context Memory currently being generated asynchronously in the background;
• assistant reasoning, content, and tool-call JSON;
• tool schemas registered with the model;
• the Context budget and any excluded or externalized content;
• streamed output, Token usage, Tool Results, and errors;
• state transitions under Plan Workflow;
• nested Subagent activity.

Step Execution and Automatic Run

One Step corresponds exactly to one model inference and the complete batch of tool calls returned by that inference. The next Step recompiles the next model request from the resulting real state.

While the model continues to produce tool calls, Run repeatedly executes Steps until the Turn completes, stops, fails, or reaches the configured Round limit.

Hack Any Historical Request

Developers can start a Hack Chain from the exact Request Snapshot of any historical Round:

1. edit, add, or remove any Message sent to the model in that Round;
2. execute an isolated Hack Step and observe the model response;
3. explicitly approve tools before they produce real side effects;
4. compile the result of the current Hack into the next Model Input and continue with another Hack Step.

2. Self-Adaptive Context

Long-running coding tasks accumulate more than chat messages. Tool outputs, Plans, code inspection, intermediate decisions, and Subagent results all compete for the same model context window.

DCode treats Context as an independent Runtime Subsystem.

Journal First

The append-only Session Journal is the sole source of truth for semantic history. Model input is a reproducible projection compiled from the Journal and immutable Context Artifacts, not the only copy of that history.

This allows DCode to compress future model requests while preserving the original records required for Session Restore, Debugging, Fork, and later inspection.

Lossless Tool Result Externalization and Snip

When Context pressure rises and old, oversized Tool Results consume too much space, DCode can Snip them from the model input:

• the complete result is stored as a Session-local Payload;
• the Message retains the tool name, summary, Preview, and Payload Reference;
• recent Context remains protected;
• short results remain inline when a reference would be more expensive than the original content;
• the Agent or developer can still reload the complete Payload.

Tool Result Snip takes priority over semantic Memory compression because it can reduce input size without requiring a model to reinterpret history.

Asynchronous Baseline and Delta Memory

As Context pressure continues to rise, a background Worker prepares model-generated Context Memory:

• a Baseline represents the consolidated historical state;
• a Delta records important changes after the Baseline or previous Deltas;
• old Journal ranges covered by Active Memory no longer need to be replayed message by message;
• multiple Deltas can be semantically rebuilt by the model into a new Baseline.

Memory Preparation runs asynchronously from foreground interaction, so users do not wait for summary generation. Preparation, Validation, Failure, Activation, and Rebuild are all visible in the Web Context Debugger. Developers can inspect a Memory Candidate after generation and before activation.

This is a traceable, Context-pressure-driven maintenance policy: it preserves continuity across long conversations and long-running tasks while keeping the original history recoverable.

3. Plan Workflow

An unconstrained single Agent may keep working after drifting from the original goal, miss acceptance criteria, or stop before the task is complete. DCode uses a persistent Plan state machine to provide explicit boundaries for long-running execution.

The Workflow divides a task into:

1. Drafting — research the problem and generate a persistent Plan document.
2. Approval — let the user review and edit the Plan before execution.
3. Execution — proceed through explicit Milestones and acceptance criteria.
4. Completion — finish after verifying the planned goal.

During execution, DCode injects the current task, Milestone, progress, and acceptance requirements through transient system-reminder messages. These Runtime Instructions come from the current completion state of the Plan's Milestones. They remain observable in the exact Model Input without pretending to be user-authored conversation history.

This allows one Agent to execute longer tasks while remaining constrained by:

• a persistent goal and implementation Plan;
• explicit Milestone progress;
• acceptance criteria for the current work;
• controlled Plan state transitions;
• concrete stopping conditions.

How the Three Parts Work Together

User / Developer
       |
       v
Session + Working Directory
       |
       v
AgentApplication
       |
       v
AgentLoopService -----> PlanWorkflowCoordinator
       |
       +-----> ContextRuntime
       |          |- Journal
       |          |- Tool Result Payloads
       |          |- Baseline / Delta Memory
       |          `- Exact Request Snapshots
       |
       +-----> ModelTurnRunner -----> LLM
       |
       `-----> ToolExecutionService -----> Workspace / Web / Subagents

Trace + Context Artifacts + Request Snapshots
       |
       +-----> TUI
       `-----> Web Client & Debugger

The frontends neither construct model context nor own the Agent Loop. They call frontend-neutral Application Services and observe persistent events.

See docs/architecture.md for complete dependency boundaries, the persistence model, Context policies, Step semantics, and the HTTP API.

Persistence and Safety

Each Session independently stores its working-directory information, Journal, Context state, Request Snapshots, Payloads, Plans, Traces, and Subagent state under:

~/.dcode/sessions/<session-id>/

Be aware of the following safety boundaries:

• DCode tools can read and write files and execute commands in the selected working directory.
• API keys should be stored in environment variables or .env and must not be committed to Git.
• Tool calls from a Hack Step require explicit approval before execution.
• The Web Server listens only on a local address by default and currently has no authentication or multi-user isolation. Do not expose it publicly.

Development

pnpm typecheck
pnpm test
pnpm web:build

Key modules:

• src/runtime — finite Agent Loop and Round execution
• src/context — Journal, Context compilation, Tool Result Snip, and Memory lifecycle
• src/application — frontend-neutral Use Cases and Session orchestration
• src/plan* — persistent Plan Workflow
• src/tools and src/llm — tools and model-provider integration
• src/tui — Ink terminal interface
• src/http and src/web — HTTP/SSE transport and React Debugger

License

MIT License