DeepCode Documentation

File: README.md Copy Chapter

DeepCode: Open Agentic Coding

*Advancing Code Generation with Multi-Agent Systems* Copy Section

🖥️ **Interface Showcase** Copy Section

🖥️ **DeepCode Desktop**

DeepCode has one Agent runtime and two interfaces: an interactive CLI for
terminal workflows and a Tauri Desktop workbench for visual Sessions, review,
and settings. Both open the same local Projects, Session history, models,
Skills, permissions, Goals, and Automations. See the
Desktop source guide to run the application locally.

🎯 Watch our complete introduction - See how DeepCode transforms research papers and natural language into production-ready code

"Where AI Agents Transform Ideas into Production-Ready Code"

📑 Table of Contents Copy Chapter

• 📰 News
• 🧠 What Deep means in DeepCode
• 🚀 Core capabilities
  • Agent Harness
  • Loop Engineering
  • Context Engineering
  • Evidence-driven completion
  • Durable local work
  • Models and Skills under your control
  • Parallel and repeatable work
• ⚡ Quick start
• 🧭 Using DeepCode
• ⚙️ Headless and automation
• 🔬 Paper2Code
  • The original architecture
  • Research results
• 🎬 Live demonstrations
• 🛠️ Development
• ⭐ Star History
• 🙏 Appreciation
• 📖 Citation
• 📄 License

News Copy Chapter

2026-08-19 · Sessions that survive resume, compaction, and a second window

• Resuming a session restores what the agent did, not only what it said.
  Tool calls and their results are part of the canonical record now, so a
  resumed agent can answer "what did you just run?". A test makes the rule
  executable: every request a run sends must be rebuildable from the session
  file alone.
• Compaction keeps the recent tail. The checkpoint replaces the older
  range and everything recent survives verbatim — assistant messages and tool
  results included — instead of dropping them and putting the summary last.
  Manual /compact used to refuse almost every real conversation; it works,
  and the checkpoint speaks as the model's own history, so it stops being
  discounted as someone else's report.
• Context pressure is measured, not guessed. The gate now anchors on the
  size the provider itself reports. The built-in estimator prices Chinese
  prose at more than twice its real cost, which was compacting Chinese
  conversations at roughly half the context they could hold.
• Two windows on one Session no longer crash each other. Each Session
  now has one live writer, enforced by an OS lock held around a turn: the
  second window gets a sentence naming who is running it, instead of a
  process dying to a database constraint about half the time. Alternate
  freely between Desktop and the terminal — just not mid-turn.

2026-08-18 · The runtime learns dsh's context discipline, and the TUI gets a face

• A new turn no longer throws away the prompt cache. The environment
  block used to be re-inserted before your newest message every turn, so each
  turn diverged from the previous request right where that block had been:
  7,420 prompt tokens recomputed at every turn boundary, now 28.
• The TUI has a logo, a live status line, and tool cards that read. A
  spinner and a sweep while work runs, paths written the way you would type
  them, the plan tool's checklist visible at last, and a turn footer with its
  time and token usage. An idle TUI costs nothing to animate.
• A source-level comparison against dsh became a plan. Where the message
  list the model sees comes from, what compaction should keep, and what the
  session record must contain — measured and written down, and four
  unreferenced documents retired.

2026-08-17 · Fixes from a review pass over the new settings and TUI work

• A declared model reads the same everywhere. Per-model declarations now
  shape the catalog a picker shows, not only what a Turn executes with, so a
  context window you set to avoid overflow is the number you see.
• Adopting fetched models shows them immediately. The catalog cache is
  keyed on the settings that shape it, instead of serving the previous remote
  listing for up to an hour.
• Escape closes one thing. Dismissing the provider editor no longer tears
  down the settings dialog around it and discards a half-typed key.
• A removed model row takes its own capacities with it rather than leaving
  them on the row that survived — which then saved them onto the wrong model.
• Automated runs keep their tools. A default agent preset chosen for
  interactive chatting no longer narrows deepcode exec and goal runs behind
  your back.
• The provider section says it is user-scoped, instead of letting the
  dialog's project write scope imply otherwise.

2026-08-16 · The TUI answers every bare command with a selector

• Type the command, pick from a list. /model now opens the full model
  directory — every configured connection's catalog (remote snapshot or
  declared entries, near a thousand rows on OpenRouter) in one filterable
  selector with the current route pinned first and each model's published
  reasoning ladder on Shift+Tab; Enter commits model and effort together.
  /preset, /effort, /permissions, /transcript and /skill join
  /resume: a bare invocation opens a picker with the current choice
  marked, while argument forms and piped runs keep their text paths.
• Background tracebacks can no longer shred the transcript. Stdlib
  logging is bridged into loguru with call-site fidelity, so file-only
  transports really are file-only; and the durable event relay backs off
  exponentially on persistent failure — one traceback per streak, one-line
  repeats, a recovery notice.

2026-08-15 · Settings grow up: a dsh-style dialog, declared models, and a safer config

• A connection's key now reaches exactly the requests it was resolved
  for. Building a provider no longer exports the key into the process
  environment, where every same-template connection could pick it up as its
  own; removing a provider un-configures every key source instead of letting
  it reappear; and when a launch environment variable shadows a pasted key,
  the editor says which one and that it wins. Verification also works from
  async hosts now.
• The agent-preset picker grew up. A menu with per-preset descriptions
  and trust marking replaces the cramped native dropdown, the duplicate
  "Default" row is gone, and a started session shows a read-only label of
  what it runs.
• Manage what each connection actually serves. The provider editor can
  fetch the live model list from a connection's endpoint and adopt picked
  models as its manual list, an environment-provided key locks the paste
  field instead of silently outranking it, and connection rows show the
  discovered model count.
