Metadata-Version: 2.4
Name: deepcode-hku
Version: 2.0.0
Summary: Open agentic coding with durable sessions, goals, and verification
Home-page: https://github.com/HKUDS/DeepCode
Author: DeepCode Team
License: MIT
Project-URL: Documentation, https://github.com/HKUDS/DeepCode#readme
Project-URL: Source, https://github.com/HKUDS/DeepCode
Project-URL: Tracker, https://github.com/HKUDS/DeepCode/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=0.8.0
Requires-Dist: aiohttp>=3.14.1
Requires-Dist: anthropic>=0.40.0
Requires-Dist: asyncio-mqtt
Requires-Dist: google-genai
Requires-Dist: httpx>=0.27.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp<2,>=1.29
Requires-Dist: mcp-server-git
Requires-Dist: nest_asyncio
Requires-Dist: openai>=1.55.0
Requires-Dist: openapi
Requires-Dist: pathlib2
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pypdf>=6.14.2
Requires-Dist: PyYAML>=6.0
Requires-Dist: reportlab>=3.5.0
Requires-Dist: rich>=13.0.0
Provides-Extra: advanced-documents
Requires-Dist: docling>=2.113.0; extra == "advanced-documents"
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: pytest-asyncio<2,>=1; extra == "test"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

<table style="border: none; margin: 0 auto; padding: 0; border-collapse: collapse;">
<tr>
<td align="center" style="vertical-align: middle; padding: 10px; border: none; width: 250px;">
  <img src="assets/logo.png" alt="DeepCode Logo" width="200" style="margin: 0; padding: 0; display: block;"/>
</td>
<td align="left" style="vertical-align: middle; padding: 10px 0 10px 30px; border: none;">
  <pre style="font-family: 'Courier New', monospace; font-size: 16px; color: #0EA5E9; margin: 0; padding: 0; text-shadow: 0 0 10px #0EA5E9, 0 0 20px rgba(14,165,233,0.5); line-height: 1.2; transform: skew(-1deg, 0deg); display: block;">    ██████╗ ███████╗███████╗██████╗  ██████╗ ██████╗ ██████╗ ███████╗
    ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██╔═══██╗██╔══██╗██╔════╝
    ██║  ██║█████╗  █████╗  ██████╔╝██║     ██║   ██║██║  ██║█████╗
    ██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ██║     ██║   ██║██║  ██║██╔══╝
    ██████╔╝███████╗███████╗██║     ╚██████╗╚██████╔╝██████╔╝███████╗
    ╚═════╝ ╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝</pre>
</td>
</tr>
</table>

<div align="center">
<a href="https://trendshift.io/repositories/14665" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14665" alt="HKUDS%2FDeepCode | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</div>

<!-- <img src="https://readme-typing-svg.herokuapp.com?font=Russo+One&size=28&duration=2000&pause=800&color=06B6D4&background=00000000&center=true&vCenter=true&width=800&height=50&lines=%E2%9A%A1+OPEN+AGENTIC+CODING+%E2%9A%A1" alt="DeepCode Tech Subtitle" style="margin-top: 5px; filter: drop-shadow(0 0 12px #06B6D4) drop-shadow(0 0 24px rgba(6,182,212,0.4));"/> -->

# <img src="https://github.com/Zongwei9888/Experiment_Images/raw/43c585dca3d21b8e4b6390d835cdd34dc4b4b23d/DeepCode_images/title_logo.svg" alt="DeepCode Logo" width="32" height="32" style="vertical-align: middle; margin-right: 8px;"/> DeepCode: Open Agentic Coding

### *Advancing Code Generation with Multi-Agent Systems*

<!-- <p align="center">
  <img src="https://img.shields.io/badge/Version-1.0.0-00d4ff?style=for-the-badge&logo=rocket&logoColor=white" alt="Version">

  <img src="https://img.shields.io/badge/License-MIT-4ecdc4?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License">
  <img src="https://img.shields.io/badge/AI-Multi--Agent-9b59b6?style=for-the-badge&logo=brain&logoColor=white" alt="AI">
  <img src="https://img.shields.io/badge/HKU-Data_Intelligence_Lab-f39c12?style=for-the-badge&logo=university&logoColor=white" alt="HKU">
