HKUDS/DeepCode: an agent harness for paper-to-code and repo-scale tasks

What DeepCode is for, and who it is for

DeepCode is an agentic coding system, not an autocomplete plugin. The README describes it as transforming research papers and natural language into production-ready code, and the repository topics name the same three concerns: agentic-coding, harness-engineering and llm-agent. The harness is the product here. DeepCode is for engineers who want to drive a coding agent from a terminal, a desktop window or a browser and keep the same projects, session history, models, Skills, permissions, Goals and Automations across all three. The README states that the TUI, desktop and web clients sit over one shared local service. That single-service design is the reason to pick it over a per-editor assistant: the agent runs as a process you control, and the clients are views onto it. It is a poor fit for anyone who wants a plugin that lives inside an IDE and never leaves it.

The harness: one local service, three clients, durable sessions

The architecture visible in the repository is a Python agent runtime plus a set of front ends. The top level holds cli/, core/, app_server/, desktop/, protocol/, schema/, prompts/, tools/ and workflows/, with deepcode.py at the root as the entry module. The README says the clients share Projects, Session history, models, Skills, permissions, Goals and Automations, and that you reach them with `deepcode`, `deepcode desktop` or `deepcode web`. The presence of app_server/ and protocol/ alongside a Rust toolchain file and a desktop/ directory matches that claim: the desktop client is not a separate agent, it is a client of the same service. The pyproject.toml confirms the packaging boundary. The Python sdist contains the shared Agent runtime and CLI, while desktop, tests, CI material and README artwork are distributed from the source repository and Desktop release bundles instead of the PyPI source archive. If you install from PyPI expecting the desktop app, you will not get it. The runtime also carries an MCP layer: requirements.txt pins `mcp>=1.29,<2` and `mcp-server-git`, and there is an examples/mcp/ directory. The comment in requirements.txt calls this the DeepCode-native LLM plus MCP runtime that replaces a legacy mcp-agent dependency.

Installing DeepCode and running a first task

The distribution name is deepcode-hku, and setup.py reads the version from core/version.py, so the package version tracks the release tags such as v2.2.0. The README badge states Python 3.12 or newer, and pyproject.toml targets py312 for linting. Create an environment on 3.12 or later and install the package.

pip install deepcode-hku

After installation, the README gives three entry commands. The bare command starts the terminal client, which is the fastest way to see whether the runtime is wired up correctly.

deepcode

The other two open the desktop and web clients, which connect to the same local service rather than starting their own agent.

deepcode desktop
deepcode web

Provider credentials come from the installed client libraries. requirements.txt lists `anthropic>=0.40.0`, `openai>=1.55.0` and `google-genai`, so the runtime can talk to several providers. The README does not spell out which environment variables each client reads, so set the key your chosen provider's own SDK expects and confirm the model appears in the session before starting work. A first real use is a small, self-contained task in a scratch project rather than a live repository, so you can read the full session log and see which tools the agent invoked.

Where DeepCode falls short

The project labels itself beta. setup.py carries the classifier Development Status :: 4 - Beta, and the README does not document rollback, upgrade or migration paths between v2.0.0, v2.1.0 and v2.2.0. For a tool that edits source files and runs tools on your machine, that gap matters more than a missing feature. The permission model is named in the README's list of shared state but the excerpt does not describe how a permission is granted, scoped or revoked, so treat the sandbox boundary as something you verify in core/ before trusting it on a repository you care about. The test configuration in pyproject.toml is a useful signal about the surface area: it sets `faulthandler_timeout = 60` with `faulthandler_exit_on_timeout = true`, and the comment records that on 2026-09-13 a TUI test blocked inside CreateProcess during ACL hardening in core/private_storage.py and the suite produced no output until morning. A stalled Windows process spawn was enough to hang a test run. If your work is a one-file edit in an editor you already have open, the local service, the session store and the client layer are overhead you will not recover.

DeepCode compared with Claude Code and OpenCode

The comparison people search for is DeepCode against Claude Code, and the difference is structural rather than a feature list. Claude Code is a terminal agent tied to one vendor's models. DeepCode's requirements.txt pulls in the Anthropic, OpenAI and Google client libraries at once, so the model is a configuration choice inside a runtime that also owns sessions, goals and automations. Against OpenCode, the difference is the client topology. OpenCode is a terminal-first agent; DeepCode runs a local service and puts a TUI, a desktop application and a web client on top of it, with the desktop client distributed as a release bundle rather than through PyPI. The trade-off is real in both directions. A single-vendor agent gets tighter integration with its own models and a smaller surface to debug. DeepCode gets provider choice and one shared session history across three interfaces, and pays for it with a Python service, a protocol layer and a beta label. It is also not the DeepCode that appears in searches alongside Snyk; that is a different, unrelated product with the same name.

Licence, maintenance and the cost of upgrading

DeepCode is MIT licensed, and the LICENSE file sits at the repository root. The MIT terms are permissive, but the repository also ships THIRD_PARTY_NOTICES.md, and pyproject.toml notes that bundled Skills under core/skills/builtin are pinned, provenance-tracked upstream packages that Ruff is told to leave alone. If you redistribute DeepCode or vendor those Skills, read the third-party notices rather than assuming the MIT grant covers everything in the tree. That is a description of the files, not legal advice. On maintenance: the repository is not archived, and the last push was on 2026-09-17. The release cadence visible in the tags is roughly monthly, v2.0.0 on 2026-08-03, v2.1.0 on 2026-08-12 and v2.2.0 on 2026-09-06. Three major-version bumps in about five weeks is the upgrade cost in one line. The README does not document a migration path between them, so pin the version you validate and read the diff before moving.

Editorial conclusion

Adopt DeepCode if you want an inspectable Python agent harness with durable sessions, goals and a shared local service behind TUI, desktop and web clients, and if you are willing to read the source when the README stops short. Do not adopt it if you need a stable, versioned API surface: setup.py still classifies it as Development Status 4 - Beta, and the README does not document rollback, upgrade or migration paths. Verify first that your Python is 3.12 or newer and that your provider key works with the installed anthropic or openai client, then run one small task end to end and read the session log before pointing it at a real repository.

Frequently asked questions

Official sources

1. HKUDS/DeepCode on GitHub
2. License: MIT
3. Project website
4. README
5. Releases