deepcode

What you will run into

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

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

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.

Step by step

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.

pip install deepcode-hku
deepcode --version

Expected output: DeepCode 2.1.0 Domestic acceleration branch (recommended, verified):

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.

deepcode init

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

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

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.

How to confirm it works

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.

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.

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.

Other environments

• Python version: >= 3.12 required; dependencies are heavy with a large install window — domestically, definitely use the Tsinghua mirror branch.
• Windows / macOS: pip install and init commands are the same (mirror still recommended); config also goes to ~/.deepcode/.
• venv / conda: if the command is not found, activate the virtualenv first; uninstall only removes the pip package, user data ~/.deepcode/ is kept by default.
• Source install (method B): git clone + pip install -e ., not verified here, commands from upstream README.
• Co-install with other tools: CLI form verified coexisting with oh-my-claudecode / agent-governance-toolkit (local repro log), does not write ~/.claude.json.

Daily usage

Startup and entry

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

Common operations

Operation 1: View the command list

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)

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)

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)

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

Uninstall & cleanup

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

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

rm -rf ~/.deepcode

Dependency warnings

• 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).

FAQ

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