</p> -->
<p>
  <a href="https://github.com/HKUDS/DeepCode/stargazers"><img src='https://img.shields.io/github/stars/HKUDS/DeepCode?color=00d9ff&style=for-the-badge&logo=star&logoColor=white&labelColor=1a1a2e' /></a>
  <a href='https://arxiv.org/abs/2512.07921'><img src="https://img.shields.io/badge/Paper-arXiv-orange?style=for-the-badge&logo=arxiv&logoColor=white&labelColor=1a1a2e"></a>
  <img src="https://img.shields.io/badge/🐍Python-3.12%2B-4ecdc4?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
  <!-- <a href="https://pypi.org/project/deepcode-hku/"><img src="https://img.shields.io/pypi/v/deepcode-hku.svg?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a2e&color=ff6b6b"></a> -->
</p>
<p>
  <a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
  <a href="https://github.com/HKUDS/.github/blob/main/profile/README.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
</p>
<div align="center">
  <div style="width: 100%; height: 2px; margin: 20px 0; background: linear-gradient(90deg, transparent, #00d9ff, transparent);"></div>
</div>

<div align="center">
  <a href="#quick-start" style="text-decoration: none;">
    <img src="https://img.shields.io/badge/Quick%20Start-Get%20Started%20Now-00d9ff?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e">
  </a>
</div>

<div align="center" style="margin-top: 10px;">
  <a href="README.md">
    <img src="https://img.shields.io/badge/English-00d4ff?style=for-the-badge&logo=readme&logoColor=white&labelColor=1a1a2e" alt="English">
  </a>
  <a href="README_ZH.md">
    <img src="https://img.shields.io/badge/中文-00d4ff?style=for-the-badge&logo=readme&logoColor=white&labelColor=1a1a2e" alt="中文">
  </a>
</div>

### 🖥️ **Interface Showcase**

#### 🖥️ **DeepCode Desktop**

<div align="center">

  <img src="https://github.com/Zongwei9888/Experiment_Images/raw/e389750e733ec2c1b94986cb990036899dcaec52/DeepCode_images/Area.gif" alt="DeepCode Desktop coding agent demo" width="100%" style="border-radius: 10px; box-shadow: 0 8px 20px rgba(45,55,72,0.3); margin: 15px 0;"/>

*Work with DeepCode in a visual workspace for Sessions, goals, tool activity, code changes, and verification.*
</div>

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`](desktop/README.md) to run the application locally.

---

<div align="center">

### 🎬 **Introduction Video**

<div style="margin: 20px 0;">
  <a href="https://youtu.be/PRgmP8pOI08" target="_blank">
    <img src="https://img.youtube.com/vi/PRgmP8pOI08/maxresdefault.jpg"
         alt="DeepCode Introduction Video"
         width="75%"
         style="border-radius: 12px; box-shadow: 0 8px 25px rgba(0,0,0,0.15); transition: transform 0.3s ease;"/>
  </a>
</div>

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

<p>
  <a href="https://youtu.be/PRgmP8pOI08" target="_blank">
    <img src="https://img.shields.io/badge/▶️_Watch_Video-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch Video"/>
  </a>
</p>

</div>

---

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

</div>

---

## 📑 Table of Contents

- [📰 News](#news)
- [🧠 What Deep means in DeepCode](#what-deep-means-in-deepcode)
- [🚀 Core capabilities](#core-capabilities)
  - [Agent Harness](#agent-harness)
  - [Loop Engineering](#loop-engineering)
  - [Context Engineering](#context-engineering)
  - [Evidence-driven completion](#evidence-driven-completion)
  - [Durable local work](#durable-local-work)
  - [Models and Skills under your control](#models-and-skills-under-your-control)
  - [Parallel and repeatable work](#parallel-and-repeatable-work)
- [⚡ Quick start](#quick-start)
- [🧭 Using DeepCode](#using-deepcode)
- [⚙️ Headless and automation](docs/HEADLESS_AND_AUTOMATION.md)
- [🔬 Paper2Code](#paper2code)
  - [The original architecture](#the-original-architecture)
  - [Research results](#research-results)
- [🎬 Live demonstrations](#live-demonstrations)
- [🛠️ Development](#development)
- [⭐ Star History](#star-history)
- [📖 Citation](#citation)
- [📄 License](#license)

<p align="center">
  <img src="assets/readme/deepcode-overview.png" alt="A verified task completed with DeepCode" width="1080" />
</p>

## News

**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.

<details>
<summary><strong>Earlier milestones</strong></summary>

- **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](docs/archive/README_LEGACY_2026-07-20.md).

</details>

## 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:

| Depth                 | What it means for you                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Deep Context**      | Understand the task through project structure, engineering rules, Skills, Session history, and long-term memory.       |
| **Deep Execution**    | Search, edit, run commands, and execute tests instead of stopping at suggestions—and show the work as it happens.       |
| **Deep Verification** | Check results with tests, builds, diagnostics, Diffs, and task Artifacts rather than treating a plausible answer as done. |
| **Deep Continuity**   | Preserve conversations, decisions, tool records, and evidence across time, directories, clients, and model changes.    |

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.

<p align="center">
  <img src="assets/readme/verification-loop.png" alt="DeepCode Agent Harness and verification loop" width="1080" />
</p>

### 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. Store Skills with a project or
install them in your user directory, then select them when a task needs them.

DeepCode supports both DeepCode and Claude-style Skill directories. 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:

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

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

```console
uv tool install deepcode-hku
deepcode init
```

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

```console
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:

