Metadata-Version: 2.4
Name: deepcode-hku
Version: 2.2.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.3
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.16.1
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?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-14665" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/14665" alt="HKUDS%2FDeepCode | Trendshift" width="250" height="55"/></a>
<a href="https://trendshift.io/repositories/14665?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-14665" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/14665/daily?language=Python" alt="HKUDS%2FDeepCode | Trendshift" 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">
  <a href="https://hkuds.github.io/DeepCode/" target="_blank"><img alt="Website — hkuds.github.io/DeepCode" src="https://img.shields.io/badge/Website-hkuds.github.io%2FDeepCode%20%E2%86%97-06B6D4?style=for-the-badge&labelColor=0B1116" height="36"></a>
</p>

<!-- <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)
  - [Work directly in your repository](#work-directly-in-your-repository)
  - [Goal-driven Loop Engineering](#goal-driven-loop-engineering)
  - [Evidence-driven completion](#evidence-driven-completion)
  - [Durable Sessions and project context](#durable-sessions-and-project-context)
  - [Your models, your reasoning settings](#your-models-your-reasoning-settings)
  - [Reusable Skills](#reusable-skills)
  - [Permissions you can understand](#permissions-you-can-understand)
  - [Parallel agents without file collisions](#parallel-agents-without-file-collisions)
  - [Automate repeatable engineering work](#automate-repeatable-engineering-work)
  - [Paper2Code](#paper2code)
- [⚡ Quick start](#quick-start)
- [🧭 Using DeepCode](#using-deepcode)
- [⚙️ Headless and automation](docs/HEADLESS_AND_AUTOMATION.md)
- [🔬 Paper2Code](#paper2code-1)
  - [The original architecture](#the-original-architecture)
  - [Research results](#research-results)
- [🎬 Live demonstrations](#-live-demonstrations)
- [🛠️ Development](#development)
- [⭐ Star History](#-star-history)
- [🙏 Appreciation](#-appreciation)
- [📖 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-09-06 · DeepCode v2.2.0: Session context-window caps, compaction that leaves a memory, and a fully localized Desktop**

- **Cap a Session's context window.** `/context 64k` in the TUI or the
  preset next to the Desktop model picker narrows the model's published
  window for future Turns; the cap is frozen into each accepted Turn and
  feeds the compaction gate directly. `/context auto` follows the model
  again. (#203)
- **Compaction leaves a note in memory, and memory notes cannot escape their
  boundary.** A compaction summary is deposited into the workspace memory on
  a background thread, and injected memory content is wrapped in an
  `<untrusted-data>` boundary whose closing tags are escaped, so a poisoned
  note cannot forge instructions. (#204)
- **Appearance settings speak Simplified Chinese too**, completing the
  Desktop shell's zh-CN coverage. (#202)

**2026-09-03 · Desktop catalog race, an honest command screen, GLM-5.2, and two dependency bumps**

- **Switching projects no longer strands the MCP catalog.** A probe or
  mutation started in one project can no longer invalidate the load of the
  project you switched to, so the catalog stops sticking in a loading state.
  (#201)
- **The legacy `execute_bash` screen matches on argv, not substrings.**
  `rm -r -f`, `--recursive --force`, `chmod 0777` and a destructive stage
  inside a pipeline are caught; `touch rm-rf-notes.txt` is not. It stays a
  cheap first pass in front of the sandbox, which remains the boundary.
  (#195)
- **GLM-5.2 is in the model catalog** — 1M context, 128K output,
  `reasoning_effort` `high` / `max`. (from #198)
- **Security bumps:** `browserslist` past GHSA-c83g-rgw3-j3cx in the Desktop
  toolchain, and the App Server sidecar's `pypdf` to 6.16.1
  (CVE-2026-84309/84310/84311).

**2026-08-28 · Community fixes: plugin credential warnings and a wider zh-CN Desktop**

- **Agent Plugin manifests now warn about plaintext credentials.** Literal
  `env` and `headers` values in a Plugin's `mcp.json` that look like secrets
  produce a redacted warning instead of loading silently, and the docs point
  to runtime credential bindings instead. (#194, landed 2026-08-27)
- **Most of the Desktop shell speaks Simplified Chinese.** The thread header,
  Goal rail, approval card, inspector, sidebar, and the Updates and
  Diagnostics settings gained about a hundred zh-CN strings; English stays
  the inline default. (#187)

**2026-08-25 · Command executors close two bypasses**

- **Case and whitespace no longer slip past the dangerous-command check**, and
  the native `mkdir`/`touch`/`rm`/`cp`/`mv` fast path declines any operand
  outside the working directory, so those commands run through the sandbox
  like every other command instead of as in-process file operations. (#193)

**2026-08-23 · Five repaired contributions land together**

- **MCP servers can start lazily.** `deferLoading` keeps a server off until
  the agent calls `activate_server`; deferred servers stay reachable and
  cancellation-safe. (#184)
- **Hooks see the whole lifecycle.** `SessionEnd` runs exactly once at
  teardown and `PreCompact` can inject context before a compaction. (#172)
- **Instruction files can be excluded, and the dangerous preset must be named
  explicitly.** (#186)
- **Windows private files get a fail-safe ACL**, applied once at creation
  (#164); the Desktop sidecar's pip pin also moved past PYSEC-2026-3721 (#191).

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

<details>
<summary><strong>Earlier August 2026 updates</strong></summary>

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

</details>

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

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

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

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

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

Prefer a guided walkthrough? The [teaching guides](docs/guide/README.md) cover
the same ground page by page — first session, the TUI, sessions, models,
skills and memory, and headless automation — with worked examples.

### 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` |
| Cap the Session context window | Model picker context control | `/context` |
| Choose tool access | Composer access picker | `/permissions` |
| Load Skills for the next Turn | Composer Skills control | `/skill <name>` |
| Create a reusable Skill | **Skills → Create Skill** | `$skill-creator` |
| Set or revise a durable Goal | Goal panel | `/goal` |
| Queue the next instruction | Composer while a Turn runs | `/queue <text>` |
| Stop the active Turn | Use the stop control | `/stop` |
| Re-run the last Turn | Retry control on the Turn | `/retry` |
| Compact a long conversation | Automatic under pressure | `/compact` (also automatic) |
| Change transcript detail | — | `/transcript` or `Ctrl+O` |
| Rename or delete a Session | Session context menu | `/rename <title>` · `/delete <id>` |

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

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.
Use the model picker's context control, or `/context 64k` in the TUI, to make
future Turns compact history sooner; `/context auto` restores the model's
published window.

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

### Local Plugins

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 <path>`; 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](docs/LOCAL_PLUGINS.md).

### MCP servers

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 <id>` 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](docs/integrations/OPENSPACE.md). Setup, preset, OAuth, and
connection-state details are in the [MCP client guide](docs/integrations/MCP.md).

### 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)    |
| Generic MCP setup and connection lifecycle     | [MCP client guide](docs/integrations/MCP.md)                  |
| OpenSpace integration                          | [OpenSpace integration](docs/integrations/OPENSPACE.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="contributors"></a>

## 🙏 Appreciation

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

<div align="center">

<a href="https://github.com/HKUDS/DeepCode/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=HKUDS/DeepCode&max=999" alt="DeepCode contributors" />
</a>

</div>

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

---

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