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

{deepcode_hku-1.2.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.2.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>
@@ -200,7 +206,6 @@ Dynamic: summary
 - [🏗️ Architecture](#️-architecture)
 - [📊 Experimental Results](#-experimental-results)
 - [🚀 Quick Start](#-quick-start)
-- [🤖 nanobot Integration (Feishu Chatbot)](#-nanobot-integration-feishu-chatbot)
 - [💡 Examples](#-examples)
   - [🎬 Live Demonstrations](#-live-demonstrations)
 - [⭐ Star History](#-star-history)
@@ -211,35 +216,96 @@ Dynamic: summary
 
 ## 📰 News
 
-🎉 **[2025-02] DeepCode + nanobot Integration — Chat with DeepCode via Feishu Bot!**
+**[2026-07-17] Extensible agents: reusable Skills, lifecycle Hooks & model-driven delegation**
 
-<div align="center">
-<table><tr>
-<td align="center"><a href="https://github.com/HKUDS/DeepCode"><img src="./assets/logo.png" alt="DeepCode" height="60"/></a></td>
-<td align="center"><h2>✦</h2></td>
-<td align="center"><a href="https://github.com/HKUDS/nanobot"><img src="./assets/nanobot.png" alt="nanobot" height="60"/></a></td>
-</tr></table>
-</div>
+- **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.
 
-- [nanobot](https://github.com/HKUDS/nanobot) now connects to DeepCode — send messages in **Feishu** and get auto-generated code back
-- Supports **Paper-to-Code** and **Chat-to-Code**, plus real-time task tracking, all from your chat app
-- One-command deploy: `./nanobot/run_nanobot.sh` → **[Setup Guide →](#-nanobot-integration-feishu-chatbot)**
+---
 
-<div align="center">
-<table width="100%"><tr>
-<td width="50%" align="center">
-  <img src="./assets/IMG_8098.jpeg" alt="Feishu Chat Example 1" width="95%" style="border-radius: 10px; box-shadow: 0 4px 15px rgba(0,0,0,0.2);"/>
-</td>
-<td width="50%" align="center">
-  <img src="./assets/IMG_8099.jpeg" alt="Feishu Chat Example 2" width="95%" style="border-radius: 10px; box-shadow: 0 4px 15px rgba(0,0,0,0.2);"/>
-</td>
-</tr></table>
-<sub><em>Feishu Bot in Action — Natural language → Full code generation with setup instructions</em></sub>
-</div>
+**[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.
 
 ---
 
-🎉 **[2025-02] New Web UI Experience Upgrade!**
+🎉 **[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
@@ -264,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
@@ -484,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 |
@@ -666,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)**
@@ -703,216 +768,237 @@ 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).
 
-Edit `mcp_agent.config.yaml` to choose your preferred LLM provider (line ~106):
+> 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.
 
-```yaml
-# Options: "google", "anthropic", "openai"
-# If not set or unavailable, will automatically fallback to first available provider
-llm_provider: "google"
+#### 🔑 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.
+
+```json
+{
+  "providers": {
+    "openai":    { "apiKey": "your_openai_api_key" },
+    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
+    "gemini":    { "apiKey": "" }
+  }
+}
 ```
 
-#### 🔍 Search API Keys *(optional)*
+<details>
+<summary><strong>🔌 Using OpenAI-compatible providers (OpenRouter / Poe / DashScope / etc.)</strong></summary>
 
-Configure web search in `mcp_agent.config.yaml`:
+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):
 
-```yaml
-# For Brave Search (default) — set in brave.env section (line ~28)
-brave:
-  env:
-    BRAVE_API_KEY: "your_brave_api_key_here"
+```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" }
+  }
+}
+```
 
-# For Bocha-MCP (alternative) — set in bocha-mcp.env section (line ~74)
-bocha-mcp:
-  env:
-    BOCHA_API_KEY: "your_bocha_api_key_here"
+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>
+
+#### 🤖 LLM Provider *(optional)*
+
+The provider is inferred from the `model` slug (`openai/...`, `anthropic/...`, `gemini/...`, etc.). To force a specific backend, set `agents.defaults.provider`:
+
+```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**
 
-Choose your preferred launch method:
-
-<table width="100%">
-<tr>
-<th width="33%">🐳 Docker (Recommended)</th>
-<th width="33%">🚀 Local (<code>deepcode</code> command)</th>
-<th width="33%">🛠️ Other Methods</th>
-</tr>
-<tr><td>
+DeepCode runs three ways, all on the same agent core:
 
-No Python/Node needed — everything in container.
+**🖥️ Interactive agent (default).** A multi-turn coding conversation in your terminal:
 
 ```bash
-git clone https://github.com/HKUDS/DeepCode.git
-cd DeepCode/
-cp mcp_agent.secrets.yaml.example \
-   mcp_agent.secrets.yaml
-# Edit secrets with your API keys
-
-./deepcode_docker/run_docker.sh
-# Access → http://localhost:8000
+deepcode                 # equivalent to: python -m cli.tui
 ```
 
-</td><td>
-
-Auto-installs deps on first run.
+**🌐 Local web UI.** React frontend + FastAPI backend on your host:
 
 ```bash
-deepcode
-# Frontend → http://localhost:5173
-# Backend  → http://localhost:8000
-# Ctrl+C to stop
+deepcode --local
+# Frontend → http://localhost:5173    Backend → http://localhost:8000
 ```
 
-Features: User-in-Loop, real-time progress, inline chat.
-
-</td><td>
+**🤖 Headless (scripting / CI).** One task, machine-readable output:
 
 ```bash
-# macOS / Linux
-./run.sh
-# or: python deepcode.py
+python -m cli.exec_cli "fix the failing test in mathlib.py" --json
+```
 
-# Windows
-run.bat
-# or: python deepcode.py
+#### 💻 **Interactive CLI (multi-turn coding agent)**
 
-# Classic Streamlit UI
-deepcode --classic
+`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.
 
-# CLI mode
-deepcode --cli
-# or: python cli/main_cli.py
+```bash
+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></tr>
-</table>
-
-<details>
-<summary><strong>🐳 Docker Management Commands</strong></summary>
+Inside the conversation:
 
-```bash
-./deepcode_docker/run_docker.sh stop      # Stop
-./deepcode_docker/run_docker.sh restart   # Restart (no rebuild needed for config changes)
-./deepcode_docker/run_docker.sh --build   # Force rebuild
-./deepcode_docker/run_docker.sh logs      # Real-time logs
-./deepcode_docker/run_docker.sh status    # Health check
-./deepcode_docker/run_docker.sh clean     # Remove containers & images
+```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
 ```
 
-Or with Docker Compose directly:
+Conversations persist under `~/.deepcode/sessions/<id>/` (JSONL, with a SQLite
+index for instant listing) and are titled automatically from your first
+message.
+
+For scripting and CI there is a headless one-shot entry:
+
 ```bash
-docker compose -f deepcode_docker/docker-compose.yml up --build   # Build & start
-docker compose -f deepcode_docker/docker-compose.yml down         # Stop
-docker compose -f deepcode_docker/docker-compose.yml logs -f      # Logs
+python -m cli.exec_cli "fix the failing test in mathlib.py" --json
 ```
 
-> **💡** Config files are mounted as volumes — edit and restart, no rebuild needed.
-> **💡** Windows users: run `docker compose` commands directly if shell scripts aren't available.
+which streams machine-readable events (NDJSON) and exits 0 on completion.
 
-</details>
+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**
 
@@ -929,166 +1015,18 @@ docker compose -f deepcode_docker/docker-compose.yml logs -f      # Logs
 
 | Problem | Cause | Fix |
 |---|---|---|
-| Docker build fails with `tsc: not found` | Corrupted build cache | `docker builder prune -f` then rebuild with `--no-cache` |
-| `error during connect` / `cannot find the file` | Docker Desktop not running | Start Docker Desktop, wait until ready, retry |
 | Frontend blank page | Corrupted `node_modules` | `cd new_ui/frontend && rm -rf node_modules && npm install` |
-| `ERR_CONNECTION_REFUSED` | Wrong port / backend not running | Docker: `http://localhost:8000`. Local: `http://localhost:5173` |
+| `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>
 
   ---
 
-## 🤖 nanobot Integration (Feishu Chatbot)
-
-> Chat with DeepCode from **Feishu** — powered by [nanobot](https://github.com/HKUDS/nanobot).
-
-<div align="center">
-
-```mermaid
-flowchart LR
-    subgraph Clients["💬 Chat Platforms"]
-        direction TB
-        F["<b>Feishu</b><br/>WebSocket"]
-        T["<b>Telegram</b><br/>Polling"]
-        D["<b>Discord</b><br/>Gateway"]
-    end
-
-    subgraph Gateway["🐈 nanobot Gateway"]
-        direction TB
-        A["Agent Loop<br/><i>LLM + Tool Calls</i>"]
-    end
-
-    subgraph Engine["🧠 DeepCode Engine"]
-        direction TB
-        P2C["Paper → Code"]
-        C2C["Chat → Code"]
-        TRK["Task Tracking"]
-    end
-
-    F & T & D <-->|"messages"| A
-    A -->|"HTTP API"| P2C & C2C & TRK
-    A -.->|"LLM API"| LLM["☁️ OpenRouter"]
-
-    style Clients fill:#1a1a2e,stroke:#00d9ff,color:#fff
-    style Gateway fill:#1a1a2e,stroke:#4ecdc4,color:#fff
-    style Engine fill:#1a1a2e,stroke:#ff6b6b,color:#fff
-    style LLM fill:#1a1a2e,stroke:#9b59b6,color:#fff
-```
-
-</div>
-
-<div align="center">
-<table><tr>
-<td align="center"><a href="https://github.com/HKUDS/DeepCode"><img src="./assets/logo.png" alt="DeepCode" height="55"/></a></td>
-<td align="center"><h2>✦</h2></td>
-<td align="center"><a href="https://github.com/HKUDS/nanobot"><img src="./assets/nanobot.png" alt="nanobot" height="55"/></a></td>
-</tr></table>
-</div>
-
-Both services run inside the same **Docker Compose** network. Prerequisites: **Docker Desktop** + **OpenRouter API Key** ([get one](https://openrouter.ai/keys)) + **Feishu App**.
-
----
-
-### Step 1 · Create a Feishu Bot
-
-<details open>
-<summary><b>Feishu / Lark</b> (Recommended — WebSocket, no public IP needed)</summary>
-
-1. Go to [Feishu Open Platform](https://open.feishu.cn/app) → **Create Custom App**
-2. Enable **Bot** capability in App Features
-3. Add permissions: `im:message` · `im:message:send_as_bot`
-4. Event Subscription → select **Long Connection** → add `im.message.receive_v1`
-5. Note your **App ID** (`cli_xxx`) and **App Secret** → Publish the app
-
-> **Note**: Feishu requires an active WebSocket connection before you can save "Long Connection" mode. Start nanobot first (Step 3), then come back to configure Event Subscription.
-
-</details>
-
-### Step 2 · Configure
-
-```bash
-cp nanobot_config.json.example nanobot_config.json
-```
-
-Edit `nanobot_config.json` — fill in the 3 required fields:
-
-```jsonc
-{
-  "channels": {
-    "feishu": {
-      "enabled": true,
-      "appId": "cli_xxx",              // ← Feishu App ID
-      "appSecret": "xxx",              // ← Feishu App Secret
-      "allowFrom": []                  // [] = allow all users
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "apiKey": "sk-or-v1-xxx"         // ← OpenRouter API Key
-    }
-  },
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-sonnet-4-20250514"
-    }
-  }
-}
-```
-
-> **Model choice**: Any model on [openrouter.ai/models](https://openrouter.ai/models). Use `anthropic/claude-sonnet-4-20250514` for English, `minimax/minimax-m2.1` for Chinese.
-
----
-
-### Step 3 · Launch
-
-Make sure `mcp_agent.secrets.yaml` has your DeepCode API keys (see [Configuration](#-step-2-configuration)), then:
-
-```bash
-./nanobot/run_nanobot.sh -d          # Start both DeepCode + nanobot in background
-```
-
-The script checks Docker, validates configs, builds images (first run only), and starts both containers.
-
-```
-✓ DeepCode API:  http://localhost:8000
-✓ Nanobot:       http://localhost:18790
-```
-
-Now open Feishu → find your bot → send a message!
-
-<details>
-<summary><b>Management Commands</b></summary>
-
-```bash
-./nanobot/run_nanobot.sh              # Start (foreground)
-./nanobot/run_nanobot.sh -d           # Start (background)
-./nanobot/run_nanobot.sh stop         # Stop all services
-./nanobot/run_nanobot.sh restart      # Restart (config changes take effect immediately)
-./nanobot/run_nanobot.sh --build      # Force rebuild Docker images
-./nanobot/run_nanobot.sh logs         # View real-time logs
-./nanobot/run_nanobot.sh status       # Health check
-./nanobot/run_nanobot.sh clean        # Remove containers & images
-```
-
-</details>
-
-<details>
-<summary><b>Troubleshooting</b></summary>
-
-| Problem | Fix |
-|---|---|
-| Feishu bot doesn't respond | Check logs (`./nanobot/run_nanobot.sh logs`), verify `appId`/`appSecret`, ensure app is published with Long Connection mode |
-| Can't connect to DeepCode | Verify `deepcode` container is healthy: `curl http://localhost:8000/health` |
-| Wrong language output | Switch model — `minimax-m2.1` defaults to Chinese, use Claude/GPT for English |
-| Config not taking effect | Just restart: `./nanobot/run_nanobot.sh restart` (no rebuild needed) |
-| Clear chat history | Send `/clear` in chat, or: `docker exec nanobot sh -c 'rm -rf /root/.nanobot/sessions/*.jsonl'` |
-
-</details>
-
----
-
 ## 💡 Examples