• deepcode chat reads like a terminal app, not a log. A restyled
  transcript — brand-gradient banner, status-colored tool cards with result
  elbows, block spacing, word-boundary wrapping — plus streaming that
  survives the prompt redraw with real colors instead of ?[36m litter.
• Desktop Settings became a dsh-style dialog. General / Models /
  Plugins / Agent presets in a left rail, with Open configuration file and
  the write-scope picker in the header. General gains the five canonical
  rows — default agent preset for new sessions (applied as a by-value
  snapshot at creation, CLI and TUI included), permissions, language
  (English/中文, first translated batch), Light/Dark/System appearance
  cards, and a steer-or-queue busy-Enter preference.
• Models are declarations now. manualModels entries can carry a
  label, capacities, and the published reasoning ladder; declarations are
  authoritative offline for execution profiles and every picker. Discovery
  probes the editor form as shown — unsaved URL or key included — and
  adopted picks land as accurate declaration rows. Config writes gained
  optimistic concurrency (a changed file conflicts instead of being
  clobbered) and a settings.changed push keeps an open dialog fresh.
• Session and model commands now hold up. /resume and /model open
  an inline selector — type to filter by title, arrows move, Enter picks,
  Tab flips directory scope, Shift+Tab cycles the route's published
  reasoning effort — and resume replays the conversation tail. Bare model
  names resolve their connection, typos no longer kill the REPL, and
  /compact summarizes with the model you actually selected. New verbs:
  /rename, /delete, /retry, with tab completion for session ids,
  transcript modes, permission presets, and effort levels.

Earlier August 2026 updates

2026-08-14 · Subagent runtime, compaction, and one-way persistence

• Delegate to Codex or Claude Code as a subagent. spawn_agent gains
  external backends that run the installed CLI with a scrubbed environment and
  strict success criteria, while native subagents gain personas, validated
  tool allowlists, JSON output schemas, follow-up conversation via
  send_message, and full transcripts in the parent session.
• Guard the loop. Tools can declare timeouts the runner enforces, and a
  repeat-call tracker injects an escalating, model-visible reminder when
  identical calls repeat.
• Compact on demand. /compact summarizes older turns in the resident
  context; every refusal is a stable, readable reason (busy Turn, too little
  history, a failed or non-shrinking summary) and canonical session data is
  never touched.
• See which file set every configuration value. Diagnostics report each
  configured leaf with its providing layer and a bounded preview;
  credential-shaped subtrees are redacted whole. A verbatim deepseek-harness
  Skill also loads unchanged from .agents/skills.
• Relieve context pressure with the cheapest sufficient measure. Under
  pressure the runtime first middle-prunes oversized tool results — a free,
  convergent pass covering MCP and custom tools alike — and only summarizes
  if that is not enough; the summarization call replays the routed request as
  a genuine prefix so provider prompt caching is reused, and a summary that
  would not shrink the conversation is rejected.
• Deleted sessions stay deleted. The Desktop projection no longer adopts
  a thread back into canonical storage unless SQLite genuinely owns it
  (legacy import or automation bootstrap), and every mid-turn message the
  model sees — goal updates, recovery prompts, injected results — now lands
  in the canonical session log, so a resumed session rebuilds exactly the
  history the model saw.
• Open a session as a different agent. Named agent presets bundle a
  persona and a tool face — deepcode exec --preset code-reader, /preset
  in the TUI, or the picker beside the Desktop model control — while the
  model route and permissions stay independent knobs. A preset is one
  markdown agent file in the .claude/agents/.agents dialect, so
  definitions written for other harnesses load unchanged; the resolved
  composition is snapshotted into the session record and locked once the
  conversation starts, at which point the Desktop picker becomes a
  read-only label of what the session runs.

2026-08-13 · Desktop typography, themes, and native controls

• Make the type-size preference actually resize the app. Every interface
  size now derives from one rem-based scale, so the Appearance slider moves the
  whole window. It previously moved almost nothing: 255 hardcoded pixel values
  ignored it, and the smallest labels sat at 7px.
• Pick from eight themes, including high contrast. Light, Dark, Paper, and
  Midnight are joined by two terracotta palettes and a WCAG AAA high-contrast
  option. Tests compare each palette against the complete token set, so a theme
  cannot half-apply and leave a stray default showing through.
• See one design language rather than the operating system's. Sliders,
  selects, and focus rings now follow the active theme instead of falling back
  to platform chrome, and an explicit theme choice moves color-scheme with it
  so native controls stop rendering in the OS scheme.
• Read the quiet text. The light palette's secondary tones and every accent
  colour were refitted to clear WCAG AA against the surfaces they actually sit
  on, several of which previously measured under 3:1.

2026-08-12 · Reviewed upstream core Skills

• Start with reviewed upstream Skills. DeepCode now bundles eight pinned,
  provenance-tracked Agent Skills from OpenAI, Codex, and Anthropic for Skill
  authoring, code review, security analysis, frontend design, MCP construction,
  and web application testing. They use the same catalog and Turn runtime as
  project, user, and Plugin Skills.

2026-08-12 · Managed MCP catalog, OAuth, and real connection checks

• Start from reviewed templates without hidden execution. DeepCode bundles
  a validated catalog based on Nanobot's current 16 MCP templates. Adding
  one copies ordinary user configuration in a disabled state; it never silently
  runs npx, Docker, or a remote server.
• Configure MCP consistently in every interface. Desktop and TUI now join
  the management CLI and App Server on one preset, configuration, test, OAuth,
  and live-status service rather than maintaining interface-specific clients.
• Distinguish config, authorization, and connectivity. A real MCP probe
  initializes the server and counts tools, resources, and prompts. Browser
  OAuth uses a loopback callback and a private credential file outside project
  configuration, while Agent startup never opens a browser implicitly.

2026-08-10 · Generic MCP runtime and portable local Plugins

• Connect standard MCP servers from every interface. User and trusted
  project configuration, App Server, CLI, and Desktop now share one generic
  stdio/SSE/Streamable HTTP client runtime with bounded discovery, stable tool
  identities, timeouts, cancellation, and session-owned cleanup.

• Keep credentials and authority explicit. Executable config layers replace
  whole entries, child processes receive a minimal environment, provider keys
  stay in private DeepCode connections, and MCP policy can only narrow global
  trust, read-only, approval, and sandbox decisions.

• Run Agent Plugins 1.0 MCP components without format forks. Valid
  mcp.json servers join the same runtime only when an Agent Session starts,
  receive isolated PLUGIN_ROOT / PLUGIN_DATA, and fail independently from
  bundled Skills and other servers.

• Connect OpenSpace as MCP plus two ordinary Skills. A reviewed recipe binds
  an OpenRouter connection without plaintext secrets, imports OpenSpace's host
  Skills into the standalone catalog, and keeps cloud/upload tools disabled by
  default.

• Register trusted local Plugin folders. CLI and Desktop now share a
  user-level Plugin registry with add, inspect, enable, disable, and unregister
  operations; unregistering never deletes source files.

• Keep one execution path. Enabled Plugins contribute authority-bound
  Skills through the existing Skill Provider host, so selection, dependencies,
  progressive reads, permissions, revisions, and audit metadata remain the
  same across CLI, TUI, headless execution, and Desktop.

• Preserve standalone Skills. Project and user Skills remain independently
  installable and take precedence over a same-named Plugin Skill. Plugins are
  an optional packaging source, never a replacement Skill lifecycle.

• Use one portable package contract. Local Plugins use the Agent Plugins
  1.0.0 root manifest and fixed skills/ layout; experimental DeepCode
  manifests are no longer accepted. Hooks, Apps, Marketplaces, downloads, and
  updates remain inert.

2026-08-09 · Skills now have a real runtime contract

• Load guidance through one provider boundary. Skill discovery, content
  reads, and package search now stay with the provider that owns the Skill,
  while the catalog remains metadata-only. Local Skills keep their existing
  precedence and identity, and future providers no longer need filesystem
  shortcuts to fit the runtime.
• Compose Skills without hiding missing capabilities. Skills can declare
  tool and Skill dependencies; DeepCode expands them in order, detects cycles,
  and fails before the first model request when a requirement is unavailable.
• Reveal only what the task needs. The Agent can search and read bounded
  package resources progressively, with revision, traversal, symlink, and size
  checks applied at the shared provider contract.
• Keep execution constrained and auditable. A Skill can narrow the tools
  already allowed by the Session but cannot grant new permissions. CLI, TUI,
  and Desktop share the same immutable Turn snapshot and persist only Skill
  identity, invocation kind, and revision—not the instruction body.
• See changes everywhere without restarting. One workspace host now owns
  the shared catalog and provider cache, while each Agent Session keeps its own
  Turn context. Local Skill and policy changes refresh Desktop automatically,
  and Composer, management, CLI, and headless execution resolve through the
  same lifecycle.

2026-08-07 · Thinking controls, more providers, and a Desktop you can tune

• Reasoning controls work again across the board. Thinking levels are now
  resolved from the model catalog, so Claude, GPT-5, Kimi, Qwen and Grok all
  offer their real effort levels, and DeepSeek, GLM and MiniMax get a working
  thinking toggle. A newly released model inherits its family's controls
  instead of silently losing them.
• Three more providers. Requesty and Forge join as gateways, and MiniMax
  arrives with its own catalog entry — including the 1M-context M3 tier.
• Make the Desktop yours. Settings → Appearance adds conversation width,
  a light/dark override that no longer follows the OS blindly, font size, and
  font selection filtered to what is actually installed on your machine.
• Safer command execution on Windows. A Job Object backend gives the
  sandbox real process-tree isolation where previously there was none.

2026-08-04 · Skills that work wherever you do

• Keep reusable expertise close to your work. DeepCode discovers Skills
  from the current project as well as your personal collection, while keeping
  existing DeepCode and Claude-compatible Skill locations working.
• Use the same Skill from CLI or Desktop. Select it for a task and DeepCode
  carries its identity and version with the Turn, so the Session shows which
  guidance shaped the result.
• Create Skills without leaving DeepCode. The built-in Skill Creator helps
  you scaffold and validate focused, reusable workflows from either interface.
• Stay focused as your library grows. Context-aware discovery keeps the
  Agent prompt concise while the complete Skill catalog remains available to
  browse and manage.

2026-08-03 · 🎉 DeepCode v2.0 is here

DeepCode v2.0 introduces a new general-purpose Coding Agent framework for
building, fixing, understanding, and improving real software projects.

• Take on real repository work. DeepCode can explore a codebase, edit
  files, run commands and tests, review changes, and carry a task through to a
  working result.
• Keep complex goals moving with Loop Engineering. Give DeepCode a goal and
  it can continue through understanding, implementation, verification, and
  repair instead of stopping after one plausible answer.
• Stay in control while the Agent works. Add requirements, correct its
  direction, switch models, stop, resume, or revise the goal without throwing
  away the work already completed.
• See what you are getting. Plans, tool activity, code changes, test results,
  and verification evidence stay visible so the result is easier to review and
  trust.
• Build Automations around the way you work. Turn any natural-language
  instruction into a project-specific task: run it on demand or on a recurring
  interval, then edit, pause, resume, and review every result. Use it for the
  work you want DeepCode to keep taking care of, from regression checks and
  test repair to documentation upkeep and repository maintenance.
• Work your way. Use Desktop or CLI, bring your own models and Skills, and
  delegate focused work without changing the underlying Agent workflow.

DeepCode v2.0 is built to help you spend less time supervising every step and
more time shipping software you are proud of. We cannot wait to see what you
build! 🚀

Earlier 2026 milestones

• 2026-07-31 · One execution model across CLI and Desktop. Interactive,
  headless, Goal, Automation, and Desktop work share the same durable Project,
  Session, Thread, and Turn lifecycle. Workspace trust stays independent from
  the Session access preset, and reasoning controls remain model-aware.
• 2026-07-21 · Durable Goals and safe Session lifecycle. Long-running Goals
  are resumable across CLI and Desktop, while guarded archival and deletion
  preserve repository files and recover safely after interruption.
• 2026-07-20 · Session-level model control and shared Skills. Named LLM
  connections and future-Turn model switches preserve conversation history;
  project and user Skills are shared across entry points.
• 2026-07-17 · Durable Session navigation and replay. Projects organize
  collapsible Session history, long conversations replay incrementally, and
  approvals, reviews, tests, and Artifacts remain attached to their task.
• 2026-07-10 · Loop Engineering and parallel agents. Mutable Goals can
  inspect, implement, verify, and repair across steerable Turns, while focused
  work can be delegated in isolated worktrees with explicit conflict handling.
• 2026-07-08 · Durable Sessions and memory. Session history survives
  restarts, project instructions can live in AGENTS.md or DEEPCODE.md, and
  persistent notes remain with the workspace.
• 2026-07-08 · General coding agent. The free-form TUI, native file and shell
  tools, headless execution, context compaction, and cross-directory resume
  established the current product foundation.
• 2026-07-04 · Agent Harness foundation. A shared execution contract,
  three-valued permissions, sensitive-path protection, platform sandboxing, and
  normalized events made supervised local execution possible.
• The complete pre-restructure history is preserved in the
  legacy README.

What Deep means in DeepCode Copy Chapter

Most Coding Agents can generate code. The hard part is understanding a real
project, making changes within the right boundaries, continuously correcting
course from runtime results, and making it clear why the outcome can be
trusted.

DeepCode is an open-source Coding Agent for real software engineering. Give it
a simple change or a goal that takes dozens of steps. It can understand the
project, work on the code, run tools, verify results, and continue after an
interruption, restart, or model switch.

“Deep” represents four kinds of depth that remain with the task from start to
finish:

DeepCode stands out in three ways:

• Turn complex knowledge into a working system. DeepCode is not limited to
  Issues and code snippets. Paper2Code can start from papers, documents,
  reference repositories, and experiment goals, then carry the work through
  understanding, implementation, and verification.
• Keep long tasks moving while staying in control. A Goal is not a one-shot
  prompt. Add requirements, revise the Goal, pause, stop, or continue while the
  task is running without losing completed work.
• Take code changes through verification and review. DeepCode goes beyond
  generating a patch. It runs the commands and tests the task requires,
  inspects build results and file changes, and links the Goal outcome to
  relevant execution records for review.

DeepCode is not designed to make an Agent look busier. It is designed to help
you finish real software engineering work more reliably.

Core capabilities Copy Chapter

DeepCode provides a complete local Coding Agent workflow. CLI and Desktop are
two ways to use the same Agent, Sessions, models, Skills, permissions, and task
state.

Work directly in your repository Copy Section

DeepCode can read and search code, edit files, apply patches, run commands and
tests, and continue working from the results. Tool calls, execution progress,
and file changes stay visible, so you can see what the Agent did and what
changed in the project.

Use it to explain code, fix bugs, and add tests—or for cross-file refactors,
feature development, and longer repository-level tasks.

When you provide a public HTTP or HTTPS URL, the shared web_fetch tool can
read the page without a search provider or an additional API key.

Goal-driven Loop Engineering Copy Section

For work that cannot be completed in one response, give DeepCode a natural-
language Goal. The Agent keeps analyzing, implementing, verifying, and fixing
around that Goal without requiring you to push every step manually.

While it runs, you can still:

• add information to the current task;
• revise the Goal or its acceptance criteria;
• queue the next instruction;
• pause, stop, or continue the task;
• resume the same Goal after leaving the application.

Automatic execution does not take away your control. You can always change
what should happen next.

Evidence-driven completion Copy Section

DeepCode does not use one hard-coded rule to judge every Coding task. It
selects evidence that fits the task, such as test results, build output, static
checks, diagnostics, file changes, Diffs, or generated Artifacts.

A failed verification is not presented as success. It becomes input to the
next repair. When a task is complete—or genuinely blocked—the result, reason,
and related evidence remain in the Session for review and reproduction.

Durable Sessions and project context Copy Section

Every Session is stored locally and linked to its original project. Start
DeepCode from any directory, find earlier projects and Sessions, and continue
the same work in CLI or Desktop.

A Session stores more than chat text: it keeps tool calls, permission
decisions, Goals, model configuration, and verification records. Project rules,
persistent memory, Skills, and long-conversation compaction help the Agent keep
context throughout complex work.

Your models, your reasoning settings Copy Section

DeepCode is not tied to one model provider. Connect OpenRouter, OpenAI,
Anthropic, DeepSeek, Gemini, an OpenAI-compatible gateway, Ollama, vLLM, or
another compatible endpoint with your own API Key.

Before use, a connection can check credentials, the model catalog, and a real
inference request. Each Session can choose a model and Thinking Level. Changing
models mid-Session affects future Turns only; it does not delete history or
confuse where earlier work came from. When supported, DeepCode can also show a
reasoning summary returned by the Provider.

Reusable Skills Copy Section

Skills turn team conventions, domain knowledge, review methods, and repeated
workflows into reusable Agent capabilities. DeepCode includes pinned upstream
Skills for authoring, review, security, frontend, MCP, and web testing workflows.
Keep project Skills in .agents/skills, keep personal Skills in
~/.agents/skills, or use the bundled Skill Creator to build one
conversationally.

DeepCode also reads existing .deepcode/skills and Claude-style directories
without migrating them. A Skill can guide how the Agent works, but it cannot
bypass project trust, tool permissions, or safety boundaries.

Permissions you can understand Copy Section

Every project must be explicitly trusted before execution. Each Session can
use one of three modes:

• Ask: confirm sensitive operations before they run;
• Read only: allow analysis and reading only;
• Full access: allow complete work in a trusted project.

Individual tools also support allow, ask, and deny. CLI and Desktop share
the same permission state, and DeepCode does not silently replay operations
with side effects after a task is stopped or interrupted.

Parallel agents without file collisions Copy Section

Complex work can be split across focused Agents—for example, separate Agents
for code investigation, test analysis, and implementation review.

Parallel changes can run in isolated Git worktrees so Agents do not edit the
same working directory at once. Results return to the main task for review and
integration. Conflicts are shown explicitly instead of being silently
overwritten, and the main Agent remains responsible for the final Goal.

Automate repeatable engineering work Copy Section

Once a workflow is stable, save it as an Automation and run it manually or on
a schedule. For example:

• check tests and builds regularly;
• scan for regressions;
• organize pending work;
• run repository maintenance or periodic reviews.

Automation does not launch a separate, reduced Agent. It uses the same
Sessions, models, Skills, permissions, approvals, and recovery behavior, and
keeps the history of every run.

Paper2Code Copy Section

Paper2Code was DeepCode's original research direction and remains its dedicated
workflow for research reproduction.

It can start from a paper, technical document, URL, or reference repository;
understand the research goal; find related implementations; organize a
development plan; generate code; and verify the result through experiments and
Artifacts. It reflects DeepCode's core idea: the goal is not to generate code
that merely looks correct, but to turn complex knowledge into a system that can
run, be inspected, and keep improving.

Quick start Copy Chapter

DeepCode has two interfaces with separate installation paths. Choose one to get
started; both use the same Agent runtime and canonical Session history.

uv tool install --python 3.12 deepcode-hku installs the CLI and shared
Python runtime. It does not install the Tauri Desktop application.

Option A — Install the CLI Copy Section

Install uv first if it is not already available. On Windows PowerShell:

winget install --id astral-sh.uv --exact

Open a new terminal after the first uv installation, then run:

uv tool install --python 3.12 deepcode-hku
deepcode init

The explicit Python selection is intentional: DeepCode requires Python 3.12+
and must not fall back to an unsupported legacy package on an older interpreter.
If an existing uv tool environment still contains DeepCode 1.x, migrate it with
uv tool upgrade --python 3.12 deepcode-hku.

Create a model connection once. --api-key opens a non-echoing prompt:

deepcode provider set personal-openrouter --template openrouter --label "OpenRouter · Personal" --api-key
deepcode provider models personal-openrouter --refresh
deepcode provider test personal-openrouter --model <model-id>

Enter the repository you want DeepCode to work in and start the interactive
Agent:

cd <your-project>
deepcode

deepcode init creates minimal user configuration under ~/.deepcode/.
Credentials are stored separately in user-private storage and are never written
to Session history. pipx install deepcode-hku and pip install deepcode-hku
are also supported in an appropriate Python 3.12+ environment.

Option B — Install Desktop Copy Section

Desktop release bundles are distributed separately from the Python package.
Check GitHub Releases for a signed
installer for your platform. If no installer is attached, use the source setup
below.

macOS and Linux from source

Install the platform dependencies from the
Tauri 2 prerequisite guide, plus
Git, Python 3.12+, uv, Node.js 22+, and stable Rust. Then run:

git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode
uv venv --python 3.12
uv pip install --python .venv/bin/python -e .
.venv/bin/deepcode init
cd desktop
npm ci
npm run setup:sidecar
npm run build:sidecar
cd ..
mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/deepcode-desktop" ~/.local/bin/deepcode-desktop
export PATH="$HOME/.local/bin:$PATH"
deepcode-desktop

The final link is a one-time source launcher installation. Afterwards,
deepcode-desktop starts this checkout from any directory, provided
~/.local/bin is on PATH. Add the export to your shell profile if it is not
already configured. The command launches Desktop; add or select the repository
you want to work on from the Project sidebar.

Windows from source

Windows requires Microsoft Edge WebView2 and the Visual Studio 2022 Build Tools
workload Desktop development with C++. Accept the UAC prompt raised by Build
Tools:

winget install --id Git.Git --exact
winget install --id astral-sh.uv --exact
winget install --id OpenJS.NodeJS.LTS --exact
winget install --id Rustlang.Rustup --exact
winget install --id Microsoft.VisualStudio.2022.BuildTools --exact `
  --override "--wait --passive --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Close PowerShell, open a new window, and verify the toolchains:

git --version
uv --version
node --version
rustup default stable-msvc
rustc --version
cargo --version

Clone, prepare, and start Desktop:

git clone https://github.com/HKUDS/DeepCode.git
Set-Location DeepCode
uv venv --python 3.12
uv pip install --python .venv\Scripts\python.exe -e .
.venv\Scripts\deepcode.exe init
Set-Location desktop
npm ci
$env:DEEPCODE_PYTHON = (Resolve-Path ..\.venv\Scripts\python.exe)
npm run setup:sidecar
npm run build:sidecar
npm run tauri -- dev

Keep that PowerShell window open while Desktop is running. See the
Desktop source guide for subsequent
launches and troubleshooting.

Configure the Desktop model

Open Settings → AI providers after Desktop starts.

1. Select Add provider, choose the service, and enter an API key or its
   environment-variable name.
2. Select Save and check to verify the credential and load the provider's
   model catalog without sending repository content.
3. Under Agent model, choose an exact model ID and select Save and verify
   model. This final check sends only a minimal inference request.
4. Add or open a Project, create a Session, choose the model, Thinking effort,
   and access level, then describe the task in natural language.

The interface changes how the work is presented, not the Agent, policy,
configuration, or Session history behind it.

Using DeepCode Copy Chapter

Prefer a guided walkthrough? The teaching guides cover
the same ground page by page — first session, the TUI, sessions, models,
skills and memory, and headless automation — with worked examples.

Sessions Copy Section

Every task lives in a durable Session attached to its original Project. Open a
Project in Desktop or start deepcode from its directory, then create a new
Session or resume an existing one. The same history can move between Desktop
and CLI without export or conversion.

Session history, tool activity, approvals, Goal state, and verification evidence
remain together. A Session has one live writer at a time: Desktop and the CLI
may hold it open together, but if one is mid-Turn the other refuses new input
with a message naming the holder instead of corrupting shared history. Archiving hides a Session without deleting its history;
permanent deletion removes the Session records but never repository files.

Connections and models Copy Section

Desktop provides connection setup and verification under Settings → AI
providers. In the CLI, /model changes the connection and model for future
Turns, while /effort selects a Thinking level supported by that model.

Model changes never rewrite earlier history or alter an active Turn. Thinking
effort controls the request sent to the provider; transcript detail controls
only presentation. DeepCode shows provider-designated reasoning summaries when
available and never merges raw chain-of-thought into the assistant answer.

Provider administration, environment-variable credentials, custom gateways,
model discovery, and machine-readable checks are documented in the
Headless and Automation guide.

Skills Copy Section

Skills turn reusable engineering knowledge into instructions the Agent can load
for a task. Desktop provides a Skills workspace; the interactive CLI uses
/skills to discover them and /skill <name> to select one for the next Turn.
Choose Skills → Create Skill in Desktop or invoke $skill-creator in CLI to
create and validate one through a normal Agent Turn.

Project Skills in .agents/skills travel with a repository; user Skills in
~/.agents/skills remain available across Projects. Existing DeepCode and
Claude-compatible directories remain readable. A Skill can guide the Agent,
but it cannot grant permissions or bypass Project trust, approvals, or tool
policy. Import, enable, disable, and catalog commands live in the
advanced guide.

Local Plugins Copy Section

Plugins optionally package Skills behind a validated local manifest; standalone
project and user Skills continue to install and run without a Plugin. New
packages must use the Agent Plugins 1.0.0 manifest and fixed skills/ layout.
Add a trusted folder from the Desktop Plugins workspace or with deepcode plugin add ; its Skills then appear in the ordinary Skill catalog and
Composer. A standards-compliant mcp.json may also contribute MCP servers;
registration remains inert and those processes start only inside an Agent
Session. DeepCode does not execute Plugin hooks or Apps and does not download
from a Marketplace. See the
local Plugin contract.

MCP servers Copy Section

Generic coding-agent MCP servers live in the top-level mcpServers section of
deepcode_config.json; the historical Paper2Code tools.mcpServers section is
kept separate. Configure servers in Desktop under MCP, or use the compact
deepcode mcp CLI. The bundled catalog is listed with deepcode mcp presets;
add copies a disabled definition, test <name> performs a real
handshake, and login/logout <name> manages explicit browser OAuth. The TUI
offers the same actions under the single /mcp command. User and
trusted-project layers replace whole server entries rather than merging
executable fields. Provider secrets are referenced from private DeepCode
connections, and MCP tool policy can only narrow global trust, read-only,
approval, and sandbox decisions.

DeepCode supports stdio, SSE, and Streamable HTTP, session-owned startup and
shutdown, bounded discovery, stable mcp__server__tool identities, tool
annotations, allow/deny lists, per-tool approvals, timeouts, and cancellation.
For a concrete two-Skill plus MCP integration, see the
OpenSpace guide. Setup, preset, OAuth, and
connection-state details are in the MCP client guide.

Safety and execution Copy Section

DeepCode treats execution as a product boundary rather than a client-side
confirmation:

• Projects require explicit trust before Agent execution on every interface.
• Permission decisions are allow, ask, or deny.
• An approval resumes the exact suspended tool call.
• Ask keeps the workspace command sandbox and protected-path checks;
  Read only denies mutating tools; Full access is an explicit,
  confirmed Session grant that removes approval and filesystem sandbox
  boundaries. Explicit deny rules still win.
• CLI and Desktop edit the same Session override. Each admitted Turn freezes
  the complete resolved security profile: changes apply to new submissions,
  while active and already queued Turns keep their recorded access after
  resume or worker handoff.
• Shell and code processes are terminated as owned process trees on timeout,
  interruption, or shutdown.
• Crash recovery settles incomplete Turns without automatically replaying side
  effects.

Long-running work Copy Section

Ordinary prompts can run a full multi-tool coding Turn. When work must continue
across several Turns or process restarts, attach a durable Goal to the Session.
Use the Goal panel in Desktop or /goal <objective> in the CLI.

While DeepCode works, new input can steer the active Turn. You can edit the
Goal, stop the current Turn, queue a follow-up, pause the Goal, or resume it
later. These actions preserve the same Session, history, permissions, Skills,
and evidence instead of starting an isolated execution.

The working Agent requests complete or blocked from its full context.
DeepCode enforces ownership, lifecycle, permission, and budget boundaries, but
does not pretend a generic host-side rule can validate every coding task. A
normal semantic result is labelled Completed; tests, builds, diagnostics,
diffs, or independent review remain visible evidence. No provider, model, task
type, or test command is fixed by the Goal engine.

Automations and headless workflows Copy Section

The Desktop Automation workspace turns a trusted Project instruction into a
manual or interval run while keeping the normal Agent, Session, Goal,
permissions, recovery, and Run history. Use it for repeatable work such as
repository health checks, regression review, or scheduled maintenance.

Shell scripts and CI systems can use the same runtime without opening an
interface. The separate
Headless and Automation guide contains the
exec, loop, Automation, Provider, Skill, and Session administration
commands. They are advanced integration surfaces—not a second way ordinary
Desktop or CLI users must learn to talk to DeepCode.

Paper2Code Copy Chapter

Paper2Code is the research origin of DeepCode and remains its specialized
workflow for scientific code reproduction. The general coding Agent extends
the product; it does not replace or flatten the original Paper2Code design.

Its central idea is unchanged: reproducing a paper is not a one-shot generation
task. A central orchestrator coordinates distinct responsibilities for
understanding the source, planning the reproduction, finding and indexing
useful references, implementing the system, and verifying the result.

The original architecture Copy Section

The specialist roles preserve the separation of concerns that made the
original system effective:

Four ideas connect those roles into one system:

• Intelligent orchestration. The central Agent chooses and revisits phases
  according to task state instead of treating reproduction as a fixed prompt
  chain.
• Document and intent grounding. Papers, specifications, URLs, and attached
  files are converted into explicit implementation requirements before code is
  written.
• Memory and CodeRAG. Large documents and reference repositories are
  segmented, indexed, and retrieved as bounded context rather than repeatedly
  placed into the model window.
• Iterative verification. Execution, tests, and observed failures feed back
  into planning and implementation until the deliverable has supporting
  evidence.

The supporting tool layer follows the same division:

The modern product adds durable plans, explicit plan review, checkpoints,
bounded retries, and interactive inspection around this workflow. Those
additions make recovery and supervision stronger while preserving the
Paper2Code architecture and its order of reasoning.

Research results Copy Section

The original DeepCode study evaluates scientific code reproduction on
PaperBench, which asks agents to
reproduce 20 ICML 2024 papers across 8,316 gradable components.

| 75.9%
Human expert subset+3.5 points | 84.8%
Commercial-agent subset+26.1 points | 73.5%
Scientific coding+22.4 points | 73.5%

LLM-agent baseline+30.2 points |
| --- | --- | --- | --- |

These are PaperBench-specific results reported by the original study. They are
not a general-purpose coding benchmark or a comparison against continuously
updated products.

Read the paper for methodology, evaluation
scope, models, and baseline details.

🎬 Live Demonstrations Copy Chapter

These recordings show projects produced by earlier DeepCode workflows. They
are output demonstrations rather than screenshots of the current Desktop UI.

| #### 📄 Paper2Code

Research to implementation

▶ Watch demonstration

Reproduce a research paper as an executable project. | #### 🖼️ Generated vision project

Image workflow example

▶ Watch demonstration

See an earlier generated image-processing workflow in use. | #### 🌐 Generated web project

Frontend implementation example

▶ Watch demonstration

Follow a complete frontend implementation from idea to result. |
| --- | --- | --- |

The project introduction remains available for
a broader walkthrough.

Development Copy Chapter

Source installation Copy Section

git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python=3.13
source .venv/bin/activate
uv pip install -e .

On Windows PowerShell, activate with .\.venv\Scripts\Activate.ps1.

Verification Copy Section

uvx pre-commit run --all-files
python -m compileall -q app_server cli core tools workflows
deepcode --version
deepcode-app-server --verify-runtime

cd desktop
npm run lint
npm test -- --run
npm run build

Desktop packaging, Rust checks, signing, and release procedures are documented
in desktop/README.md and the
Desktop release runbook.

Contributor architecture notes

The pre-restructure README is preserved in
docs/archive/README_LEGACY_2026-07-20.md.
The empty product-image slots have a shared
capture brief.

⭐ Star History Copy Chapter

🚀 Ready to build with DeepCode? Copy Section

🙏 Appreciation Copy Chapter

Thanks to everyone in the open-source community — your stars, issues, pull
requests and discussions shape where DeepCode goes next.

Everyone who has opened a pull request is listed in
CONTRIBUTORS.md, including contributions that predate the
v2.0 rebuild and so are not reflected in the graph above.

📖 Citation Copy Chapter

If DeepCode contributes to your research, cite:

@misc{li2025deepcodeopenagenticcoding,
  title         = {DeepCode: Open Agentic Coding},
  author        = {Zongwei Li and Zhonghang Li and Zirui Guo and Xubin Ren and Chao Huang},
  year          = {2025},
  eprint        = {2512.07921},
  archivePrefix = {arXiv},
  primaryClass  = {cs.SE},
  url           = {https://arxiv.org/abs/2512.07921}
}

📄 License Copy Chapter

File: docs/P1_SECURITY_BASE.md Copy Chapter

P1 · 安全底座(第一增量)

实现 DEEPCODE_V2_MASTER_PLAN.md §4.3 的安全层——计划标注"现在裸奔,最高优先级"。机制,非决策:这些模块只做确定性的判定与包裹,不碰模型、不碰 UI(军规 5/7)。

交付 Copy Chapter

权限引擎(提炼自参考项目,非照抄) Copy Chapter

• 集中式敏感路径保护(源自 OpenHarness):.ssh / .aws/credentials / .env / deepcode_config.json / *.pem / id_rsa* 等在 legacy、Ask 与 Read only 执行中优先于规则。产品级、经二次确认的 Full Access 会原子地关闭这条保护、命令沙箱与 workspace 写围栏；普通配置规则不能单独绕过保护。
• 二维通配符规则,特异性优先 + last-match-wins(源自 opencode + 改进):规则同时匹配工具名 × 参数(命令行/路径),{"execute_bash": {"git push *": "ask", "*": "allow"}} 按作者直觉工作(具体压过通配)。直接构造的 PermissionRule 列表保持纯 last-match-wins。
• 三模式:default(改动型工具 ask)/ plan(改动型 deny,只读探索)/ full_auto(仅规则,无隐式 ask,供无人值守工作流)。

沙箱库 Copy Chapter

• macOS seatbelt:生成 .sbpl——读全放行、写仅限工作区(+ /tmp、/private/var/folders 供构建)、默认断网;sandbox-exec 用绝对路径调用防 PATH 注入。已有真实强制执行测试:区内写成功、区外写被拦、区外读放行。
• Linux bwrap:只读绑定根、读写绑定工作区、fresh /tmp、--unshare-net。
• 降级:不可用平台(原生 Windows 等)sandbox_backend() 返回 none,包裹退化为裸命令并打标——调用方据此转审批优先(接线阶段处理)。

内核接缝(错误即数据) Copy Chapter

AgentRunSpec.permission_checker 在每次工具执行前调用:

• allow → 放行;
• deny → 变成 Error: permission denied: <reason> 的工具结果回喂模型(军规 3,不崩溃、不中断);
• ask → 有 approval_callback 则问(批准放行/拒绝回喂),无(无人值守)则默认拒绝并解释——自主性永不静默升级。

fail-closed:checker 或 approver 抛异常 → 一律拒绝。

行为影响 Copy Chapter

实现阶段(FULL_AUTO):与 P0 完全一致,唯一变化——agent 再也读不到/写不了凭据库,即便计划或模型要求。回归验证:paper9 全流程行为无回退。

增量 b(已完成):沙箱接线 + 交互式审批 Copy Chapter

b1 · execute_bash/python 真正经沙箱运行(tools/code_implementation_server.py、tools/command_executor.py)

• 两个 MCP server 的 execute_bash/execute_python(及文件树创建的命令回退)现在经 core.harness.sandbox.build_exec_command 包裹:写围栏到 workspace,读全放行,网络放行(pip/下载不受影响)。
• 环境门控 DEEPCODE_SANDBOX(默认开;0/false/off/no 关闭);后端不可用时降级为裸执行并在结果 sandbox 字段标注(seatbelt/bwrap/none/disabled)。
• 闭合上一节坦白的 shell 凭据边界:shell 命令把凭据 copy 到自控文件 → 写围栏拦截。已有真实 seatbelt 测试证明(test_execute_bash_credential_exfil_write_blocked、区外写拦截、区内写放行、python 同款)。
• 权衡说明:沙箱选择放行网络(实现阶段常需 pip),FS 写围栏是高价值低风险的那层保护;要严格隔离可用 allow_network=False(库支持)。

b2 · 交互式审批(ask → 人机确认)(core/harness/approval.py)

• TerminalApprover:把 ask 变成终端 y/n/always 提示,always 按工具名记忆本会话;非交互 stdin → 拒绝(fail-closed);as_async() 用线程包裹避免阻塞事件循环。
• altitude 决策:自主实现阶段逐工具确认是糟糕 UX,故默认仍 FULL_AUTO;DEEPCODE_PERMISSION_MODE=default|plan 可主动切换,此时自动挂上审批器。真正"交互式默认"属于 P2 通用 agent 循环。

后续接线状态 Copy Chapter

• deepcode_config.json 的 permissions 规则已在 Turn admission 时规范化并
  冻结进 ExecutionSecurityProfile，worker 不再动态重读可变配置。
• 通用 Agent 循环、CLI 与 Desktop 已共享 Ask / Read only / Full access 预设
  及同一 Approval 状态机；legacy mode 只保留给兼容调用。

File: eval/swebench/README.md Copy Chapter

SWE-bench harness

The P2 exit gate: measure whether the DeepCode agent can resolve a real
GitHub issue — produce a patch that flips the hidden FAIL_TO_PASS tests to
passing without breaking PASS_TO_PASS.

The harness separates the two jobs so DeepCode owns only what is DeepCode's:

We do not reimplement the official scorer — for the Verified set the
harness emits predictions.jsonl and hands off to
swebench.harness.run_evaluation.

Local mode (Docker-free, runs anywhere) Copy Chapter

A built-in benchmark of three self-contained instances — each a real bug
(off-by-one, case-sensitivity, missing empty-guard) plus an unrelated correct
function, mirroring SWE-bench's "fix the bug, don't break the neighbours"
shape. Runs the full loop end to end and prints a real resolved rate:

python -m eval.swebench.run --mode local --model gpt-5.4 --report report.json

Result on this machine (Poe gpt-5.4): 3/3 resolved (100%) — every
instance's FAIL_TO_PASS flipped and PASS_TO_PASS stayed green. This
validates the whole prepare → agent → apply → test → score pipeline against a
live model; it is a smoke baseline, not the official Verified number.

Official Verified 50 (needs Docker) Copy Chapter

Generate predictions for the deterministic 50-instance subset (sorted by
instance_id, so the set is reproducible with no RNG seed):

# needs `datasets` + network to stream the dataset and clone repos
uv run --with-requirements requirements.txt --with datasets \
  python -m eval.swebench.run --mode predict --limit 50 --out predictions.jsonl

Then score with the official Docker harness (the command is printed at the
end of the predict run):

python -m swebench.harness.run_evaluation \
  --dataset_name princeton-nlp/SWE-bench_Verified \
  --predictions_path predictions.jsonl \
  --max_workers 4 --run_id deepcode-p2

Scoring requires a running Docker daemon and the swebench package; it is not
reproduced here. Record the resolved rate it reports as the P2 baseline and
re-run it before each release so the number never silently regresses.

Layout Copy Chapter

• instance.py — Instance model + the local benchmark (declarative specs → git repos)
• dataset.py — load Verified + deterministic subset selection + record→Instance
• predict.py — clone, drive deepcode exec, capture the patch (bytecode/cache excluded)
• evaluate.py — local Docker-free scorer (apply to a clean checkout, run the tests)
• report.py — result rows + aggregate resolved rate (JSON + summary line)
• run.py — CLI wiring both modes

File: README_ZH.md Copy Chapter

DeepCode: 开源智能体编程

*基于多智能体系统推进代码生成技术* Copy Section

🖥️ **界面展示** Copy Section

🖥️ **DeepCode Desktop**

DeepCode 只有一套 Agent 运行时，同时提供两种使用界面：面向终端
工作流的交互式 CLI，以及用于 Session、审查和设置的 Tauri Desktop。
两端打开同一份本地 Project、Session 历史、模型、Skills、权限、Goals 与
Automations。从源码启动请参考
Desktop 运行指南。

🎯 观看我们的完整介绍 - 了解DeepCode如何将研究论文和自然语言转换为生产就绪的代码

"AI智能体将创意转化为生产就绪代码的地方"

📑 目录 Copy Chapter

• 📰 新闻
• 🧠 DeepCode 中的 Deep
• 🚀 核心能力
  • Agent Harness
  • Loop Engineering
  • Context Engineering
  • 以证据判断完成
  • 持久化本地工作
  • 由用户控制的模型与 Skills
  • 实时 Web 调研
  • 并行且可重复的工作
• ⚡ 快速开始
• 🧭 使用 DeepCode
• ⚙️ Headless 与 Automation
• 🔬 Paper2Code
  • 原始架构
  • 研究结果
• 🎬 实时演示
• 🛠️ 开发
• ⭐ 星标历史
• 🙏 致谢
• 📖 引用
• 📄 许可证

新闻 Copy Chapter

2026-08-12 · MCP 模板目录、OAuth 与真实连接测试

• 预装模板，但不偷偷执行。 DeepCode 内置基于 Nanobot 当前 16 个 MCP
  模板整理的校验目录。添加模板只会复制一份默认禁用的普通配置，不会自动运行
  npx、Docker 或连接远程服务。
• 所有入口共用一套管理逻辑。 Desktop、TUI、管理 CLI 与 App Server
  现在共享模板安装、配置、连接测试、OAuth 和运行状态服务。
• 分开显示配置、授权与连接状态。 真实测试会初始化 MCP 并统计 tools、
  resources 和 prompts；浏览器 OAuth 使用本机回调，凭据保存在项目配置之外，
  Agent 启动时不会擅自打开浏览器。

2026-08-07 · 思考强度控制、更多模型服务商、可调的 Desktop

• 思考强度控制全面恢复。 思考档位改为从模型目录解析，Claude、GPT-5、
  Kimi、Qwen、Grok 都能选到各自真实的档位，DeepSeek、GLM、MiniMax 也拿到了
  可用的思考开关。新发布的模型会继承同族的能力，而不会悄悄失去控制项。
• 新增三家模型服务商。 Requesty 与 Forge 作为网关加入，MiniMax 拥有独立的
  目录条目——包含 100 万上下文的 M3 层级。
• 把 Desktop 调成你习惯的样子。 设置 → 外观新增会话区宽度、不再盲从系统的
  浅色/深色手动切换、字号，以及只列出本机实际已安装字体的字体选择。
• Windows 上的命令执行更安全。 新的 Job Object 后端为沙箱带来了真正的
  进程树隔离——此前这里是空白。

2026-08-04 · 让 Skills 在每一种工作方式中保持一致

• 让可复用经验跟随项目。 DeepCode 既能发现当前项目中的 Skills，
  也能使用个人 Skill 集合，并继续兼容现有 DeepCode 与 Claude 风格目录。
• 在 CLI 与 Desktop 中使用同一个 Skill。 为任务选择 Skill 后，
  DeepCode 会把它的身份和版本保留在 Turn 中，方便在 Session 中追溯
  哪些指导影响了结果。
• 不离开 DeepCode 也能创建 Skill。 内置 Skill Creator 可在两端
  帮助创建和验证聚焦、可复用的工作流。
• Skill 库增长后依然保持专注。 上下文感知的发现机制会控制
  Agent 上下文中的信息量，同时保留完整的 Skill 浏览与管理能力。

2026-08-03 · 🎉 DeepCode v2.0 正式发布

DeepCode v2.0 带来一套全新的通用型 Coding Agent 框架，面向真实软件项目的
开发、修复、理解与持续改进。

• 直接完成真实仓库任务。 DeepCode 可以理解代码库、修改文件、运行命令
  与测试、检查变化，并把需求推进到真正可以工作的结果。
• 通过 Loop Engineering 持续完成复杂目标。 给出一个 Goal，DeepCode
  可以持续理解、实现、验证和修复，而不是生成一段看似合理的回答就停止。
• Agent 工作时，你始终掌握方向。 随时补充要求、纠正方向、切换模型、
  停止、恢复或修改 Goal，不必丢掉已经完成的工作。
• 清楚看到交付了什么。 规划、工具活动、代码变化、测试结果和验证证据
  都可以查看，让审查结果和放心合并变得更容易。
• 让 Automation 适应你的工作方式。 用自然语言把任意要求变成某个项目
  专属的任务：既可随时手动运行，也可按固定间隔自动执行，还能修改、暂停、
  恢复并查看每次结果。无论是回归检查、测试修复、文档同步还是仓库维护，
  都可以交给 DeepCode 持续处理。
• 按照自己的方式工作。 自由选择 Desktop 或 CLI，使用自己的模型与
  Skills，并委派聚焦任务，而不必改变底层 Agent 工作流。

DeepCode v2.0 希望让你少花时间逐步盯着 Agent，多花时间完成真正值得发布的
软件。期待看到你用它创造出的作品！🚀

2026-07-31 · CLI 与 Desktop 共用统一执行模型

• 交互式对话、无头任务、Goal、Automation 与 Desktop 全部进入同一套持久化
  Project、Session、Thread 和 Turn 生命周期。
• Workspace trust 与 Session 工具权限相互独立；权限可选 Ask、
  Read only 或 Full access。
• 模型 Thinking 强度与推理展示详细度分开控制，改变界面展示不会改变模型请求。

2026-07-21 · 持久化 Goals 与安全的 Session 生命周期

• 长任务可以作为 CLI 与 Desktop 共享的可恢复、证据驱动 Goal 运行。
• Archive 保留历史；永久删除通过统一的 Session 生命周期清理记录，
  不会删除仓库文件。
• 中断的删除会从持久化 tombstone 恢复，不会让旧 Session 记录重新出现。

2026-07-20 · Session 级模型控制与共享 Skills

• 命名 LLM 连接只需配置一次，即可在整个 DeepCode 中使用。
• 为后续 Turn 切换连接或模型时，不会丢失之前的完整对话。
• 无论任务从哪里启动，都能发现、导入、启用和选择同一套项目级或用户级 Skills。

2026-07-17 · 持久化 Session 导航与回放

• 每个 Project 管理自己的可折叠 Session 列表，同时仍可跨目录发现更早的记录。
• 长对话采用增量回放，不再因为把全部历史作为一条超大消息传输而失败。
• 批准、变更审查、测试与 Artifacts 始终保留在产生它们的任务中。

2026-07-10 · Loop Engineering 与并行 Agent

• 给出一个可修改的 Goal，DeepCode 可以在普通 Turn 之间持续理解、
  实现、按需验证与修复，并且始终可被纠正。
• 将聚焦任务委派给隔离 worktree 中的 Agent，并在集成前明确暴露冲突。

更早的里程碑

• 2026-07-08 · 持久化 Sessions 与记忆。 Session 历史可以跨重启恢复；
  项目长期指令可以写入 AGENTS.md 或 DEEPCODE.md，持久笔记跟随工作区保存。
• 2026-07-08 · 通用 Coding Agent。 自由对话式 TUI、原生文件与 Shell 工具、
  无头执行、上下文压缩和跨目录恢复，建立了当前产品基础。
• 2026-07-04 · Agent Harness 基础。 统一执行约束、三值权限、
  敏感路径保护、平台 Sandbox 与标准化事件，使本地执行真正可监督。
• 重构前的完整更新记录保存在
  旧版中文 README。

What Deep means in DeepCode Copy Chapter

大多数 Coding Agent 都能生成代码。真正困难的是：理解一个真实项目、在正确的边界内完成修改、根据运行结果持续修正，并让用户清楚地知道结果为什么可信。

DeepCode 是一个面向真实软件工程的开源 Coding Agent。你可以把一个简单修改交给它，也可以给它一个需要持续数十个步骤的目标。它能够理解项目、操作代码、运行工具、验证结果，并在中断、重启或模型切换之后继续工作。

“Deep”代表四种贯穿任务始终的深度：

DeepCode 最特别的地方可以归纳为三点：

• 从复杂知识走向可运行系统。 DeepCode 不只处理 Issue 和代码片段。Paper2Code 可以从论文、文档、参考仓库和实验目标出发，完成理解、实现与验证。
• 让长任务持续运行，同时始终可控。 Goal 不是一次性的提示词。你可以在运行中补充要求、修订目标、暂停、停止或继续，而不必丢掉已经完成的工作。
• 从代码修改走到验证与审查。 DeepCode 不会停在生成 Patch。它会根据任务运行命令与测试、检查构建结果和文件变化，并把 Goal 的完成或受阻原因关联到相关执行记录，方便你审查最终修改。

DeepCode 的目标不是让 Agent 显得更忙，而是帮助你更可靠地完成真正的软件工程工作。

Core capabilities Copy Chapter

DeepCode 提供完整的本地 Coding Agent 工作流。CLI 和 Desktop 只是两种使用方式，它们共享同一套 Agent、Session、模型、Skills、权限和任务状态。

Work directly in your repository Copy Section

DeepCode 可以读取和搜索代码、编辑文件、应用 Patch、运行命令与测试，并根据结果继续修改。工具调用、执行进度和文件变化会被持续展示，你可以随时查看 Agent 做了什么以及项目发生了哪些变化。

它既适合解释代码、修复 Bug 和补充测试，也能完成跨文件重构、功能开发和较长的仓库级任务。

当你提供一个公开的 HTTP 或 HTTPS URL 时，共享的 web_fetch 工具可以直接读取页面，不需要搜索服务或额外的 API Key。

Goal-driven Loop Engineering Copy Section

对于无法在一次回答中完成的任务，你可以直接给 DeepCode 一个自然语言 Goal。Agent 会围绕目标持续进行分析、实现、验证和修复，而不需要用户手动推动每一个步骤。

运行过程中，你仍然可以：

• 向当前任务补充新的信息；
• 修订 Goal 或验收要求；
• 排队下一条指令；
• 暂停、停止或继续任务；
• 在退出程序后恢复同一个 Goal。

任务不会因为进入自动执行就失去控制权。你始终可以改变接下来的方向。

Evidence-driven completion Copy Section

DeepCode 不使用一套硬编码规则判断所有 Coding 任务。它会根据任务本身选择合适的证据，例如测试结果、构建输出、静态检查、诊断信息、文件变化、Diff 或生成的 Artifacts。

验证失败不会被包装成成功，而会成为下一轮修复的输入。任务完成或真正受阻时，结果、原因以及相关证据会继续保留在 Session 中，方便你检查和复现。

Durable Sessions and project context Copy Section

每个 Session 都会保存在本地，并关联到它最初所属的项目。你可以从任意目录启动 DeepCode，找到之前的项目和 Session，在 CLI 或 Desktop 中继续同一段工作。

Session 不只保存聊天文本，还保存工具调用、权限决策、Goal、模型配置和验证记录。项目规则、持久记忆、Skills 与长对话压缩共同帮助 Agent 在复杂任务中保持上下文连续。

Your models, your reasoning settings Copy Section

DeepCode 不绑定单一模型厂商。你可以连接 OpenRouter、OpenAI、Anthropic、DeepSeek、Gemini、OpenAI-compatible Gateway、Ollama、vLLM 或其他兼容端点，并使用自己的 API Key。

连接可以在使用前检查凭据、模型列表和真实推理请求。每个 Session 都可以选择模型与 Thinking Level；中途切换模型只影响后续 Turn，不会删除已有对话或混淆之前的工作来源。模型支持时，DeepCode 也会展示 Provider 返回的推理摘要。

Reusable Skills Copy Section

Skills 可以把团队规范、领域知识、评审方法或重复工作流变成 Agent 可复用的能力。项目 Skill 放在 .agents/skills，个人 Skill 放在 ~/.agents/skills，也可以通过内置 Skill Creator 以对话方式创建。

DeepCode 继续读取已有的 .deepcode/skills 和 Claude 风格目录，不会自动迁移。Skill 可以指导 Agent 如何工作，但不能绕过项目信任、工具权限或安全边界。

Permissions you can understand Copy Section

每个项目在执行前都需要明确信任。每个 Session 可以选择：

• Ask：敏感操作执行前询问；
• Read only：只允许分析和读取；
• Full access：对可信项目执行完整工作。

工具级别还支持 allow、ask 和 deny。CLI 与 Desktop 使用相同的权限状态，任务被停止或异常中断时，DeepCode 不会静默重放可能产生副作用的操作。

Parallel agents without file collisions Copy Section

复杂任务可以被拆分给多个专门的 Agent，例如让不同 Agent 分别负责代码调查、测试分析和实现审查。

并行修改可以运行在隔离的 Git Worktree 中，避免多个 Agent 同时修改同一个工作目录。结果返回主任务后再进行检查和整合，冲突会被明确展示，而不是被静默覆盖。主 Agent 始终负责最终 Goal，不会因为委派任务而失去方向。

Automate repeatable engineering work Copy Section

当一项工作已经足够稳定，可以把它保存为 Automation，手动运行或按时间间隔重复执行。例如：

• 定期检查测试和构建状态；
• 扫描回归问题；
• 整理待处理任务；
• 执行仓库维护或周期性审查。

Automation 不会启动另一套简化版 Agent。它仍然使用正常的 Session、模型、Skills、权限、审批和恢复机制，并保留每一次运行的历史。

Paper2Code Copy Section

Paper2Code 是 DeepCode 最初的研究方向，也是当前产品中专门面向科研复现的工作流。

它可以从论文、技术文档、URL 或参考仓库开始，理解研究目标，寻找相关实现，组织开发计划，生成代码，并通过实验与产物验证结果。它体现了 DeepCode 的核心理念：重要的不是生成一段看起来正确的代码，而是把复杂知识转化为可以运行、检查和继续改进的系统。

快速开始 Copy Chapter

DeepCode 提供两种界面，并且对应两条独立安装路径。任选一种即可开始；两端
使用相同的 Agent 运行时和规范 Session 历史。

uv tool install --python 3.12 deepcode-hku 安装的是 CLI 和共享 Python
运行时，不会安装 Tauri Desktop 应用。

方案 A：安装 CLI Copy Section

如果尚未安装 uv，请先安装。Windows PowerShell 使用：

winget install --id astral-sh.uv --exact

首次安装 uv 后重新打开终端，再执行：

uv tool install --python 3.12 deepcode-hku
deepcode init

这里显式选择 Python 是有意的：DeepCode 要求 Python 3.12+，不能在旧解释器上
回退安装已经不受支持的历史版本。
如果现有 uv tool 环境仍安装着 DeepCode 1.x，可执行
uv tool upgrade --python 3.12 deepcode-hku 完成迁移。

首次创建模型连接。--api-key 会打开不回显的安全输入：

deepcode provider set personal-openrouter --template openrouter --label "OpenRouter · Personal" --api-key
deepcode provider models personal-openrouter --refresh
deepcode provider test personal-openrouter --model <model-id>

进入希望 DeepCode 操作的仓库，然后启动交互式 Agent：

cd <你的项目>
deepcode

deepcode init 会在 ~/.deepcode/ 下创建最小用户配置。凭证单独保存在
用户私有存储中，不会进入 Session 历史。也可以在合适的 Python 3.12+
环境中使用 pipx install deepcode-hku 或 pip install deepcode-hku。

方案 B：安装 Desktop Copy Section

Desktop 安装包与 Python 包分开发布。先检查
GitHub Releases 是否提供当前
平台的签名安装包；如果没有，请使用下面的源码安装流程。

macOS 与 Linux 源码安装

请先根据 Tauri 2 前置依赖指南
安装平台依赖，并准备 Git、Python 3.12+、uv、Node.js 22+ 和稳定版 Rust。
然后执行：

git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode
uv venv --python 3.12
uv pip install --python .venv/bin/python -e .
.venv/bin/deepcode init
cd desktop
npm ci
npm run setup:sidecar
npm run build:sidecar
cd ..
mkdir -p ~/.local/bin
ln -sf "$(pwd)/scripts/deepcode-desktop" ~/.local/bin/deepcode-desktop
export PATH="$HOME/.local/bin:$PATH"
deepcode-desktop

以上步骤会完成一次性的源码启动器安装。以后只要 ~/.local/bin 已加入
PATH，就可以从任意目录运行 deepcode-desktop 启动这个源码版本。如果
Shell 尚未配置该路径，请把上述 export 写入 Shell profile。命令只负责启动
Desktop；需要操作的仓库仍应在 Project 侧边栏中添加或选择。

Windows 源码安装

Windows 必须安装 Microsoft Edge WebView2，以及 Visual Studio 2022 Build
Tools 的 Desktop development with C++ 工作负载。Build Tools 弹出 UAC
提示时请选择“是”：

winget install --id Git.Git --exact
winget install --id astral-sh.uv --exact
winget install --id OpenJS.NodeJS.LTS --exact
winget install --id Rustlang.Rustup --exact
winget install --id Microsoft.VisualStudio.2022.BuildTools --exact `
  --override "--wait --passive --norestart --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

关闭 PowerShell，重新打开一个窗口并验证工具链：

git --version
uv --version
node --version
rustup default stable-msvc
rustc --version
cargo --version

克隆、准备并启动 Desktop：

git clone https://github.com/HKUDS/DeepCode.git
Set-Location DeepCode
uv venv --python 3.12
uv pip install --python .venv\Scripts\python.exe -e .
.venv\Scripts\deepcode.exe init
Set-Location desktop
npm ci
$env:DEEPCODE_PYTHON = (Resolve-Path ..\.venv\Scripts\python.exe)
npm run setup:sidecar
npm run build:sidecar
npm run tauri -- dev

Desktop 运行期间请保持这个 PowerShell 窗口开启。后续启动和故障排查请参考
Desktop 源码运行指南。

配置 Desktop 模型

Desktop 启动后，打开 Settings → AI providers。

1. 点击 Add provider，选择模型服务，并输入 API Key 或保存它的环境变量名。
2. 点击 Save and check，检查凭证并读取 Provider 的模型目录；这一阶段不会
   发送项目内容。
3. 在 Agent model 中选择准确的模型 ID，然后点击 Save and verify
   model；最后一步只会发送一次极小的真实推理请求。
4. 添加或打开 Project，创建 Session，选择模型、Thinking 档位和权限，然后
   用自然语言描述任务。

使用界面只改变工作的呈现方式，不改变背后的 Agent、策略、配置和 Session
历史。

使用 DeepCode Copy Chapter

Sessions Copy Section

每项工作都保存在与原始 Project 关联的持久 Session 中。在 Desktop 打开
Project，或者从项目目录启动 deepcode，然后创建新 Session 或恢复历史。
同一份历史可以直接在 Desktop 与 CLI 之间继续，无需导出或转换。

对话、工具活动、审批、Goal 状态和验证证据始终保存在一起。Archive 只隐藏
Session，不删除历史；永久删除只移除 Session 记录，不会删除项目文件。

Connections 与模型 Copy Section

Desktop 在 Settings → AI providers 中提供连接配置与验证。CLI 使用
/model 修改后续 Turn 的连接和模型，使用 /effort 选择该模型支持的
Thinking 档位。

模型切换不会改写已有历史，也不会改变正在运行的 Turn。Thinking 档位决定
发送给 Provider 的请求；transcript 详细程度只影响界面展示。DeepCode 只在
Provider 明确提供时展示推理摘要，不会把原始 chain-of-thought 混入助手回答。

环境变量凭证、自定义网关、模型发现和机器可读检查等管理命令统一收录在
Headless 与 Automation 指南。

Skills Copy Section

Skills 可以把可复用的工程知识变成 Agent 在任务中加载的指导。Desktop
提供 Skills 工作区；交互式 CLI 使用 /skills 发现可用 Skill，使用
/skill <名称> 为下一个 Turn 选择能力。在 Desktop 选择 Skills → Create
Skill，或在 CLI 调用 $skill-creator，即可通过普通 Agent Turn 创建并校验。

项目级 Skills 存放在 .agents/skills 并可随仓库共享，用户级 Skills 存放在
~/.agents/skills 并可跨 Project 使用。旧 DeepCode 与 Claude 风格目录继续
兼容读取。Skill 只能指导 Agent，不能授予权限，也不能绕过 Project trust、
审批或工具策略。导入、启用、禁用和目录管理命令统一放在
高级指南中。

MCP 服务器 Copy Section

DeepCode 的 Agent Session、Desktop、TUI、管理 CLI 与 App Server 共用同一套
MCP 客户端。Desktop 在 MCP Servers 页面管理；TUI 统一使用 /mcp；
Shell 中可先运行 deepcode mcp presets 查看内置的 16 个 Nanobot 模板，再用
deepcode mcp add 添加配置。模板默认禁用，不会自动下载依赖或启动进程。

用 deepcode mcp test <名称>、/mcp test <名称> 或 Desktop 的 Test connection
进行真实 MCP 初始化和能力枚举，确认后再用 deepcode mcp enable <名称>、
/mcp enable <名称> 或 Desktop 的 Enable 启用。启用后，用户只需正常
描述 coding 任务，模型会在需要时自动调用 MCP 工具。Notion、Linear、Xmind 等 OAuth
服务通过 login/logout 或 Desktop 的 Authenticate/Logout 显式授权；凭据
单独保存在私有文件中，Agent 启动不会自动打开浏览器。配置方式、环境变量、
OAuth 与三类状态的说明见 MCP 客户端指南。

安全与执行 Copy Section

DeepCode 将执行安全视为产品边界，而不是客户端确认框：

• 所有界面在执行 Agent 之前都需要明确的 Project trust。
• 权限决策分为 allow、ask 和 deny。
• Approval 会恢复被暂停的同一次工具调用。
• Ask 保留工作区命令沙箱和受保护路径检查；Read only 拒绝修改型
  工具；Full access 是经过明确二次确认的 Session 授权，会移除审批与
  文件系统沙箱边界，但显式 deny 规则仍然优先。
• CLI 与 Desktop 修改同一个 Session 权限覆盖。每个 Turn 在进入队列时都会
  冻结完整安全快照，因此切换只影响新提交；正在运行和已经排队的 Turn 会在
  恢复或 worker 交接后继续使用各自记录的权限。
• Shell 与代码进程在超时、中断或关闭时会按 DeepCode 所有的进程树终止。
• 崩溃恢复会收敛未完成的 Turn，但不会自动重放副作用。

长期任务 Copy Section

普通输入就可以运行包含多个工具调用的完整 Coding Turn。当任务需要跨多个
Turn 或进程重启继续时，再把持久 Goal 绑定到 Session。Desktop 使用 Goal
面板，CLI 使用 /goal <目标>。

DeepCode 工作期间，新输入可以纠正当前 Turn。你也可以编辑 Goal、停止当前
Turn、安排后续指令、暂停 Goal，或者稍后恢复。所有操作都保留相同的 Session、
历史、权限、Skills 与验证证据，不会变成一次孤立执行。

工作 Agent 根据完整上下文显式请求 complete 或 blocked。DeepCode 强制
检查归属、生命周期、权限和预算边界，但不会用一条宿主规则冒充对所有 coding
任务的验证。普通语义完成显示为 Completed；测试、Build、诊断、Diff 或
独立复核继续作为可见证据。Goal 引擎不会硬编码 provider、模型、任务类型或
测试命令。

Automation 与无界面工作流 Copy Section

Desktop 的 Automation 工作区可以把可信 Project 中的一条指令保存为手动或
定时任务，同时继续使用正常的 Agent、Session、Goal、权限、恢复和 Run 历史。
它适合仓库健康检查、回归审查和周期性维护等可重复工作。

Shell 脚本和 CI 也可以在不打开界面的情况下调用相同运行时。独立的
Headless 与 Automation 指南
集中说明 exec、loop、Automation、Provider、Skill 和 Session 管理命令。
这些是高级集成入口，普通 Desktop 或 CLI 用户无需用它们拼接日常任务。

Paper2Code Copy Chapter

Paper2Code 是 DeepCode 的研究起点，也是当前面向科研代码复现的专业工作流。
通用 Coding Agent 扩展了产品边界，但没有替代或简化 Paper2Code 的原始设计。

它的核心思路始终不变：论文复现不是一次性代码生成任务。一个中央编排智能体
负责协调多个边界清晰的专业角色，依次完成来源理解、复现规划、参考发现与索引、
代码实现以及结果验证。

原始架构 Copy Section

各专业角色继续保持原系统中清晰的职责分离：

四个核心思想把这些角色连接为一个整体：

• 智能编排。 中央 Agent 根据任务状态选择并回访不同阶段，而不是把论文复现
  当作固定的一次性 Prompt 链。
• 文档与意图对齐。 论文、规格、URL 与附件会先转化为明确实现要求，再进入
  编码阶段。
• 记忆与 CodeRAG。 长文档与参考仓库经过分段、索引和按需检索，以有边界的
  上下文进入模型，而不是反复塞入整个窗口。
• 迭代验证。 执行、测试与真实失败会回流到规划和实现阶段，直到交付结果
  拥有可以检查的证据。

配套工具层同样延续这一职责划分：

新版产品围绕这套流程增加了持久化计划、显式计划审查、检查点、有边界重试与
交互式检查能力。这些变化增强了恢复和监督，但没有改变 Paper2Code 的架构
职责与推理顺序。

研究结果 Copy Section

DeepCode 原始研究使用
PaperBench 评估科研代码复现能力。
该基准要求 Agent 复现 20 篇 ICML 2024 论文，共包含 8,316 个可评分组件。

| 75.9%
人类专家子集领先 3.5 个百分点 | 84.8%
商业 Agent 子集领先 26.1 个百分点 | 73.5%
科研编程领先 22.4 个百分点 | 73.5%

LLM Agent 基线领先 30.2 个百分点 |
| --- | --- | --- | --- |

以上是原论文报告的 PaperBench 专项结果，不代表通用编程基准，也不代表对
持续更新中的商业产品进行实时比较。

评估方法、范围、模型和基线详情请阅读
论文。

🎬 实时演示 Copy Chapter

下面的录像展示了早期 DeepCode 工作流生成的项目结果。它们是输出案例，
不是当前 Desktop 界面的截图。

| #### 📄 Paper2Code

从研究到实现

▶ 观看演示

将研究论文复现为可以执行的工程项目。 | #### 🖼️ 生成式视觉项目

图像工作流案例

▶ 观看演示

查看早期 DeepCode 生成的图像处理工作流。 | #### 🌐 生成式 Web 项目

前端实现案例

▶ 观看演示

从想法开始，查看完整前端项目的实现结果。 |
| --- | --- | --- |

项目介绍视频继续提供更完整的产品说明。

开发 Copy Chapter

源码安装 Copy Section

git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python=3.13
source .venv/bin/activate
uv pip install -e .

Windows PowerShell 请使用 .\.venv\Scripts\Activate.ps1 激活环境。

验证 Copy Section

uvx pre-commit run --all-files
python -m compileall -q app_server cli core tools workflows
deepcode --version
deepcode-app-server --verify-runtime

cd desktop
npm run lint
npm test -- --run
npm run build

Desktop 打包、Rust 检查、签名和发布流程请参考
desktop/README.md 与
Desktop 发布手册。

贡献者架构资料

重构前的中文 README 保存在
docs/archive/README_ZH_LEGACY_2026-07-20.md。
新版产品图片占位使用同一份
截图要求。

⭐ 星标历史 Copy Chapter

🚀 准备好使用 DeepCode 了吗？ Copy Section

🙏 致谢 Copy Chapter

感谢开源社区的每一位——你们的 star、issue、pull request 和讨论，
共同塑造了 DeepCode 的走向。

所有提交过 pull request 的贡献者都记录在
CONTRIBUTORS.md 中，其中也包含早于 v2.0 重构、
因而未体现在上方贡献图中的那些贡献。

📖 引用 Copy Chapter

如果 DeepCode 对您的研究有所帮助，请引用：

@misc{li2025deepcodeopenagenticcoding,
  title         = {DeepCode: Open Agentic Coding},
  author        = {Zongwei Li and Zhonghang Li and Zirui Guo and Xubin Ren and Chao Huang},
  year          = {2025},
  eprint        = {2512.07921},
  archivePrefix = {arXiv},
  primaryClass  = {cs.SE},
  url           = {https://arxiv.org/abs/2512.07921}
}

📄 许可证 Copy Chapter