DeepCode Logo 
    ██████╗ ███████╗███████╗██████╗  ██████╗ ██████╗ ██████╗ ███████╗
    ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██╔═══██╗██╔══██╗██╔════╝
    ██║  ██║█████╗  █████╗  ██████╔╝██║     ██║   ██║██║  ██║█████╗
    ██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ██║     ██║   ██║██║  ██║██╔══╝
    ██████╔╝███████╗███████╗██║     ╚██████╗╚██████╔╝██████╔╝███████╗
    ╚═════╝ ╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
HKUDS%2FDeepCode | Trendshift HKUDS%2FDeepCode | Trendshift
# DeepCode Logo DeepCode: Open Agentic Coding ### *Advancing Code Generation with Multi-Agent Systems*

Website — hkuds.github.io/DeepCode

Feishu WeChat

English 中文
### 🖥️ **Interface Showcase** #### 🖥️ **DeepCode Desktop**
DeepCode Desktop coding agent demo *Work with DeepCode in a visual workspace for Sessions, goals, tool activity, code changes, and verification.*
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. ---
### 🎬 **Introduction Video**
DeepCode Introduction Video
*🎯 **Watch our complete introduction** - See how DeepCode transforms research papers and natural language into production-ready code*

Watch Video

--- > *"Where AI Agents Transform Ideas into Production-Ready Code"*
--- ## 📑 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) - [🙏 Appreciation](#contributors) - [📖 Citation](#citation) - [📄 License](#license)

A verified task completed with DeepCode

