HKUDS/DeepCode

---

📑 Table of Contents

• 📰 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
• 📖 Citation
• 📄 License

News

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! 🚀

2026-07-31 · One execution model across CLI and Desktop

• Interactive, headless, Goal, Automation, and Desktop work all use the same durable Project, Session, Thread, and Turn lifecycle.
• Workspace trust is explicit and independent from the Session access preset: Ask, Read only, or Full access.
• Model-aware Thinking controls and typed reasoning presentation remain separate, so changing display detail never changes the model request.

2026-07-21 · Durable Goals and safe Session lifecycle

• Run long tasks as resumable, evidence-driven Goals shared by CLI and Desktop.
• Archive history for later or permanently delete it through one guarded Session lifecycle, without touching repository files.
• Interrupted deletions recover from a durable tombstone instead of reviving stale Session records.

2026-07-20 · Session-level model control and shared Skills

• Configure named LLM connections once and use them throughout DeepCode.
• Switch the connection or model for future Turns without losing the conversation that came before it.
• Discover, import, enable, and select the same project or user Skills regardless of how the task was started.

2026-07-17 · Durable Session navigation and replay

• Projects organize their own collapsible Session history while older Sessions remain discoverable across directories.
• Long conversations replay incrementally instead of being rejected as one oversized message.
• Approvals, change review, tests, and Artifacts remain attached to the task that produced them.

2026-07-10 · Loop Engineering and parallel agents

• Give DeepCode a mutable Goal; it can inspect, implement, verify where appropriate, and repair across ordinary Turns while remaining steerable.
• Delegate focused work to agents in isolated worktrees, then surface conflicts explicitly before integration.

Earlier milestones

• 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

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

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

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

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

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

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

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

Skills turn team conventions, domain knowledge, review methods, and repeated workflows into reusable Agent capabilities. 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

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

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

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

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

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 deepcode-hku installs the CLI and shared Python runtime. It does not install the Tauri Desktop application.

Option A — Install the CLI

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 deepcode-hku
deepcode init

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

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

Sessions

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. Archiving hides a Session without deleting its history; permanent deletion removes the Session records but never repository files.

Connections and models

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

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.

Safety and execution

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

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

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

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

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

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

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

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

The project introduction remains available for a broader walkthrough.

Development

Source installation

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

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

Topic	Document
Agent execution and approvals	P2 Agent execution
Desktop sidecar and lifecycle	P3 Desktop runtime
Git review, files, terminal, and tests	P4 Code workbench
Durable Paper2Code workflow	P5 Paper2Code
Canonical Sessions and cross-directory resume	P6 Session alignment
Skills identity, security, and persistence	Skills architecture
Automation scheduling and execution	Automation architecture
Desktop product and interaction model	Desktop UI specification
Privacy and diagnostics	Privacy contract

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

---

🚀 Ready to build with DeepCode?

---

📖 Citation

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