```console
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](https://github.com/HKUDS/DeepCode/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](https://v2.tauri.app/start/prerequisites/), plus
Git, Python 3.12+, `uv`, Node.js 22+, and stable Rust. Then run:

```bash
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:

```powershell
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:

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

Clone, prepare, and start Desktop:

```powershell
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](desktop/README.md#windows-powershell) for subsequent
launches and troubleshooting.

#### Configure the Desktop model

Open **Settings → AI providers** after Desktop starts.

<div align="center">
  <img src="assets/setting_model.png" alt="Configure an AI provider and model in DeepCode Desktop" width="100%" style="border-radius: 10px; box-shadow: 0 8px 20px rgba(45,55,72,0.2); margin: 15px 0;"/>

  <sub>Provider credentials, model discovery, and inference verification stay in one Desktop workflow.</sub>
</div>

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.

| What you want to do | Desktop | Interactive CLI |
|---|---|---|
| Start a Session | **New thread** | `/new [title]` |
| Resume local history | Select it under the Project | `/resume` |
| Find history from every Project | Browse the project list | `/resume all` |
| Attach a file | Use the composer attachment | `@path/to/file` |
| Change the next Turn's model | Composer model picker | `/model` |
| Adjust Thinking effort | Composer effort picker | `/effort` |
| Choose tool access | Composer access picker | `/permissions` |
| Load Skills for the next Turn | Composer Skills control | `/skill <name>` |
| Set or revise a durable Goal | Goal panel | `/goal` |
| Stop the active Turn | Use the stop control | `/stop` |

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](docs/HEADLESS_AND_AUTOMATION.md#connection-and-model-management).

### 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.

Project Skills can travel with a repository, while user Skills remain available
across Projects. DeepCode also recognizes Claude-compatible Skill directories.
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](docs/HEADLESS_AND_AUTOMATION.md#skill-management).

### 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](docs/HEADLESS_AND_AUTOMATION.md) 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

<p align="center">
  <img src="assets/readme/framework2.png" alt="Paper2Code framework from source documents through code generation, verification, and refinement" width="1080" />
</p>

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

| Role                            | Responsibility                                                                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Central Orchestrating Agent** | Interprets progress, selects the next phase, coordinates specialists, and adapts the plan when evidence changes.                    |
| **Intent Understanding Agent**  | Turns the user's objective into explicit functional requirements, technical constraints, and an actionable task decomposition.      |
| **Document Parsing Agent**      | Processes papers and technical documents, extracting algorithms, equations, methods, assumptions, and implementation requirements.  |
| **Code Planning Agent**         | Converts the understood method into an implementation roadmap, module boundaries, dependencies, interfaces, and verification goals. |
| **Code Reference Mining Agent** | Discovers relevant repositories, libraries, and implementation patterns, then evaluates their relevance and integration potential.  |
| **Code Indexing Agent**         | Builds a searchable semantic index and knowledge graph so useful components and relationships can be recovered during generation.   |
| **Code Generation Agent**       | Synthesizes the plan and evidence into executable code, tests, documentation, and the interfaces needed for a reproducible result.  |

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:

| Layer                     | Purpose                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Document ingestion        | Fetch and normalize papers, URLs, PDFs, DOCX, presentations, text, and HTML.                      |
| Document segmentation     | Divide long technical material into coherent, recoverable sections for analysis.                  |
| Reference discovery       | Find candidate repositories and supporting implementations.                                       |
| Code reference indexing   | Build searchable context over external and local code, including cross-file relationships.        |
| Implementation execution  | Read and write files, run shell or Python commands, inspect the project structure, and keep logs. |
| Verification and delivery | Run tests, record results, and deliver the codebase together with documentation and Artifacts.    |

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.

<!--
README VISUAL SLOT — PAPER2CODE WORKFLOW

Add a current Paper2Code workflow capture at:
  assets/readme/paper2code-workflow.png

Capture:
- the workflow plan or checkpoint state;
- one verification result;
- the Artifact/Inspector surface.

Do not reuse the legacy browser UI screenshot.
-->

### Research results

The original DeepCode study evaluates scientific code reproduction on
[PaperBench](https://openai.com/index/paperbench/), which asks agents to
reproduce 20 ICML 2024 papers across 8,316 gradable components.

<table align="center" width="100%">
<tr>
<td width="25%" align="center">
  <strong>75.9%</strong><br/>
  <sub>Human expert subset<br/>+3.5 points</sub>
</td>
<td width="25%" align="center">
  <strong>84.8%</strong><br/>
  <sub>Commercial-agent subset<br/>+26.1 points</sub>
</td>
<td width="25%" align="center">
  <strong>73.5%</strong><br/>
  <sub>Scientific coding<br/>+22.4 points</sub>
</td>
<td width="25%" align="center">
  <strong>73.5%</strong><br/>
  <sub>LLM-agent baseline<br/>+30.2 points</sub>
</td>
</tr>
</table>

<p align="center">
  <img src="assets/result_main02.jpg" alt="DeepCode PaperBench results" width="920" />
</p>

| Evaluation subset       | DeepCode | Reported comparison                   | Difference   |
| ----------------------- | -------- | ------------------------------------- | ------------ |
| Human expert subset     | 75.9%    | Best reported human baseline: 72.4%   | +3.5 points  |
| Commercial-agent subset | 84.8%    | Best reported commercial agent: 58.7% | +26.1 points |
| Scientific coding       | 73.5%    | PaperCoder: 51.1%                     | +22.4 points |
| LLM-agent baseline      | 73.5%    | Best reported LLM agent: 43.3%        | +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](https://arxiv.org/abs/2512.07921) for methodology, evaluation
scope, models, and baseline details.

<a id="live-demonstrations"></a>

## 🎬 Live Demonstrations

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

<table align="center" width="100%">
<tr>
<td width="33%" align="center">

#### 📄 Paper2Code

**Research to implementation**

<a href="https://www.youtube.com/watch?v=MQZYpLkzsbw">
  <img src="https://img.youtube.com/vi/MQZYpLkzsbw/maxresdefault.jpg" alt="Paper2Code demonstration" width="100%" />
</a>

**[▶ Watch demonstration](https://www.youtube.com/watch?v=MQZYpLkzsbw)**

<sub>Reproduce a research paper as an executable project.</sub>

</td>
<td width="33%" align="center">

#### 🖼️ Generated vision project

**Image workflow example**

<a href="https://www.youtube.com/watch?v=nFt5mLaMEac">
  <img src="https://img.youtube.com/vi/nFt5mLaMEac/maxresdefault.jpg" alt="Generated image-processing project" width="100%" />
</a>

**[▶ Watch demonstration](https://www.youtube.com/watch?v=nFt5mLaMEac)**

<sub>See an earlier generated image-processing workflow in use.</sub>

</td>
<td width="33%" align="center">

#### 🌐 Generated web project

**Frontend implementation example**

<a href="https://www.youtube.com/watch?v=78wx3dkTaAU">
  <img src="https://img.youtube.com/vi/78wx3dkTaAU/maxresdefault.jpg" alt="Generated frontend project" width="100%" />
</a>

**[▶ Watch demonstration](https://www.youtube.com/watch?v=78wx3dkTaAU)**

<sub>Follow a complete frontend implementation from idea to result.</sub>

</td>
</tr>
</table>

The [project introduction](https://youtu.be/PRgmP8pOI08) remains available for
a broader walkthrough.

## Development

### Source installation

```bash
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

```bash
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`](desktop/README.md) and the
[Desktop release runbook](docs/DESKTOP_RELEASE_RUNBOOK.md).

<details>
<summary><strong>Contributor architecture notes</strong></summary>

| Topic                                         | Document                                                      |
| --------------------------------------------- | ------------------------------------------------------------- |
| Agent execution and approvals                 | [P2 Agent execution](docs/P2_AGENT_EXECUTION_ARCHITECTURE.md) |
| Desktop sidecar and lifecycle                 | [P3 Desktop runtime](docs/P3_DESKTOP_RUNTIME_ARCHITECTURE.md) |
| Git review, files, terminal, and tests        | [P4 Code workbench](docs/P4_CODE_WORKBENCH_ARCHITECTURE.md)   |
| Durable Paper2Code workflow                   | [P5 Paper2Code](docs/P5_PAPER2CODE_ARCHITECTURE.md)           |
| Canonical Sessions and cross-directory resume | [P6 Session alignment](docs/P6_SESSION_ALIGNMENT_REVIEW.md)   |
| Skills identity, security, and persistence    | [Skills architecture](docs/SKILLS_PRODUCT_ARCHITECTURE.md)    |
| Automation scheduling and execution           | [Automation architecture](docs/AUTOMATION_ARCHITECTURE.md)    |
| Desktop product and interaction model         | [Desktop UI specification](docs/DESKTOP_PRODUCT_UI_SPEC.md)   |
| Privacy and diagnostics                       | [Privacy contract](docs/PRIVACY_AND_DIAGNOSTICS.md)           |

</details>

The pre-restructure README is preserved in
[`docs/archive/README_LEGACY_2026-07-20.md`](docs/archive/README_LEGACY_2026-07-20.md).
The empty product-image slots have a shared
[capture brief](assets/readme/README.md).

---

<a id="star-history"></a>

## ⭐ Star History

<div align="center">

*Community growth trajectory*

  <a href="https://star-history.com/#HKUDS/DeepCode&Date">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/DeepCode&type=Date&theme=dark" />
      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/DeepCode&type=Date" />
      <img src="https://api.star-history.com/svg?repos=HKUDS/DeepCode&type=Date" alt="DeepCode Star History chart" width="900" />
    </picture>
  </a>

</div>

---

### 🚀 Ready to build with DeepCode?

<div align="center">

<p>
  <a href="#quick-start"><img src="https://img.shields.io/badge/🚀_Get_Started-00d4ff?style=for-the-badge&logo=rocket&logoColor=white" alt="Get started" /></a>
  <a href="https://github.com/HKUDS/DeepCode"><img src="https://img.shields.io/badge/🏛️_View_on_GitHub-00d4ff?style=for-the-badge&logo=github&logoColor=white" alt="View DeepCode on GitHub" /></a>
  <a href="https://github.com/HKUDS/DeepCode/stargazers"><img src="https://img.shields.io/badge/⭐_Star_Project-00d4ff?style=for-the-badge&logo=star&logoColor=white" alt="Star DeepCode" /></a>
</p>

</div>

---

<a id="citation"></a>

## 📖 Citation

If DeepCode contributes to your research, cite:

```bibtex
@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}
}
```

---

<a id="license"></a>

## 📄 License

<div align="center">

<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-4ecdc4?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="MIT License" /></a>

DeepCode is available under the [MIT License](LICENSE).<br/>
Copyright © 2025 Data Intelligence Lab at The University of Hong Kong.

</div>
