HKUDS (HKU Data Intelligence Lab)'s open-source agentic coding framework (MIT, ~16k stars): it advances code generation with a multi-agent system, built around durable sessions / goals / verification — sessions and goals persist, so tasks can run long and resume from breakpoints. It offers a TUI CLI and a Desktop interface sharing the same agent runtime; natively supports MCP, Skills, plugin registration and paper reproduction (deepcode test <paper>).

In one sentence: it is itself an "agent workbench" — install it, configure a model, and it can run coding tasks.

You want to let an AI coding agent actually "do the task" from the terminal: break down a goal, execute it, and produce results — deepcode-hku is a headless multi-agent coding system for that. The most common pitfalls: the install window is large (many dependencies, PyPI official direct measured ~16s, right at pip's 15s read-timeout edge, so installs die mid-way), deepcode is not found after install (venv PATH), and tasks report "no provider" (you must configure an LLM provider first). This guide covers "install → init → provider → first task" with verified commands (provider/task steps not verified here — no API key, marked accordingly).

When to use it:

• Running agentic coding tasks headless from the CLI (deepcode exec "..." -w .);
• Wanting multi-agent breakdown and execution inside a terminal workflow;
• Using MCP/skill/plugin/session/schedule/automation surfaces from --help.

When not to use it: you just want an interactive IDE-style agent; or you cannot provide any LLM provider (local provider also works).

note: verified path on this machine; mainland use the Tsinghua mirror branch (PyPI official ~16s is at the timeout edge)

# Source: Trove detailed guide · verified 2026-08-28
pip install deepcode-hku --index-url https://pypi.tuna.tsinghua.edu.cn/simple
deepcode --version

Expected output: DeepCode 2.1.0

Step 1: Confirm the CLI and config surface

Why: deepcode --version confirms the version; after deepcode init, checking that ~/.deepcode/deepcode_config.json exists confirms the initialization path.

# Source: Trove detailed guide · verified 2026-08-28
deepcode --version
ls ~/.deepcode/deepcode_config.json 2>/dev/null && echo "config: OK" || echo "config: MISSING"

Expected output: DeepCode 2.1.0; config: OK

Stuck? How to recover:

• config missing → run deepcode init (idempotent; prompts --force if it exists);
• command not found → activate the venv in venv scenarios; confirm the pip install path is on PATH.

Step 2: Confirm the task path (configure a provider first)

Why: getting a minimal coding task to run and produce a result file confirms the provider + workspace path; without a provider the task errors immediately.

# Source: Trove detailed guide · verified 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

Expected output: headless task run progress and final result (not verified here — no API key; command from --help)

Stuck? How to recover:

• provider missing prompt → back to "Step by step" step 2 and run provider set;
• task fails mid-way → locate it from the logs; confirm the workspace path first.

pip installs deepcode-hku (CLI deepcode). Dependencies are heavy, so the install window is large; mainland PyPI official direct measured ~16s — right at pip's 15s read-timeout edge — while the Tsinghua mirror took 40s and completed fully (verified). First use requires deepcode init (creates ~/.deepcode/deepcode_config.json, idempotent) and a configured provider (deepcode provider set <vendor> --api-key <key>); without a provider, exec-style tasks fail immediately.

Key concepts:

• init: idempotent config bootstrap (writes ~/.deepcode/deepcode_config.json);
• provider: LLM provider config — required for exec tasks (local provider needs no cloud API key);
• exec: headless multi-agent task entry (deepcode exec "<goal>" -w .).

Where it writes: ~/.deepcode/ (config and data); does not write ~/.claude.json.

• Config: ~/.deepcode/ (user data: provider config, sessions, goals)
• Runtime: TUI CLI and Desktop share the same agent runtime; MCP serve opens a server port
• Registration: MCP/Skills/plugin commands write their respective registrations

Step 1: Install the main package (why prefer the Tsinghua mirror: official source measured ~16s, at pip's 15s read-timeout edge)

Why: deepcode-hku has many dependencies; direct PyPI official from mainland measured ~16s on a preflight — right at pip's default 15s read-timeout edge, so installs often die mid-way. The Tsinghua mirror completed all dependencies in 40s (verified) — the more stable path. Verify with deepcode --version after install.

# Source: Trove detailed guide · verified 2026-08-28
pip install deepcode-hku
deepcode --version

Expected output: DeepCode 2.1.0

Domestic acceleration branch (recommended, verified):

# Source: Trove detailed guide · verified 2026-08-28
pip install deepcode-hku --index-url https://pypi.tuna.tsinghua.edu.cn/simple
deepcode --version

Expected output: DeepCode 2.1.0

After install, confirm:

• deepcode --version prints DeepCode 2.1.0;
• deepcode --help shows init/test/mcp/skill/plugin/provider/session/exec/loop/schedule/automation.

Stuck? How to recover:

• pip timeout/won't install → confirm Python >= 3.12; reinstall with the Tsinghua mirror branch;
• command not found → activate the venv in venv scenarios; confirm the pip install path is on PATH;
• source install (method B, not tested) → git clone https://github.com/HKUDS/DeepCode.git && cd DeepCode && pip install -e . && deepcode --version (commands from upstream README).

Step 2: Init + configure provider (prerequisite for running tasks)

Why: deepcode init is idempotent and generates ~/.deepcode/deepcode_config.json. Then you must configure an LLM provider — exec tasks will not run without one. Commands from --help, not verified here (no API key); a local provider needs no cloud API key.

# Source: Trove detailed guide · verified 2026-08-28
deepcode init

Expected output: Initialized <home>/.deepcode/deepcode_config.json (prompts --force if it already exists)

# Source: Trove detailed guide · verified 2026-08-28
deepcode provider set openai --api-key <your key>

Expected output: provider configured successfully (local provider needs no cloud API key)

After install, confirm:

• after init, the config file exists;
• after provider set, the provider list shows the configured item (via --help or before a task).

Stuck? How to recover:

• init says already exists → rerun with --force (overwrites config, use with care);
• task reports no provider → back to this step; a local provider needs no cloud API key.

Step 3: Run the first coding task (needs step 2 first)

Why: deepcode exec "..." -w . is the headless task entry; the multi-agent coding system breaks down and executes on its own. Commands from --help`, not verified here (no provider/key).

# Source: Trove detailed guide · verified 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

Expected output: headless task run progress and final result (multi-agent coding system execution)

After install, confirm:

• the task finishes normally and outputs a result file;
• task artifacts appear in the workspace.

Stuck? How to recover:

• provider missing prompt → back to step 2;
• task fails mid-way → locate it from the logs (the framework prints execution progress); confirm the workspace path first.

Startup and entry

Call the CLI directly; entry deepcode --help; no resident service.

Common operations

Operation 1: View the command list

# Source: Trove detailed guide · verified 2026-08-28
deepcode --help

Expected output: starts with Usage:, includes init/test/mcp/skill/plugin/provider/session/exec/loop/schedule/automation

Operation 2: Init config (required first use, idempotent, verified here)

# Source: Trove detailed guide · verified 2026-08-28
deepcode init

Expected output: Initialized <home>/.deepcode/deepcode_config.json (prompts --force if it already exists)

Operation 3: Configure an LLM provider (prerequisite for the agent; command from --help, not verified here — no API key)

# Source: Trove detailed guide · verified 2026-08-28
deepcode provider set openai --api-key <your key>

Expected output: provider configured successfully (local provider needs no cloud API key)

Operation 4: Minimal coding task (needs operation 3 first; command from --help, not verified here)

# Source: Trove detailed guide · verified 2026-08-28
deepcode exec "写一个 python 的 hello world 并运行" -w .

Expected output: headless task run progress and final result (multi-agent coding system execution)

Data and directories

• Config: ~/.deepcode/deepcode_config.json;
• Session/task data: under ~/.deepcode/ (default).

Same source as the tool-page matrix — 19 pairs total (7 measured compatible / 12 inferred possibly compatible / 0 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• Symptom: pip install timeout (unstable direct PyPI)
• Symptom: git clone connection reset (source install path)
• Symptom: curl certificate error (--ssl-no-revoke)
• Symptom: old Python won't install (requires-python)
• Symptom: MCP client won't start (Brave MCP WinError 2 / npx not running)
• Symptom: agent unresponsive after install (needs init + provider config)

Full four-part write-up (symptom → cause → fix → verification evidence): site docs

# Source: Trove detailed guide · verified 2026-08-28
pip uninstall -y deepcode-hku || true

note: uninstall via pip; the ~/.deepcode config directory is user data and not auto-deleted; the last line verifies zero residue

# Source: Trove detailed guide · verified 2026-08-28
pip uninstall -y deepcode-hku || true
command -v deepcode >/dev/null 2>&1 && echo "deepcode 仍存在" || echo "deepcode removed: OK"

Expected output: deepcode removed: OK

For full cleanup (user data, kept by default):

# Source: Trove detailed guide · verified 2026-08-28
rm -rf ~/.deepcode

• Runtime precheck (needs Python >= 3.12; pass = output includes the Python version)
• Official form = pip install of the PyPI package deepcode-hku (measured passing in this environment); last step is the verification command
• Each operation = one command block + expected output; init/provider are required for first use, exec/loop need an LLM provider
• pip-based uninstall; the config directory ~/.deepcode is user data and is not auto-deleted; last line verifies zero residue
• Python must be 3.12+; precheck passed install, init and help on 3.14.4

• Q: pip install timeout/won't install? A: confirm Python >= 3.12; on mainland networks use the method A domestic branch command from the install section (Tsinghua mirror verified, 40s success).
• Q: deepcode command not found? A: check whether the venv is activated (in venv scenarios install and run inside the venv); confirm the pip install path is on PATH.
• Q: Task reports no provider? A: run deepcode init first, then deepcode provider set <vendor> --api-key <key>; a local provider needs no cloud API key.
• Q: Can it be installed alongside oh-my-claudecode / agent-governance-toolkit? A: CLI mode verified coexisting (see local repro log: no interference, no ~/.claude.json writes, no venv cross-contamination); DeepCode has no Claude Code plugin form, so no ~/.claude.json shared surface.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.

• Version: [2.1.0, 2.1.0] locked (verified collection version).
• Environment: Python >= 3.12; heavy dependencies, large install window (mirror recommended).
• Network: PyPI official direct measured ~16s (may trigger pip's 15s read timeout), Tsinghua mirror full success in 40s (verified).
• Write surface: ~/.deepcode/ (config and data); does not write ~/.claude.json.
• Co-install: CLI form verified coexisting with oh-my-claudecode / agent-governance-toolkit (local repro log).

• Verified: local repro log (2026-08-27, CLI smoke: version/help/init).
• Not tested: provider config and exec tasks (no API key) — commands from --help, marked accordingly; method B source install (commands from upstream README).

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README：Quick Start CLI（uv 安装 / init / provider 连接 / 进入仓库） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
  CLI 安装与初始化——`uv tool install --python 3.12 deepcode-hku`（要求 Python 3.12+，显式选版本避免回退旧包；uv 缺失时 Windows 用 winget 装 astral-sh.uv）→ `deepcode init`（建 ~/.deepcode/ 最小配置，凭据单独存用户私有存储，不进 Session 历史）→ `deepcode provider set <name> --template ... --api-key`（创建模型连接，--api-key 为非回显提示）→ `deepcode provider models <name> --refresh` → `deepcode provider test <name> --model <id>` → `cd <项目> && deepcode` 进入交互式 Agent；pipx/pip 安装同样支持（Python 3.12+）
• 官方 README：命令面与 Sessions（TUI 斜杠命令表） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
  `deepcode` 默认进交互式 TUI；斜杠命令表——/resume（会话恢复）、/model（改模型）、/effort（思考强度）、/permissions（工具权限）、/skill（技能）、/goal（持久目标）、/queue（排队指令）、/stop、/retry、/compact、/transcript、/rename、/delete；Session 单一写者（Desktop 与 CLI 同时持有互斥，拒绝时提示持有者）；存档隐藏不删历史
• 官方 README：Skills / Local Plugins / MCP（扩展能力三件套） [官方文档 · deepcode 官方 · 2026-08-30（v2.1.0 README）]
  Skills——/skills 发现、/skill <name> 选择；项目技能 .agents/skills 随仓库走、用户技能 ~/.agents/skills 跨项目可用；$skill-creator 创建。Local Plugins——deepcode plugin add <path> 注册本地插件（Agent Plugins 1.0.0 清单 + 固定 skills/ 布局），不下载 Marketplace、不执行插件 hooks/Apps。MCP——deepcode mcp CLI（serve/list/presets/test/login/logout/enable/disable/add/remove），配置在 deepcode_config.json 顶层 mcpServers；stdio/SSE/Streamable HTTP 都支持