## News **2026-08-19 · Sessions that survive resume, compaction, and a second window** - **Resuming a session restores what the agent did, not only what it said.** Tool calls and their results are part of the canonical record now, so a resumed agent can answer "what did you just run?". A test makes the rule executable: every request a run sends must be rebuildable from the session file alone. - **Compaction keeps the recent tail.** The checkpoint replaces the older range and everything recent survives verbatim — assistant messages and tool results included — instead of dropping them and putting the summary last. Manual `/compact` used to refuse almost every real conversation; it works, and the checkpoint speaks as the model's own history, so it stops being discounted as someone else's report. - **Context pressure is measured, not guessed.** The gate now anchors on the size the provider itself reports. The built-in estimator prices Chinese prose at more than twice its real cost, which was compacting Chinese conversations at roughly half the context they could hold. - **Two windows on one Session no longer crash each other.** Each Session now has one live writer, enforced by an OS lock held around a turn: the second window gets a sentence naming who is running it, instead of a process dying to a database constraint about half the time. Alternate freely between Desktop and the terminal — just not mid-turn. **2026-08-18 · The runtime learns dsh's context discipline, and the TUI gets a face** - **A new turn no longer throws away the prompt cache.** The environment block used to be re-inserted before your newest message every turn, so each turn diverged from the previous request right where that block had been: 7,420 prompt tokens recomputed at every turn boundary, now 28. - **The TUI has a logo, a live status line, and tool cards that read.** A spinner and a sweep while work runs, paths written the way you would type them, the plan tool's checklist visible at last, and a turn footer with its time and token usage. An idle TUI costs nothing to animate. - **A source-level comparison against dsh became a plan.** Where the message list the model sees comes from, what compaction should keep, and what the session record must contain — measured and written down, and four unreferenced documents retired. **2026-08-17 · Fixes from a review pass over the new settings and TUI work** - **A declared model reads the same everywhere.** Per-model declarations now shape the catalog a picker shows, not only what a Turn executes with, so a context window you set to avoid overflow is the number you see. - **Adopting fetched models shows them immediately.** The catalog cache is keyed on the settings that shape it, instead of serving the previous remote listing for up to an hour. - **Escape closes one thing.** Dismissing the provider editor no longer tears down the settings dialog around it and discards a half-typed key. - **A removed model row takes its own capacities with it** rather than leaving them on the row that survived — which then saved them onto the wrong model. - **Automated runs keep their tools.** A default agent preset chosen for interactive chatting no longer narrows `deepcode exec` and goal runs behind your back. - **The provider section says it is user-scoped**, instead of letting the dialog's project write scope imply otherwise. **2026-08-16 · The TUI answers every bare command with a selector** - **Type the command, pick from a list.** `/model` now opens the full model directory — every configured connection's catalog (remote snapshot or declared entries, near a thousand rows on OpenRouter) in one filterable selector with the current route pinned first and each model's published reasoning ladder on Shift+Tab; Enter commits model and effort together. `/preset`, `/effort`, `/permissions`, `/transcript` and `/skill` join `/resume`: a bare invocation opens a picker with the current choice marked, while argument forms and piped runs keep their text paths. - **Background tracebacks can no longer shred the transcript.** Stdlib logging is bridged into loguru with call-site fidelity, so file-only transports really are file-only; and the durable event relay backs off exponentially on persistent failure — one traceback per streak, one-line repeats, a recovery notice. **2026-08-15 · Settings grow up: a dsh-style dialog, declared models, and a safer config** - **A connection's key now reaches exactly the requests it was resolved for.** Building a provider no longer exports the key into the process environment, where every same-template connection could pick it up as its own; removing a provider un-configures every key source instead of letting it reappear; and when a launch environment variable shadows a pasted key, the editor says which one and that it wins. Verification also works from async hosts now. - **The agent-preset picker grew up.** A menu with per-preset descriptions and trust marking replaces the cramped native dropdown, the duplicate "Default" row is gone, and a started session shows a read-only label of what it runs. - **Manage what each connection actually serves.** The provider editor can fetch the live model list from a connection's endpoint and adopt picked models as its manual list, an environment-provided key locks the paste field instead of silently outranking it, and connection rows show the discovered model count. - **`deepcode chat` reads like a terminal app, not a log.** A restyled transcript — brand-gradient banner, status-colored tool cards with result elbows, block spacing, word-boundary wrapping — plus streaming that survives the prompt redraw with real colors instead of `?[36m` litter. - **Desktop Settings became a dsh-style dialog.** General / Models / Plugins / Agent presets in a left rail, with Open configuration file and the write-scope picker in the header. General gains the five canonical rows — default agent preset for new sessions (applied as a by-value snapshot at creation, CLI and TUI included), permissions, language (English/中文, first translated batch), Light/Dark/System appearance cards, and a steer-or-queue busy-Enter preference. - **Models are declarations now.** `manualModels` entries can carry a label, capacities, and the published reasoning ladder; declarations are authoritative offline for execution profiles and every picker. Discovery probes the editor form as shown — unsaved URL or key included — and adopted picks land as accurate declaration rows. Config writes gained optimistic concurrency (a changed file conflicts instead of being clobbered) and a settings.changed push keeps an open dialog fresh. - **Session and model commands now hold up.** `/resume` and `/model` open an inline selector — type to filter by title, arrows move, Enter picks, Tab flips directory scope, Shift+Tab cycles the route's published reasoning effort — and resume replays the conversation tail. Bare model names resolve their connection, typos no longer kill the REPL, and `/compact` summarizes with the model you actually selected. New verbs: `/rename`, `/delete`, `/retry`, with tab completion for session ids, transcript modes, permission presets, and effort levels.
Earlier August 2026 updates **2026-08-14 · Subagent runtime, compaction, and one-way persistence** - **Delegate to Codex or Claude Code as a subagent.** `spawn_agent` gains external backends that run the installed CLI with a scrubbed environment and strict success criteria, while native subagents gain personas, validated tool allowlists, JSON output schemas, follow-up conversation via `send_message`, and full transcripts in the parent session. - **Guard the loop.** Tools can declare timeouts the runner enforces, and a repeat-call tracker injects an escalating, model-visible reminder when identical calls repeat. - **Compact on demand.** `/compact` summarizes older turns in the resident context; every refusal is a stable, readable reason (busy Turn, too little history, a failed or non-shrinking summary) and canonical session data is never touched. - **See which file set every configuration value.** Diagnostics report each configured leaf with its providing layer and a bounded preview; credential-shaped subtrees are redacted whole. A verbatim deepseek-harness Skill also loads unchanged from `.agents/skills`. - **Relieve context pressure with the cheapest sufficient measure.** Under pressure the runtime first middle-prunes oversized tool results — a free, convergent pass covering MCP and custom tools alike — and only summarizes if that is not enough; the summarization call replays the routed request as a genuine prefix so provider prompt caching is reused, and a summary that would not shrink the conversation is rejected. - **Deleted sessions stay deleted.** The Desktop projection no longer adopts a thread back into canonical storage unless SQLite genuinely owns it (legacy import or automation bootstrap), and every mid-turn message the model sees — goal updates, recovery prompts, injected results — now lands in the canonical session log, so a resumed session rebuilds exactly the history the model saw. - **Open a session as a different agent.** Named agent presets bundle a persona and a tool face — `deepcode exec --preset code-reader`, `/preset` in the TUI, or the picker beside the Desktop model control — while the model route and permissions stay independent knobs. A preset is one markdown agent file in the `.claude/agents`/`.agents` dialect, so definitions written for other harnesses load unchanged; the resolved composition is snapshotted into the session record and locked once the conversation starts, at which point the Desktop picker becomes a read-only label of what the session runs. **2026-08-13 · Desktop typography, themes, and native controls** - **Make the type-size preference actually resize the app.** Every interface size now derives from one rem-based scale, so the Appearance slider moves the whole window. It previously moved almost nothing: 255 hardcoded pixel values ignored it, and the smallest labels sat at 7px. - **Pick from eight themes, including high contrast.** Light, Dark, Paper, and Midnight are joined by two terracotta palettes and a WCAG AAA high-contrast option. Tests compare each palette against the complete token set, so a theme cannot half-apply and leave a stray default showing through. - **See one design language rather than the operating system's.** Sliders, selects, and focus rings now follow the active theme instead of falling back to platform chrome, and an explicit theme choice moves `color-scheme` with it so native controls stop rendering in the OS scheme. - **Read the quiet text.** The light palette's secondary tones and every accent colour were refitted to clear WCAG AA against the surfaces they actually sit on, several of which previously measured under 3:1. **2026-08-12 · Reviewed upstream core Skills** - **Start with reviewed upstream Skills.** DeepCode now bundles eight pinned, provenance-tracked Agent Skills from OpenAI, Codex, and Anthropic for Skill authoring, code review, security analysis, frontend design, MCP construction, and web application testing. They use the same catalog and Turn runtime as project, user, and Plugin Skills. **2026-08-12 · Managed MCP catalog, OAuth, and real connection checks** - **Start from reviewed templates without hidden execution.** DeepCode bundles a validated catalog based on Nanobot's current 16 MCP templates. Adding one copies ordinary user configuration in a disabled state; it never silently runs `npx`, Docker, or a remote server. - **Configure MCP consistently in every interface.** Desktop and TUI now join the management CLI and App Server on one preset, configuration, test, OAuth, and live-status service rather than maintaining interface-specific clients. - **Distinguish config, authorization, and connectivity.** A real MCP probe initializes the server and counts tools, resources, and prompts. Browser OAuth uses a loopback callback and a private credential file outside project configuration, while Agent startup never opens a browser implicitly. **2026-08-10 · Generic MCP runtime and portable local Plugins** - **Connect standard MCP servers from every interface.** User and trusted project configuration, App Server, CLI, and Desktop now share one generic stdio/SSE/Streamable HTTP client runtime with bounded discovery, stable tool identities, timeouts, cancellation, and session-owned cleanup. - **Keep credentials and authority explicit.** Executable config layers replace whole entries, child processes receive a minimal environment, provider keys stay in private DeepCode connections, and MCP policy can only narrow global trust, read-only, approval, and sandbox decisions. - **Run Agent Plugins 1.0 MCP components without format forks.** Valid `mcp.json` servers join the same runtime only when an Agent Session starts, receive isolated `PLUGIN_ROOT` / `PLUGIN_DATA`, and fail independently from bundled Skills and other servers. - **Connect OpenSpace as MCP plus two ordinary Skills.** A reviewed recipe binds an OpenRouter connection without plaintext secrets, imports OpenSpace's host Skills into the standalone catalog, and keeps cloud/upload tools disabled by default. - **Register trusted local Plugin folders.** CLI and Desktop now share a user-level Plugin registry with add, inspect, enable, disable, and unregister operations; unregistering never deletes source files. - **Keep one execution path.** Enabled Plugins contribute authority-bound Skills through the existing Skill Provider host, so selection, dependencies, progressive reads, permissions, revisions, and audit metadata remain the same across CLI, TUI, headless execution, and Desktop. - **Preserve standalone Skills.** Project and user Skills remain independently installable and take precedence over a same-named Plugin Skill. Plugins are an optional packaging source, never a replacement Skill lifecycle. - **Use one portable package contract.** Local Plugins use the Agent Plugins 1.0.0 root manifest and fixed `skills/` layout; experimental DeepCode manifests are no longer accepted. Hooks, Apps, Marketplaces, downloads, and updates remain inert. **2026-08-09 · Skills now have a real runtime contract** - **Load guidance through one provider boundary.** Skill discovery, content reads, and package search now stay with the provider that owns the Skill, while the catalog remains metadata-only. Local Skills keep their existing precedence and identity, and future providers no longer need filesystem shortcuts to fit the runtime. - **Compose Skills without hiding missing capabilities.** Skills can declare tool and Skill dependencies; DeepCode expands them in order, detects cycles, and fails before the first model request when a requirement is unavailable. - **Reveal only what the task needs.** The Agent can search and read bounded package resources progressively, with revision, traversal, symlink, and size checks applied at the shared provider contract. - **Keep execution constrained and auditable.** A Skill can narrow the tools already allowed by the Session but cannot grant new permissions. CLI, TUI, and Desktop share the same immutable Turn snapshot and persist only Skill identity, invocation kind, and revision—not the instruction body. - **See changes everywhere without restarting.** One workspace host now owns the shared catalog and provider cache, while each Agent Session keeps its own Turn context. Local Skill and policy changes refresh Desktop automatically, and Composer, management, CLI, and headless execution resolve through the same lifecycle. **2026-08-07 · Thinking controls, more providers, and a Desktop you can tune** - **Reasoning controls work again across the board.** Thinking levels are now resolved from the model catalog, so Claude, GPT-5, Kimi, Qwen and Grok all offer their real effort levels, and DeepSeek, GLM and MiniMax get a working thinking toggle. A newly released model inherits its family's controls instead of silently losing them. - **Three more providers.** Requesty and Forge join as gateways, and MiniMax arrives with its own catalog entry — including the 1M-context M3 tier. - **Make the Desktop yours.** Settings → Appearance adds conversation width, a light/dark override that no longer follows the OS blindly, font size, and font selection filtered to what is actually installed on your machine. - **Safer command execution on Windows.** A Job Object backend gives the sandbox real process-tree isolation where previously there was none. **2026-08-04 · Skills that work wherever you do** - **Keep reusable expertise close to your work.** DeepCode discovers Skills from the current project as well as your personal collection, while keeping existing DeepCode and Claude-compatible Skill locations working. - **Use the same Skill from CLI or Desktop.** Select it for a task and DeepCode carries its identity and version with the Turn, so the Session shows which guidance shaped the result. - **Create Skills without leaving DeepCode.** The built-in Skill Creator helps you scaffold and validate focused, reusable workflows from either interface. - **Stay focused as your library grows.** Context-aware discovery keeps the Agent prompt concise while the complete Skill catalog remains available to browse and manage. **2026-08-03 · 🎉 DeepCode v2.0 is here** DeepCode v2.0 introduces a new general-purpose Coding Agent framework for building, fixing, understanding, and improving real software projects. - **Take on real repository work.** DeepCode can explore a codebase, edit files, run commands and tests, review changes, and carry a task through to a working result. - **Keep complex goals moving with Loop Engineering.** Give DeepCode a goal and it can continue through understanding, implementation, verification, and repair instead of stopping after one plausible answer. - **Stay in control while the Agent works.** Add requirements, correct its direction, switch models, stop, resume, or revise the goal without throwing away the work already completed. - **See what you are getting.** Plans, tool activity, code changes, test results, and verification evidence stay visible so the result is easier to review and trust. - **Build Automations around the way you work.** Turn any natural-language instruction into a project-specific task: run it on demand or on a recurring interval, then edit, pause, resume, and review every result. Use it for the work you want DeepCode to keep taking care of, from regression checks and test repair to documentation upkeep and repository maintenance. - **Work your way.** Use Desktop or CLI, bring your own models and Skills, and delegate focused work without changing the underlying Agent workflow. DeepCode v2.0 is built to help you spend less time supervising every step and more time shipping software you are proud of. We cannot wait to see what you build! 🚀
Earlier 2026 milestones - **2026-07-31 · One execution model across CLI and Desktop.** Interactive, headless, Goal, Automation, and Desktop work share the same durable Project, Session, Thread, and Turn lifecycle. Workspace trust stays independent from the Session access preset, and reasoning controls remain model-aware. - **2026-07-21 · Durable Goals and safe Session lifecycle.** Long-running Goals are resumable across CLI and Desktop, while guarded archival and deletion preserve repository files and recover safely after interruption. - **2026-07-20 · Session-level model control and shared Skills.** Named LLM connections and future-Turn model switches preserve conversation history; project and user Skills are shared across entry points. - **2026-07-17 · Durable Session navigation and replay.** Projects organize collapsible Session history, long conversations replay incrementally, and approvals, reviews, tests, and Artifacts remain attached to their task. - **2026-07-10 · Loop Engineering and parallel agents.** Mutable Goals can inspect, implement, verify, and repair across steerable Turns, while focused work can be delegated in isolated worktrees with explicit conflict handling. - **2026-07-08 · Durable Sessions and memory.** Session history survives restarts, project instructions can live in `AGENTS.md` or `DEEPCODE.md`, and persistent notes remain with the workspace. - **2026-07-08 · General coding agent.** The free-form TUI, native file and shell tools, headless execution, context compaction, and cross-directory resume established the current product foundation. - **2026-07-04 · Agent Harness foundation.** A shared execution contract, three-valued permissions, sensitive-path protection, platform sandboxing, and normalized events made supervised local execution possible. - The complete pre-restructure history is preserved in the [legacy README](docs/archive/README_LEGACY_2026-07-20.md).
## 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.

DeepCode Agent Harness and verification loop

### 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 ``` Enter the repository you want DeepCode to work in and start the interactive Agent: ```console cd 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.
Configure an AI provider and model in DeepCode Desktop Provider credentials, model discovery, and inference verification stay in one Desktop workflow.
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` | | Choose tool access | Composer access picker | `/permissions` | | Load Skills for the next Turn | Composer Skills control | `/skill ` | | 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 ` | | 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 ` · `/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. 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>