deepcode-hku 1.1.0__tar.gz → 1.3.0__tar.gz

{deepcode_hku-1.1.0/deepcode_hku.egg-info → deepcode_hku-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepcode-hku
-Version: 1.1.0
+Version: 1.3.0
 Summary: AI Research Engine - Transform research papers into working code automatically
 Home-page: https://github.com/HKUDS/DeepCode
 Author: DeepCodeTeam
@@ -21,21 +21,27 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiofiles>=0.8.0
 Requires-Dist: aiohttp>=3.8.0
-Requires-Dist: anthropic
+Requires-Dist: anthropic>=0.40.0
 Requires-Dist: asyncio-mqtt
 Requires-Dist: docling
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: google-genai
-Requires-Dist: mcp-agent
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: json-repair>=0.30.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: mcp>=1.0.0
 Requires-Dist: mcp-server-git
 Requires-Dist: nest_asyncio
-Requires-Dist: openai
+Requires-Dist: openai>=1.55.0
+Requires-Dist: openapi
 Requires-Dist: pathlib2
+Requires-Dist: prompt_toolkit>=3.0.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: PyPDF2>=2.0.0
 Requires-Dist: python-multipart>=0.0.6
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: reportlab>=3.5.0
+Requires-Dist: rich>=13.0.0
 Requires-Dist: streamlit
 Requires-Dist: uvicorn>=0.24.0
 Requires-Dist: websockets>=12.0
@@ -92,8 +98,8 @@ Dynamic: summary
   <!-- <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://discord.gg/yF2MmDJyGJ"><img src="https://img.shields.io/badge/💬Discord-Community-7289da?style=for-the-badge&logo=discord&logoColor=white&labelColor=1a1a2e"></a>
-  <a href="https://github.com/HKUDS/DeepCode/issues/11"><img src="https://img.shields.io/badge/💬WeChat-Group-07c160?style=for-the-badge&logo=wechat&logoColor=white&labelColor=1a1a2e"></a>
+  <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>
@@ -210,7 +216,96 @@ Dynamic: summary
 
 ## 📰 News
 
-🎨 **[2025-02] New Web UI Experience Upgrade!**
+**[2026-07-17] Extensible agents: reusable Skills, lifecycle Hooks & model-driven delegation**
+
+- **The agent chooses how to work.** DeepCode can maintain a plan, ask a focused question when genuinely blocked, and load reusable `SKILL.md` playbooks only when needed. Project and user skills under `.deepcode/skills/` — plus existing `.claude/skills/` packages — work across the CLI, web chat, and headless runs.
+- **Complex tasks delegate themselves.** The model can spawn bounded subagents with focused context, track their progress, and bring the results back into the parent task — without a special team command or a fixed workflow.
+- **Plug in your own guardrails and automation.** External command hooks cover session start, prompt submission, tool use, permission decisions, stopping, and subagent lifecycle events. DeepCode reads native hook files as well as compatible `.claude/settings.json` configurations, with timeouts and validated outputs so a broken hook cannot hang the agent.
+- **Run DeepCode from any folder.** `deepcode init` creates a user-level base under `~/.deepcode`; user configuration, instructions, and memory are layered with project overrides, so credentials stay global while repository-specific behavior follows the workspace. Configuration failures now show a clear setup hint instead of a traceback.
+
+---
+
+**[2026-07-10] Team mode: split a big feature across parallel workers**
+
+- **A team, not just one agent.** Hand DeepCode a larger feature and it breaks the work into pieces, builds them at the same time, and combines the results — each piece checked against your tests as it goes.
+- **Parallel work that never collides.** Every worker builds on its own isolated copy of your project, so simultaneous changes can't corrupt each other; when two pieces touch the same code, the overlap is flagged instead of silently overwritten.
+- **Only ships when the tests pass.** Once everything is combined, the whole feature runs against your test command — the team reports success only when the tests are actually green.
+
+---
+
+**[2026-07-10] Loop engineering: give it a goal, it works until the tests pass**
+
+- **Autonomous coding loops.** Hand DeepCode a goal and a test command — it works, runs your tests, and keeps fixing until they pass, on its own.
+- **Self-tidying memory.** The agent periodically cleans up its own notes, so its memory stays sharp across sessions.
+- **Run it on a schedule.** Kick off a loop or a memory tidy-up on an interval, with sensible stop conditions so it never runs away.
+
+---
+
+**[2026-07-08] Agent Chat, polished: memory, folder picker, session management**
+
+- **The agent remembers across sessions.** Drop an `AGENTS.md` (or `DEEPCODE.md`) at your project root for standing instructions, and the agent keeps its own persistent notes under `.deepcode/memory/` — so a fact it learned yesterday is there today. Works the same in the CLI, the web chat, and headless runs.
+- **Point it at a real project folder.** New chats get a workspace picker — browse and choose the directory the agent works in (fenced to your home), instead of typing a path blind.
+- **Manage your conversations.** Rename or delete any chat from the sidebar; a new chat stays a draft until you send the first message, so the list no longer fills with empty sessions. Each chat's folder is shown and remembered across restarts.
+- **Replies you can actually read.** Assistant messages render as markdown (code blocks, lists, tables); every tool call is an expandable card showing what it did (e.g. "Wrote 163 bytes to plan.md"); errors read as errors, not as a fake answer.
+
+---
+
+**[2026-07-08] General coding agent: interactive CLI, web Agent Chat & native tools**
+
+- **Talk to DeepCode in your terminal.** `python -m cli.tui` (or just `deepcode`) opens a free-form, multi-turn coding conversation — describe any task in natural language and watch the agent stream its reply, edit files, and run commands with live progress cards. Steer with `/new`, `/resume`, `/model`, `/clear`, `/help`, and attach files with `@path`. (Replaces the previous menu-driven CLI.)
+- **Chat with the agent in your browser.** The new "Agent Chat" page keeps continuous conversations: a sidebar of past chats, one-click New chat, streamed replies with tool progress, and mid-run interrupt. Every chat persists, reopens any time, and works in its own workspace under `deepcode_lab/chats/`.
+- **Edits that land on the first try.** First-class `read` / `write` / `edit` / `apply_patch` / `bash` / `grep` / `glob` tools: whitespace-tolerant fuzzy edits, multi-file atomic patches, and automatic post-edit diagnostics the agent fixes on the spot.
+- **Script any task.** `python -m cli.exec_cli "task" --json` runs one task end-to-end and emits a machine-readable event stream — drop it straight into CI or your own pipelines.
+- **Long conversations stay fast and stable.** Context windows resolve per model with automatic history compaction, and sessions are SQLite-indexed so listing and resume are instant.
+
+---
+
+**[2026-07-04] V2 foundation: unified agent kernel, security sandbox & event protocol**
+
+- **Every coding phase behaves the same.** All phases now run on one shared agent runtime, with tool definitions sourced straight from the MCP servers as the single source of truth — Paper2Code results unchanged.
+- **Your credentials stay yours.** Every tool call passes a three-valued permission engine (allow / ask / deny) with a non-overridable credential denylist (`.ssh`, `.aws/credentials`, `.env`, `*.pem`, ...), and shell/Python execution runs inside a platform sandbox (macOS seatbelt / Linux bubblewrap) fenced to the workspace. Tune it via `DEEPCODE_SANDBOX` / `DEEPCODE_PERMISSION_MODE` or the `security` block in `deepcode_config.json`.
+- **Build any frontend on one contract.** Declarative per-model provider settings, a normalized model-event stream, a structured message model, and an `AgentSession` event protocol back the CLI, the web UI, and headless runs alike.
+- **Web chat planning just runs.** It now proceeds autonomously by default (requirements -> plan -> implementation) instead of stalling on a clarifying-questions step.
+
+---
+
+<details>
+<summary><strong>Earlier news</strong></summary>
+
+🧭 **[2026-05-01] OpenRouter model selector, session cleanup & workflow UX hardening**
+
+- 🧠 **OpenRouter model catalog in Settings.** The new UI can now fetch OpenRouter model metadata from `https://openrouter.ai/api/v1/models`, cache it locally, and expose searchable model selectors for the Default, Planning, and Implementation phases. Use exact OpenRouter model ids such as `z-ai/glm-5.1` without editing JSON by hand.
+- 🔄 **Runtime model switching.** Saving model choices from Settings updates `deepcode_config.json` and reloads the in-process LLM runtime so newly started workflows pick up the selected provider/model combination immediately.
+- 🗑️ **Session deletion now performs safe cascade cleanup.** Deleting a session from the UI removes its persistent session store and associated `deepcode_lab/tasks/<task_id>/` workspaces, while preserving shared `uploads/` source files. Sessions with `pending`, `running`, or `waiting_for_input` tasks are blocked with a clear `409 Conflict`.
+- 📊 **More accurate Paper2Code progress.** The frontend now shows backend stage messages and avoids marking intermediate phases as fully "Done" while long LLM work is still running.
+- 🛡️ **Workflow robustness fixes.** Uploads now reject Git LFS pointer files, cancelled tasks stop backend work promptly, stale browser session ids recover cleanly, planner retries fall back to a minimal valid plan when a model defers/tool-calls incorrectly, and document segmentation skips an extra validation LLM call that could stall progress.
+
+---
+
+🗂️ **[2026-04-28] Persistent sessions & dual-layer logging**
+
+- 🆕 **Sessions are now persistent.** Every CLI / UI run is automatically attached to a session under `~/.deepcode/sessions/<id>/` (override with `DEEPCODE_SESSIONS_DIR`). Sessions are JSONL — `tail -f session.jsonl` works out of the box. List / inspect / branch them with `python cli/main_cli.py session list|show <id>|new|resume <id>|delete <id>`, or via `GET /api/v1/sessions` from the backend.
+- 🔄 **Resume a previous run** by passing `--session <id>` to the CLI or `session_id` to `POST /api/v1/workflows/paper-to-code` (or `chat-planning`). Backend restarts no longer drop task history; running tasks left over from a crash are surfaced as `interrupted`.
+- 💻 **CLI session UX.** The interactive CLI now supports Cursor-style slash commands: `/resume` opens a numbered session picker, `/new [title]` creates and switches sessions, `/session` shows the active session, and `/help` lists commands. You can also paste inline inputs directly at the menu prompt with `@/path/to/paper.pdf`, `@"C:\path with spaces\paper.pdf"`, or `@https://...`.
+- 📜 **Two-layer structured logging.** A global rotating JSONL lives at `logs/server-YYYYMMDD.jsonl`; per-task logs at `deepcode_lab/tasks/<task_id>/logs/{system,llm,mcp}.jsonl`. Every `loguru.logger` call automatically picks up the active `task_id` via a contextvar — business code did not have to change. Configure via the new `logger.{globalFile,taskFile,llm}` block in `deepcode_config.json`.
+- 📡 **WebSocket log streaming.** Tail one task with `/ws/tasks/{task_id}/logs?channel=llm`, or merge every task in a session via `/ws/sessions/{session_id}/logs`. The legacy `/ws/logs/{session_id}` endpoint that silently ignored its parameter has been removed.
+- 🧹 **Dead code removed.** `utils/simple_llm_logger.py`, `utils/dialogue_logger.py`, and the in-memory `services/session_service.py` implementation are gone (the latter is now a thin re-export of `core.sessions.SessionStore`).
+
+---
+
+🛠️ **[2026-04-17] Stability, Windows compatibility & secrets hygiene update**
+
+- 🐛 **Code Implementation no longer crashes** with `name 'LoopDetector' is not defined` — added the missing `LoopDetector`/`ProgressTracker` imports in both `workflows/code_implementation_workflow.py` and `workflows/code_implementation_workflow_index.py`.
+- 🪟 **Windows: `mkdir -p` / `touch` / `rm -rf` / `cp -r` / `mv` now work natively.** `tools/command_executor.py` translates these common Unix file-tree commands via `pathlib`/`shutil` on every platform, eliminating the bug where `cmd.exe` would create a literal `-p` directory and stall the workflow.
+- 🚀 **Removed Brave Search end-to-end.** All Python code, MCP server config, and docs are scrubbed of `brave`/`BRAVE_API_KEY`/`WebSearchTool`. Web fetching now relies entirely on the built-in `fetch` MCP server.
+- 🔌 **OpenAI-compatible providers documented.** New `Quick Start → Configuration` snippet shows how to point the `openai`/`openrouter` blocks at Poe (`https://api.poe.com/v1`), OpenRouter, or Alibaba DashScope, plus how to set `agents.defaults.model` / `agents.planning.model` / `agents.implementation.model` (e.g. `openai/gpt-5.4`).
+- 🔐 **Secrets hygiene.** All YAML config has been collapsed into a single `deepcode_config.json`, and `.gitignore` now ignores it alongside `secrets.json`, `*credentials*.json`, `.env`, `.env.*` (with `*.env.example` whitelisted).
+- 📝 **Launch table fixed.** The README now documents `deepcode --local` for the web UI path and adds explicit Troubleshooting rows for Windows GBK encoding and the issues fixed above.
+- 🧹 **Misc:** auto-create `logs/` directory so JSONL logging never fails on a fresh checkout, replace bare `except:` with `except Exception:` in `agent_orchestration_engine.py` (Ruff E722), `command_executor` MCP tool descriptions now embed the host OS so the LLM picks compatible commands.
+
+---
+
+🎉 **[2026-02] New Web UI Experience Upgrade!**
 
 - 🔄 **User-in-Loop Interaction**: Support real-time user interaction during workflows - AI asks clarifying questions directly in the chat
 - 💬 **Inline Interaction Design**: Interaction prompts appear naturally within the chat flow for a seamless experience
@@ -226,7 +321,7 @@ Dynamic: summary
 
 ---
 
-🎉 **[2025-10] 🎉 [2025-10-28] DeepCode Achieves SOTA on PaperBench!**
+🎉 **[2025-10-28] DeepCode Achieves SOTA on PaperBench!**
 
 DeepCode sets new benchmarks on OpenAI's PaperBench Code-Dev across all categories:
 
@@ -235,6 +330,8 @@ DeepCode sets new benchmarks on OpenAI's PaperBench Code-Dev across all categori
 - 🔬 **Advances Scientific Coding**: **73.5%** (DeepCode) vs PaperCoder 51.1% (+22.4%).
 - 🚀 **Beats LLM Agents**: **73.5%** (DeepCode) vs best LLM frameworks 43.3% (+30.2%).
 
+</details>
+
 ---
 
 ## 🚀 Key Features
@@ -455,8 +552,6 @@ DeepCode leverages the **Model Context Protocol (MCP)** standard to seamlessly i
 
 | 🛠️ **MCP Server** | 🔧 **Primary Function** | 💡 **Purpose & Capabilities** |
 |-------------------|-------------------------|-------------------------------|
-| **🔍 brave** | Web Search Engine | Real-time information retrieval via Brave Search API |
-| **🌐 bocha-mcp** | Alternative Search | Secondary search option with independent API access |
 | **📂 filesystem** | File System Operations | Local file and directory management, read/write operations |
 | **🌐 fetch** | Web Content Retrieval | Fetch and extract content from URLs and web resources |
 | **📥 github-downloader** | Repository Management | Clone and download GitHub repositories for analysis |
@@ -637,9 +732,8 @@ Choose one of the following installation methods:
 # 🚀 Install DeepCode package directly
 pip install deepcode-hku
 
-# 🔑 Download configuration files
-curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/mcp_agent.config.yaml
-curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/mcp_agent.secrets.yaml
+# 🔑 One-time setup: create ~/.deepcode/deepcode_config.json (then add a key)
+deepcode init
 ```
 
 #### 🔧 **Development Installation (From Source)**
@@ -674,257 +768,243 @@ pip install -r requirements.txt
 npm install --prefix new_ui/frontend
 ```
 
+##### 🧪 **Editable install (lets `deepcode` always run THIS checkout)**
+
+If you want the global `deepcode` command to launch the source tree you are
+hacking on, install the project in editable mode after the steps above:
+
+```bash
+pip install -e .
+```
+
+This registers a `deepcode-hku` package (current version 1.2.0) and exposes
+the `deepcode` CLI entry point. Any local code change is picked up
+immediately on next launch — no reinstall needed.
+
+> If you maintain multiple DeepCode checkouts, only one of them can own the
+> `deepcode` command at a time (the most recent `pip install -e .` wins).
+> Reinstall in the checkout you currently want to be active.
+
 </details>
 
 ### 🔧 **Step 2: Configuration**
 
-> The following configuration applies to **all installation methods** (pip, UV, source, and Docker).
+> The following configuration applies to **all installation methods** (pip, UV, source). Everything lives in a single `deepcode_config.json` file.
 
-#### 🔑 API Keys *(required)*
+#### 🌍 Run `deepcode` from any directory
 
-Edit `mcp_agent.secrets.yaml` with your API keys:
+DeepCode resolves its config in two layers, the same way Codex and Claude Code do:
 
-```yaml
-# At least ONE provider API key is required
-openai:
-  api_key: "your_openai_api_key"
-  base_url: "https://openrouter.ai/api/v1"  # Optional: for OpenRouter or custom endpoints
+| Layer | Location | Role |
+|-------|----------|------|
+| **User base** | `~/.deepcode/deepcode_config.json` (or `$DEEPCODE_HOME`) | Read from **any** working directory. Keep your provider keys here. |
+| **Project override** | `deepcode_config.json` in the current directory (or any parent) | Optional. Deep-merged on top of the base, overriding it key by key. |
 
-anthropic:
-  api_key: "your_anthropic_api_key"  # For Claude models
+Run the one-time setup and you can launch `deepcode` anywhere:
 
-google:
-  api_key: "your_google_api_key"     # For Gemini models
+```bash
+deepcode init      # creates ~/.deepcode/deepcode_config.json
 ```
 
-#### 🤖 LLM Provider *(optional)*
+`deepcode init` is a single cross-platform command (Windows, macOS, Linux). Run
+from a checkout that already has a `deepcode_config.json`, it lifts that config —
+keys and all — into the user base; run elsewhere, it drops the template there for
+you to fill in. It never overwrites an existing base (use `--force` to reseed,
+which keeps a `.bak`), and on Unix it locks the file to `600`. To relocate the
+base, set `DEEPCODE_HOME` (`export DEEPCODE_HOME=...` on macOS/Linux,
+`setx DEEPCODE_HOME ...` on Windows).
+
+> If you prefer to keep the config only next to a specific project, skip
+> `deepcode init` and just create `deepcode_config.json` in that directory — it
+> is picked up whenever you launch from there.
+
+#### 🔑 API Keys *(required)*
+
+Edit `deepcode_config.json` and fill in at least one provider key. Inline strings work, and `${ENV_VAR}` references are resolved at load time.
 
-Edit `mcp_agent.config.yaml` to choose your preferred LLM provider (line ~106):
+```json
+{
+  "providers": {
+    "openai":    { "apiKey": "your_openai_api_key" },
+    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
+    "gemini":    { "apiKey": "" }
+  }
+}
+```
 
-```yaml
-# Options: "google", "anthropic", "openai"
-# If not set or unavailable, will automatically fallback to first available provider
-llm_provider: "google"
+<details>
+<summary><strong>🔌 Using OpenAI-compatible providers (OpenRouter / Poe / DashScope / etc.)</strong></summary>
+
+Any OpenAI-compatible endpoint is supported by overriding `apiBase` on the matching provider entry. Then set the model name on the `agents` block (using `provider/model` slugs):
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "provider": "openrouter",
+      "model": "z-ai/glm-5.1"
+    },
+    "planning":       { "provider": "openrouter", "model": "z-ai/glm-5.1" },
+    "implementation": { "provider": "openrouter", "model": "z-ai/glm-5.1" }
+  },
+  "providers": {
+    "openai":     { "apiKey": "your_openai_api_key" },
+    "openrouter": { "apiKey": "your_openrouter_key", "apiBase": "https://openrouter.ai/api/v1" }
+  }
+}
 ```
 
-#### 🔍 Search API Keys *(optional)*
+OpenRouter model ids must use the exact `id` returned by OpenRouter, for example
+`z-ai/glm-5.1`, `anthropic/claude-sonnet-4.5`, or
+`google/gemini-2.5-pro`. In the new UI, open **Settings → OpenRouter Models**
+to search the live OpenRouter catalog and update the Default, Planning, and
+Implementation models without editing this file manually. Saving from the UI
+reloads the runtime for newly started workflows.
+
+> **🔐 Never commit `deepcode_config.json`.** It is already in `.gitignore`.
+
+</details>
 
-Configure web search in `mcp_agent.config.yaml`:
+#### 🤖 LLM Provider *(optional)*
 
-```yaml
-# For Brave Search (default) — set in brave.env section (line ~28)
-brave:
-  env:
-    BRAVE_API_KEY: "your_brave_api_key_here"
+The provider is inferred from the `model` slug (`openai/...`, `anthropic/...`, `gemini/...`, etc.). To force a specific backend, set `agents.defaults.provider`:
 
-# For Bocha-MCP (alternative) — set in bocha-mcp.env section (line ~74)
-bocha-mcp:
-  env:
-    BOCHA_API_KEY: "your_bocha_api_key_here"
+```json
+{
+  "agents": {
+    "defaults": { "provider": "openai" }
+  }
+}
 ```
 
 #### 📄 Document Segmentation *(optional)*
 
-Control document processing in `mcp_agent.config.yaml`:
-
-```yaml
-document_segmentation:
-  enabled: true          # true/false — whether to use intelligent document segmentation
-  size_threshold_chars: 50000  # Document size threshold to trigger segmentation
+```json
+{
+  "documentSegmentation": {
+    "enabled": true,
+    "sizeThresholdChars": 50000
+  }
+}
 ```
 
 <details>
 <summary><strong>🪟 Windows Users: Additional MCP Server Configuration</strong></summary>
 
-If you're using Windows, you may need to configure MCP servers manually in `mcp_agent.config.yaml`:
+On Windows you may need to configure MCP servers manually in `deepcode_config.json` (`tools.mcpServers`):
 
 ```bash
 # 1. Install MCP servers globally
-npm i -g @modelcontextprotocol/server-brave-search
 npm i -g @modelcontextprotocol/server-filesystem
 
 # 2. Find your global node_modules path
 npm -g root
 ```
 
-Then update your `mcp_agent.config.yaml` to use absolute paths:
-
-```yaml
-mcp:
-  servers:
-    brave:
-      command: "node"
-      args: ["C:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"]
-    filesystem:
-      command: "node"
-      args: ["C:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
+```json
+{
+  "tools": {
+    "mcpServers": {
+      "filesystem": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["C:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
+      }
+    }
+  }
+}
 ```
 
-> **Note**: Replace the path with your actual global node_modules path from step 2.
+> Replace the path with the actual global `node_modules` path from step 2.
 
 </details>
 
 <details>
-<summary><strong>🔍 Search Server Configuration (Optional)</strong></summary>
+<summary><strong>🔍 Web Search Configuration</strong></summary>
 
-DeepCode supports multiple search servers for web search functionality. You can configure your preferred option in `mcp_agent.config.yaml`:
-
-```yaml
-# Default search server configuration
-# Options: "brave" or "bocha-mcp"
-default_search_server: "brave"
-```
+DeepCode performs web content retrieval through the built-in `fetch` MCP server (no API key required) and reads local files via `filesystem`. The auxiliary search server defaults to `filesystem`:
 
-**Available Options:**
-- **🔍 Brave Search** (`"brave"`): Default option with high-quality search results. Requires `BRAVE_API_KEY`. Recommended for most users.
-- **🌐 Bocha-MCP** (`"bocha-mcp"`): Alternative search server. Requires `BOCHA_API_KEY`. Uses local Python server implementation.
-
-**Full MCP server configuration in mcp_agent.config.yaml:**
-```yaml
-# For Brave Search (default) - around line 28
-brave:
-  command: "npx"
-  args: ["-y", "@modelcontextprotocol/server-brave-search"]
-  env:
-    BRAVE_API_KEY: "your_brave_api_key_here"
-
-# For Bocha-MCP (alternative) - around line 74
-bocha-mcp:
-  command: "python"
-  args: ["tools/bocha_search_server.py"]
-  env:
-    PYTHONPATH: "."
-    BOCHA_API_KEY: "your_bocha_api_key_here"
+```json
+{
+  "tools": { "defaultSearchServer": "filesystem" }
+}
 ```
 
-> **💡 Tip**: Both search servers require API key configuration. Choose the one that best fits your API access and requirements.
+> **💡 Tip**: To plug in another search backend, add it under `tools.mcpServers` in `deepcode_config.json` and set `tools.defaultSearchServer` to its name.
 
 </details>
 
 ### ⚡ **Step 3: Launch Application**
 
-#### 🐳 **Docker** (Recommended — Easiest Setup)
-
-No need to install Python, Node.js, or any dependencies — everything runs inside the container.
+DeepCode runs three ways, all on the same agent core:
 
-**Prerequisites:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop) (includes Docker Engine + Docker Compose).
+**🖥️ Interactive agent (default).** A multi-turn coding conversation in your terminal:
 
 ```bash
-# 1. Clone the repository (if not already done)
-git clone https://github.com/HKUDS/DeepCode.git
-cd DeepCode/
-
-# 2. Configure your API keys (see Step 2: Configuration above)
-cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml
-# Edit mcp_agent.secrets.yaml with your API keys
-
-# 3. Start with one command
-./deepcode_docker/run_docker.sh        # Build & start (auto-builds on first run)
-
-# Access at http://localhost:8000
+deepcode                 # equivalent to: python -m cli.tui
 ```
 
-**Management Commands:**
-```bash
-./deepcode_docker/run_docker.sh stop         # Stop the service
-./deepcode_docker/run_docker.sh restart      # Restart (after config changes, no rebuild needed)
-./deepcode_docker/run_docker.sh --build      # Rebuild (after code changes)
-./deepcode_docker/run_docker.sh logs         # View real-time logs
-./deepcode_docker/run_docker.sh status       # Check service status
-./deepcode_docker/run_docker.sh clean        # Remove containers and images
-```
+**🌐 Local web UI.** React frontend + FastAPI backend on your host:
 
-Or use Docker Compose directly:
 ```bash
-docker compose -f deepcode_docker/docker-compose.yml up --build   # Build and start
-docker compose -f deepcode_docker/docker-compose.yml up -d        # Start in background
-docker compose -f deepcode_docker/docker-compose.yml down         # Stop
-docker compose -f deepcode_docker/docker-compose.yml logs -f      # View logs
+deepcode --local
+# Frontend → http://localhost:5173    Backend → http://localhost:8000
 ```
 
-> **💡 Config changes don't need rebuild**: `mcp_agent.config.yaml` and `mcp_agent.secrets.yaml` are mounted as volumes — just edit them and run `./deepcode_docker/run_docker.sh restart`.
->
-> **💡 Windows users**: Run `docker compose -f deepcode_docker/docker-compose.yml up --build` directly if the shell script is not available.
-
-#### 🚀 **Using `deepcode` Command** (Local Installation)
+**🤖 Headless (scripting / CI).** One task, machine-readable output:
 
 ```bash
-# 🌐 Launch the new React-based web interface
-deepcode
-
-# Frontend: http://localhost:5173
-# Backend API: http://localhost:8000
-# Press Ctrl+C to stop all services
+python -m cli.exec_cli "fix the failing test in mathlib.py" --json
 ```
-<div align="center">
-  <img src="https://img.shields.io/badge/Frontend-localhost:5173-00d4ff?style=flat-square&logo=react&logoColor=white" alt="Frontend" />
-  <img src="https://img.shields.io/badge/Backend-localhost:8000-4ecdc4?style=flat-square&logo=fastapi&logoColor=white" alt="Backend" />
-</div>
-
-> **📦 Auto Install**: On first run, dependencies are automatically installed (`pip install` for backend, `npm install` for frontend)
 
-> **✨ Features**: User-in-Loop interaction, real-time progress tracking, inline chat interaction
+#### 💻 **Interactive CLI (multi-turn coding agent)**
 
-#### 🛠️ **Alternative Launch Methods**
-
-<table>
-<tr>
-<td><strong>🍎 macOS / 🐧 Linux</strong></td>
-<td><strong>🪟 Windows</strong></td>
-</tr>
-<tr>
-<td>
+`python -m cli.tui` opens a Claude Code-style conversation in your terminal:
+describe any coding task in natural language, watch the agent stream its
+reply and tool progress live, and keep the conversation going across turns.
 
 ```bash
-# Using run.sh
-./run.sh
-
-# Or using Python directly
-python deepcode.py
+python -m cli.tui                          # converse in the current directory
+python -m cli.tui -w ./my-project          # explicit workspace
+python -m cli.tui -m gpt-5.4               # explicit model
+python -m cli.tui --resume <session_id>    # pick up a stored conversation
 ```
 
-</td>
-<td>
-
-```cmd
-# Using run.bat
-run.bat
+Inside the conversation:
 
-# Or using Python directly
-python deepcode.py
+```text
+/help                   # list all commands
+/new [title]            # start a fresh conversation
+/resume                 # list THIS directory's sessions; /resume <id> restores one
+/resume all             # list sessions from every directory (origins shown)
+/model [id]             # show or switch the model (history preserved)
+/clear                  # clear the conversation context
+@src/main.py            # attach a file's content to your message
 ```
 
-</td>
-</tr>
-</table>
+Conversations persist under `~/.deepcode/sessions/<id>/` (JSONL, with a SQLite
+index for instant listing) and are titled automatically from your first
+message.
 
-```bash
-# Classic Streamlit UI (all platforms)
-deepcode --classic
-```
-<div align="center">
-  <img src="https://img.shields.io/badge/Classic_UI-localhost:8501-00d4ff?style=flat-square&logo=streamlit&logoColor=white" alt="Classic UI" />
-</div>
+For scripting and CI there is a headless one-shot entry:
 
-##### 🖥️ **CLI Interface** (Advanced Users)
 ```bash
-# CLI via Docker (no local Python needed)
-./deepcode_docker/run_docker.sh cli
+python -m cli.exec_cli "fix the failing test in mathlib.py" --json
+```
 
-# Or: deepcode --cli
+which streams machine-readable events (NDJSON) and exits 0 on completion.
 
-# CLI locally (requires Python environment)
-python cli/main_cli.py
-```
-<div align="center">
-  <img src="https://img.shields.io/badge/Mode-Interactive_Terminal-9b59b6?style=flat-square&logo=terminal&logoColor=white" alt="CLI Mode" />
-</div>
+In the web UI, use the **Sessions** menu in the header to resume or delete a
+session. Deleting a session removes its JSONL session record and associated task
+workspace under `deepcode_lab/tasks/`, but keeps original files in `uploads/`.
+If the session still has `pending`, `running`, or `waiting_for_input` tasks, the
+backend rejects the deletion until the task is cancelled or completed.
 
 ### 🎯 **Step 4: Generate Code**
 
-1. **📄 Input**: Upload your research paper, provide requirements, or paste a URL
-2. **🤖 Processing**: Watch the multi-agent system analyze and plan
-3. **⚡ Output**: Receive production-ready code with tests and documentation
+1. **📄 Input** — Upload a research paper, type requirements, or paste a URL
+2. **🤖 Processing** — The multi-agent system analyzes, plans, and generates
+3. **⚡ Output** — Receive production-ready code with tests and documentation
 
 ---
 
@@ -933,60 +1013,15 @@ python cli/main_cli.py
 <details>
 <summary><strong>❓ Common Issues & Solutions</strong></summary>
 
-#### 🐳 Docker build fails with `tsc: not found`
-
-```
-node_modules/.bin/tsc: line 1: ../typescript/bin/tsc: not found
-```
-
-**Cause**: Corrupted Docker build cache.
-
-**Fix**: Clear the cache and rebuild:
-```bash
-docker builder prune -f
-docker compose -f deepcode_docker/docker-compose.yml build --no-cache
-docker compose -f deepcode_docker/docker-compose.yml up -d
-```
-
-#### 🐳 Docker command returns `error during connect` / `cannot find the file specified`
-
-**Cause**: Docker Desktop is not running.
-
-**Fix**: Start **Docker Desktop** from the Start menu (Windows) or Applications (macOS), wait until it's fully ready, then retry.
-
-#### 🌐 Frontend displays abnormally or shows a blank page
-
-**Cause**: Corrupted `node_modules` — frontend dependencies are incomplete.
-
-**Fix**: Reinstall frontend dependencies:
-```bash
-cd new_ui/frontend
-rm -rf node_modules
-npm install
-```
-
-Then rebuild (for Docker) or restart (for local mode).
-
-#### 🌐 Browser shows `ERR_CONNECTION_REFUSED` or JSON response instead of UI
-
-**Cause**: Accessing the wrong port or backend not running.
-
-**Fix**:
-- **Docker mode** (`deepcode`): Access **http://localhost:8000**. Make sure the container is running: `docker ps`
-- **Local mode** (`deepcode --local`): Access **http://localhost:5173** (not 8000). Port 5173 is the frontend dev server.
-
-#### 📦 `npm install` fails with `Could not read package.json`
-
-**Cause**: Running `npm install` in the project root instead of the frontend directory.
-
-**Fix**: Run it in the correct directory:
-```bash
-npm install --prefix new_ui/frontend
-```
-
-#### 🪟 Windows: MCP servers not working
-
-See the [Windows MCP Server Configuration](#-step-2-configuration) section above for setting up absolute paths.
+| Problem | Cause | Fix |
+|---|---|---|
+| Frontend blank page | Corrupted `node_modules` | `cd new_ui/frontend && rm -rf node_modules && npm install` |
+| `ERR_CONNECTION_REFUSED` | Wrong port / backend not running | With `--local`: frontend `http://localhost:5173`, backend `http://localhost:8000` |
+| `npm install` → `Could not read package.json` | Wrong directory | Use `npm install --prefix new_ui/frontend` |
+| Windows: MCP servers not working | Need absolute paths | See [Windows MCP Configuration](#-step-2-configuration) above |
+| Windows: `UnicodeEncodeError: 'gbk' codec can't encode...` on launch | Default GBK console can't render emoji in startup banner | Set UTF-8 first: `set PYTHONIOENCODING=utf-8 && set PYTHONUTF8=1` (cmd) or `$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"` (PowerShell) |
+| Windows: code-implementation stage hangs / produces a `-p` directory | LLM emitted `mkdir -p ...` and `cmd.exe` treated `-p` as a folder name | Already fixed in `tools/command_executor.py` — common Unix commands (`mkdir -p`, `touch`, `rm -rf`, `cp -r`, `mv`) are now executed natively via `pathlib`/`shutil`, no shell needed |
+| `name 'LoopDetector' is not defined` during code implementation | Missing import in workflow modules | Already fixed — `LoopDetector` and `ProgressTracker` are now imported from `utils.loop_detector` in both `workflows/code_implementation_workflow.py` and `workflows/code_implementation_workflow_index.py` |
 
 </details>