mocode-ai 0.4.4 → 0.4.6

package/README.md

@@ -1,209 +1,219 @@
-<img src="./assets/banner-en.svg?v=2" alt="MoCode">
-
-<p align="right">English | <a href="./README.zh-CN.md">简体中文</a></p>
-
-# MoCode
-
-A terminal coding agent: give it a goal, and it **completes it autonomously** — no step-by-step hand-holding required.
-
-MoCode explores your code, reads/writes/edits files, runs shell commands, and searches the web on its own, driving the task forward through a loop of "think → call a tool → observe the result → think again." It works with any OpenAI-compatible endpoint (GLM, DeepSeek, Qwen, local Ollama / vLLM, etc.), runs as a full-screen TUI with streaming output and visible reasoning.
-
-## Why MoCode
-
-MoCode isn't a chat box with a coat of paint — it's an agent that actually gets things done:
-
-- **Autonomous multi-step execution** — In a single conversation, the agent chains multiple steps on its own: read code, edit code, run tests, fix based on errors, and so on. It decides the next step without you nagging it. When it hits a decision point, it calls `ask_human` to pop up a panel and ask you (blocking until you respond).
-- **Parallel read-only tools** — Consecutive read-only operations in a turn (reading files, grep, glob, codegraph, web search/fetch) run concurrently, so total time is roughly the slowest single call instead of the sum of all of them. Operations with side effects (writing/editing files) stay sequential to preserve snapshot ordering and data safety.
-- **Sub-agents divide and conquer** — Complex tasks can spawn independent sub-agents, each with its own conversation history (isolated from the main thread), an optional restricted toolset, and a step cap. They can explore multiple code areas or directions in parallel and report back only a summary, which the main thread uses to decide what's next.
-- **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode unlocks the full toolset. The agent can switch between the two on its own — scope out an unfamiliar codebase first, then start making changes.
-- **Automatic context compression** — As the context window fills up, a three-tier compression kicks in (trim individual results → compact older tool results in place → summarize older turns), so long sessions never overflow. `/context` shows live token usage; `/compact` triggers manual compression (optionally with a focus hint to preserve what matters).
-- **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
-- **Working notepad (todolist)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent first writes a plan to `.mocode/plans/<id>.md` (file-based, survives context compression), then ticks each step as it goes. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`. `finish` auto-archives completed plans to `plans/archive/`, with explicit `list / delete / unarchive` actions.
-- **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
-- **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
-
-## Features
-
-- **Streaming output + visible reasoning** — Responses render as they're generated; when the model supports reasoning, the thinking process is visible in real time and auto-collapses to save screen space.
-- **Full-screen TUI** — Alt-screen mode with a fixed status bar, scrollback (PgUp/PgDn), typeahead while the agent is running, and auto-prefill for the next turn.
-- **Session persistence** — Every turn is saved automatically; `--resume` / `/resume` picks up a past session.
-- **Skills system** — Scans directories like `~/.mocode/skills/` automatically; each skill's description is injected into the system prompt, and the model calls `use_skill` to load the full instructions only when relevant (progressive disclosure: skim the summary first, load the body only if needed).
-- **Optional desktop pet** — A small floating window (`/pet`) shows a stateful character that mirrors agent activity (idle / thinking / tool running / waiting for human). Works as a separate process over WebSocket; quit it with `/pet quit`. Sits beside the terminal, never blocks it.
-- **Slash commands** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`, with dropdown filtering as you type.
-
-## Installation
-
-Requires Node.js ≥ 18.
-
-```bash
-npm install -g mocode-ai
-```
-
-This gives you the `mocode` command. Prefer not to install globally? Run it directly with `npx mocode-ai`.
-
-> MoCode checks for new versions on startup and self-updates in the background via `npm i -g mocode-ai@latest` — the update takes effect on the next launch, with zero startup delay and silent failure if offline. This is skipped in dev mode (`npm start`, running via tsx).
-
-### Run from source (development / contributing)
-
-```bash
-git clone https://github.com/wanxunyang/mocode.git
-cd mocode
-npm install
-npm start
-```
-
-Source runs directly via tsx, no build step. After changing code, restart `npm start` for changes to take effect (tsx loads modules at startup, no hot reload). Runtime dependencies: `openai`, `dotenv`, `fast-glob`; dev dependencies: `tsx`, `typescript`, `@types/node`.
-
-## Configuration
-
-On first use, run the setup wizard to fill in three fields interactively (API base URL / key / model name), written to `~/.mocode/config` (global, works from any directory or terminal):
-
-```bash
-mocode config
-```
-
-You can also configure it from inside the REPL with the `/model` command (pick a backend preset interactively and fill in each field, applied immediately and persisted). Without configuration, the REPL still opens and prompts you to run `/model`.
-
-You can also hand-edit the config files. MoCode loads them in the following priority order (later entries override earlier ones, only backfilling unset environment variables; anything `export`ed in your shell always takes precedence):
-
-1. `<cwd>/.env` — legacy compatibility, lowest priority (see `.env.example` in the source repo for reference)
-2. `~/.mocode/config` — global (written by `/model` and `mocode config`)
-3. `<cwd>/.mocode/config` — project-level override, highest priority
-
-Three required fields:
-
-```env
-LLM_BASE_URL=https://open.bigmodel.cn/api/v3   # swap in your backend
-LLM_API_KEY=your-key-here
-LLM_MODEL=glm-4.6                              # swap in your model name
-```
-
-Common backend `base_url` values:
-
-| Backend        | base\_url                                           |
-| -------------- | ---------------------------------------------------- |
-| GLM (Zhipu)    | `https://open.bigmodel.cn/api/v3`                   |
-| DeepSeek       | `https://api.deepseek.com`                          |
-| Qwen (Alibaba) | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-| Local Ollama   | `http://localhost:11434/v1`                         |
-| Local vLLM     | `http://localhost:8000/v1`                          |
-
-> The model must support OpenAI-style function calling, otherwise tools won't be triggered.
-
-### Optional configuration
-
-| Environment variable       | Description                                                          | Default                     |
-| --------------------------- | ---------------------------------------------------------------------- | --------------------------- |
-| `MAX_TOKENS`                | Max tokens per response                                               | unlimited                   |
-| `CONTEXT_WINDOW_TOKENS`     | Model context window; must match the real model                      | `128000`                    |
-| `COMPACT_THRESHOLD`         | Auto-compaction trigger threshold (fraction of window)                | `0.85`                      |
-| `LLM_STREAM_USAGE`          | Include `stream_options.include_usage` on streaming requests for real usage | `true`                |
-| `AUTO_COMPACT`               | Auto-compaction master switch                                          | `true`                       |
-| `AUTO_REFLECT`               | Background reflection pass master switch (periodically mines memories from conversations) | `true`   |
-| `REFLECT_EVERY_N`            | Trigger a background reflection every N turns (runs alongside the agent, non-blocking) | `5`      |
-| `ANYSEARCH_API_KEY`         | Web search API key (falls back to anonymous free quota if unset)      | none                         |
-| `ANYSEARCH_BASE_URL`        | Search API endpoint                                                    | `https://api.anysearch.com` |
-| `SKILLS_DIRS`               | Override the default skill scan directories (platform path separator) | three default directories   |
-| `MOCODE_CONTEXT_OPTIMIZE`   | Typed encoding of tool results before they reach the LLM (tree/search/log…); disable for raw passthrough (length trimming only) | `true` |
-| `MAX_STEPS`                 | Max agent loop steps per turn (prevents infinite loops)               | `200`                        |
-| `SUB_AGENT_MAX_STEPS`       | Default step cap for sub-agents (spawned via the `task` tool)         | `50`                         |
-| `SANDBOX_ROOT`               | Sandbox root directory (file operation boundary; falls back to cwd if unset) | none                  |
-| `MOCODE_THEME`               | Color theme (default/dark/light…; shell env takes precedence over file) | `default`                   |
-
-## Usage
-
-```bash
-mocode                          # new session (run inside your target project directory)
-mocode --resume                 # list saved sessions
-mocode --resume <id>            # resume a specific session
-mocode config                   # edit configuration
-```
-
-Running from source uses `npm start` (equivalent to `mocode`, but skips the self-update check).
-
-Once in the REPL, just start chatting. It launches straight into the full-screen TUI, showing a banner (model / backend / working directory / tool list). Responses stream in, with the reasoning section visible in real time before collapsing.
-
-The agent operates in **the working directory it was launched from** — to have it work on a specific project, `cd` into that project before running `mocode`.
-
-## Tools
-
-| Tool             | Purpose                                                                  |
-| ---------------- | ------------------------------------------------------------------------- |
-| `read_file`       | Read a file with line numbers; supports `offset` / `limit`               |
-| `write_file`      | Create/overwrite a file, auto-creating parent directories                |
-| `edit_file`       | Precise string replacement (`old_string` must match uniquely)            |
-| `run_command`     | Run a shell command, merging stdout+stderr, 120s default timeout         |
-| `glob`            | Find files by glob pattern (excludes node\_modules/.git)                 |
-| `grep`            | Regex content search, pure JS implementation, no `rg` dependency         |
-| `codegraph`       | With a `.codegraph/` index built, query symbol source and call chains (more accurate and cheaper than read\_file/grep) |
-| `web_search`      | Web search (AnySearch), returns title/URL/snippet/body                   |
-| `web_fetch`       | Fetch a URL, cleaning HTML into plain text                                |
-| `use_skill`       | Load the full SKILL.md instructions for a given skill                    |
-| `ask_human`        | Pop up a Q&A panel at decision points; user picks a preset or types freely (blocks until answered) |
-| `switch_mode`      | Switch between `plan` (read-only planning) and `auto` (full execution); the agent can call this itself to explore before acting |
-| `drop_context`     | Replace irrelevant old tool results in history with stubs to free up context (preserves tool_call_id pairing, leaves system prompt and current turn untouched, idempotent) |
-| `task`             | Spawn a sub-agent for an independent subtask (isolated history, optional restricted toolset, optional step cap); consecutive calls run in parallel automatically, returning only a summary |
-| `todolist`         | Working notepad: write a multi-step plan to `.mocode/plans/<id>.md` (survives compression) and tick steps as you go; `finish` auto-archives, with `list / delete / unarchive` for history |
-| `memory_save`      | Save a piece of cross-session long-term memory (title indexed, body fetched on demand) |
-| `memory_search`    | Search memory bodies by keyword; hits boost the recall count (affects forgetting decay) |
-| `memory_list`       | List the memory index (id/title/summary, no body)                        |
-| `memory_update`     | Edit a memory in place (id unchanged; correct stale facts / update summary / toggle pin) |
-| `memory_forget`     | Forget a memory: archived by default (recoverable), `mode=delete` for a hard delete (pinned memories can't be deleted) |
-
-## Slash commands
-
-| Command           | Purpose                                                              |
-| ------------------ | ----------------------------------------------------------------------- |
-| `/exit` `/quit`     | Exit MoCode                                                          |
-| `/clear`            | Clear history (keeps the system prompt) + clear screen               |
-| `/context`          | Show a context usage bar (tokens / message count, estimated or measured) |
-| `/skills`           | List discovered skills                                               |
-| `/compact`          | Compress history (optionally with a focus hint: `/compact …`)        |
-| `/resume`           | Resume a saved session                                                |
-| `/rollback`         | Menu to pick a turn to roll back to (↑↓ · Enter)                     |
-| `/memory`           | Show memory library: entry count + recent index                       |
-| `/reflect`          | Manually trigger a background memory reflection pass                  |
-| `/model`            | Configure the LLM (baseURL / apiKey / model / context window), applied immediately + persisted |
-| `/init`             | Scan the project and generate `MOCODE.md` project memory (dispatched to the agent) |
-| `/theme`            | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)         |
-| `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
-| `/auto`             | Switch back to auto mode (full toolset execution)                     |
-| `/pet`              | Toggle the optional desktop pet (floating window mirroring agent state) |
-| `/pet skin`         | Pick a pet skin (↑↓ · Enter)                                          |
-| `/pet quit`         | Fully shut down the pet process (not just disconnect)                 |
-
-Type `/` to trigger the dropdown menu, keep typing to filter; Esc to cancel.
-
-## Quick verification (after configuring your key)
-
-```
-> hello, who are you                  # verify LLM connectivity
-> read sample.txt                     # triggers read_file
-> change foo to bar in sample.txt     # triggers read_file + edit_file
-> list all .txt files in this directory  # triggers glob
-> search the code for runAgent        # triggers grep
-> run node -e "console.log(1+1)"      # triggers run_command
-> search what's new in TypeScript 5.5 # triggers web_search
-```
-
-Each step prints `● tool name + argument summary` and `↳ result preview` in the terminal; the agent decides the next step on its own within the loop, with responses streaming in as they're generated.
-
-## Skills
-
-MoCode automatically scans the following directories for skills (each skill is a `<name>/SKILL.md` with frontmatter):
-
-- `~/.claude/skills/`
-- `~/.mocode/skills/`
-- `<cwd>/.mocode/skills/`
-
-A skill's `description` is injected into the system prompt (progressive disclosure, tier 1); the model calls `use_skill` to load the full body (tier 2) only when the task is relevant. Use `/skills` to see discovered skills.
-
-## Type checking
-
-```bash
-npm run typecheck   # tsc --noEmit
-```
-
-## Future extensions
-
-MCP tool integration, a permission confirmation UI, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 20 tools, working-notepad planning, cross-session memory, parallel sub-agents, and an optional desktop pet.
+<img src="./assets/banner-en.svg?v=2" alt="MoCode">
+
+<p align="right">English | <a href="./README.zh-CN.md">简体中文</a></p>
+
+# MoCode
+
+A terminal coding agent: give it a goal, and it **completes it autonomously** — no step-by-step hand-holding required.
+
+MoCode explores your code, reads/writes/edits files, runs shell commands, and searches the web on its own, driving the task forward through a loop of "think → call a tool → observe the result → think again." It works with any OpenAI-compatible endpoint (GLM, DeepSeek, Qwen, local Ollama / vLLM, etc.), runs as a full-screen TUI with streaming output and visible reasoning.
+
+## Why MoCode
+
+MoCode isn't a chat box with a coat of paint — it's an agent that actually gets things done:
+
+- **Autonomous multi-step execution** — In a single conversation, the agent chains multiple steps on its own: read code, edit code, run tests, fix based on errors, and so on. It decides the next step without you nagging it. When it hits a decision point, it calls `ask_human` to pop up a panel and ask you (blocking until you respond).
+- **Parallel read-only tools** — Consecutive read-only operations in a turn (reading files, grep, glob, codegraph, web search/fetch) run concurrently, so total time is roughly the slowest single call instead of the sum of all of them. Operations with side effects (writing/editing files) stay sequential to preserve snapshot ordering and data safety.
+- **Sub-agents divide and conquer** — Complex tasks can spawn independent sub-agents, each with its own conversation history (isolated from the main thread), an optional restricted toolset, and a step cap. They can explore multiple code areas or directions in parallel and report back only a summary, which the main thread uses to decide what's next.
+- **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode unlocks the full toolset. The agent can switch between the two on its own — scope out an unfamiliar codebase first, then start making changes.
+- **Automatic context compression** — As the context window fills up, a three-tier compression kicks in (trim individual results → compact older tool results in place → summarize older turns), so long sessions never overflow. `/context` shows live token usage; `/compact` triggers manual compression (optionally with a focus hint to preserve what matters).
+- **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
+- **Working notepad (todolist)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent first writes a plan to `.mocode/plans/<id>.md` (file-based, survives context compression), then ticks each step as it goes. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`. `finish` auto-archives completed plans to `plans/archive/`, with explicit `list / delete / unarchive` actions.
+- **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
+- **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
+
+## Features
+
+- **Streaming output + visible reasoning** — Responses render as they're generated; when the model supports reasoning, the thinking process is visible in real time and auto-collapses to save screen space.
+- **Full-screen TUI** — Alt-screen mode with a fixed status bar, scrollback (PgUp/PgDn), typeahead while the agent is running, and auto-prefill for the next turn.
+- **Session persistence** — Every turn is saved automatically; `--resume` / `/resume` picks up a past session.
+- **Skills system** — Scans directories like `~/.mocode/skills/` automatically; each skill's description is injected into the system prompt, and the model calls `use_skill` to load the full instructions only when relevant (progressive disclosure: skim the summary first, load the body only if needed).
+- **Optional desktop pet** — A small floating window (`/pet`) shows a stateful character that mirrors agent activity (idle / thinking / tool running / waiting for human). Works as a separate process over WebSocket; quit it with `/pet quit`. Sits beside the terminal, never blocks it.
+- **Slash commands** — `/exit` `/clear` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`, with dropdown filtering as you type.
+
+## Installation
+
+Requires Node.js ≥ 18.
+
+```bash
+npm install -g mocode-ai
+```
+
+This gives you the `mocode` command. Prefer not to install globally? Run it directly with `npx mocode-ai`.
+
+> MoCode checks for new versions on startup and self-updates in the background via `npm i -g mocode-ai@latest` — the update takes effect on the next launch, with zero startup delay and silent failure if offline. This is skipped in dev mode (`npm start`, running via tsx).
+
+### Run from source (development / contributing)
+
+```bash
+git clone https://github.com/wanxunyang/mocode.git
+cd mocode
+npm install
+npm start
+```
+
+Source runs directly via tsx, no build step. After changing code, restart `npm start` for changes to take effect (tsx loads modules at startup, no hot reload). Runtime dependencies: `openai`, `dotenv`, `fast-glob`; dev dependencies: `tsx`, `typescript`, `@types/node`.
+
+## Configuration
+
+On first use, run the setup wizard to fill in three fields interactively (API base URL / key / model name), written to `~/.mocode/config` (global, works from any directory or terminal):
+
+```bash
+mocode config
+```
+
+You can also configure it from inside the REPL with the `/model` command (pick a backend preset interactively and fill in each field, applied immediately and persisted). Without configuration, the REPL still opens and prompts you to run `/model`.
+
+You can also hand-edit the config files. MoCode loads them in the following priority order (later entries override earlier ones, only backfilling unset environment variables; anything `export`ed in your shell always takes precedence):
+
+1. `<cwd>/.env` — legacy compatibility, lowest priority (see `.env.example` in the source repo for reference)
+2. `~/.mocode/config` — global (written by `/model` and `mocode config`)
+3. `<cwd>/.mocode/config` — project-level override, highest priority
+
+Three required fields:
+
+```env
+LLM_BASE_URL=https://open.bigmodel.cn/api/v3   # swap in your backend
+LLM_API_KEY=your-key-here
+LLM_MODEL=glm-4.6                              # swap in your model name
+```
+
+Common backend `base_url` values:
+
+| Backend        | base\_url                                           |
+| -------------- | ---------------------------------------------------- |
+| GLM (Zhipu)    | `https://open.bigmodel.cn/api/v3`                   |
+| DeepSeek       | `https://api.deepseek.com`                          |
+| Qwen (Alibaba) | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Local Ollama   | `http://localhost:11434/v1`                         |
+| Local vLLM     | `http://localhost:8000/v1`                          |
+
+> The model must support OpenAI-style function calling, otherwise tools won't be triggered.
+
+### Optional configuration
+
+| Environment variable       | Description                                                          | Default                     |
+| --------------------------- | ---------------------------------------------------------------------- | --------------------------- |
+| `MAX_TOKENS`                | Max tokens per response                                               | unlimited                   |
+| `CONTEXT_WINDOW_TOKENS`     | Model context window; must match the real model                      | `128000`                    |
+| `COMPACT_THRESHOLD`         | Auto-compaction trigger threshold (fraction of window)                | `0.85`                      |
+| `LLM_STREAM_USAGE`          | Include `stream_options.include_usage` on streaming requests for real usage | `true`                |
+| `AUTO_COMPACT`               | Auto-compaction master switch                                          | `true`                       |
+| `AUTO_REFLECT`               | Background reflection pass master switch (periodically mines memories from conversations) | `true`   |
+| `REFLECT_EVERY_N`            | Trigger a background reflection every N turns (runs alongside the agent, non-blocking) | `5`      |
+| `ANYSEARCH_API_KEY`         | Web search API key (falls back to anonymous free quota if unset)      | none                         |
+| `ANYSEARCH_BASE_URL`        | Search API endpoint                                                    | `https://api.anysearch.com` |
+| `SKILLS_DIRS`               | Override the default skill scan directories (platform path separator) | three default directories   |
+| `MOCODE_CONTEXT_OPTIMIZE`   | Typed encoding of tool results before they reach the LLM (tree/search/log…); disable for raw passthrough (length trimming only) | `true` |
+| `MAX_STEPS`                 | Max agent loop steps per turn (prevents infinite loops)               | `200`                        |
+| `SUB_AGENT_MAX_STEPS`       | Default step cap for sub-agents (spawned via the `task` tool)         | `50`                         |
+| `SANDBOX_ROOT`               | Sandbox root directory (file operation boundary; falls back to cwd if unset) | none                  |
+| `MOCODE_THEME`               | Color theme (default/dark/light…; shell env takes precedence over file) | `default`                   |
+
+## Usage
+
+```bash
+mocode                          # new session (run inside your target project directory)
+mocode --resume                 # list saved sessions
+mocode --resume <id>            # resume a specific session
+mocode config                   # edit configuration
+```
+
+Running from source uses `npm start` (equivalent to `mocode`, but skips the self-update check).
+
+Once in the REPL, just start chatting. It launches straight into the full-screen TUI, showing a banner (model / backend / working directory / tool list). Responses stream in, with the reasoning section visible in real time before collapsing.
+
+The agent operates in **the working directory it was launched from** — to have it work on a specific project, `cd` into that project before running `mocode`.
+
+## Tools
+
+| Tool             | Purpose                                                                  |
+| ---------------- | ------------------------------------------------------------------------- |
+| `read_file`       | Read a file with line numbers; supports `offset` / `limit`               |
+| `write_file`      | Create/overwrite a file, auto-creating parent directories                |
+| `edit_file`       | Precise string replacement (`old_string` must match uniquely)            |
+| `run_command`     | Run a shell command, merging stdout+stderr, 120s default timeout         |
+| `glob`            | Find files by glob pattern (excludes node\_modules/.git)                 |
+| `grep`            | Regex content search, pure JS implementation, no `rg` dependency         |
+| `codegraph`       | With a `.codegraph/` index built, query symbol source and call chains (more accurate and cheaper than read\_file/grep) |
+| `web_search`      | Web search (AnySearch), returns title/URL/snippet/body                   |
+| `web_fetch`       | Fetch a URL, cleaning HTML into plain text                                |
+| `use_skill`       | Load the full SKILL.md instructions for a given skill                    |
+| `ask_human`        | Pop up a Q&A panel at decision points; user picks a preset or types freely (blocks until answered) |
+| `switch_mode`      | Switch between `plan` (read-only planning) and `auto` (full execution); the agent can call this itself to explore before acting |
+| `drop_context`     | Replace irrelevant old tool results in history with stubs to free up context (preserves tool_call_id pairing, leaves system prompt and current turn untouched, idempotent) |
+| `task`             | Spawn a sub-agent for an independent subtask (isolated history, optional restricted toolset, optional step cap); consecutive calls run in parallel automatically, returning only a summary |
+| `todolist`         | Working notepad: write a multi-step plan to `.mocode/plans/<id>.md` (survives compression) and tick steps as you go; `finish` auto-archives, with `list / delete / unarchive` for history |
+| `memory_save`      | Save a piece of cross-session long-term memory (title indexed, body fetched on demand) |
+| `memory_search`    | Search memory bodies by keyword; hits boost the recall count (affects forgetting decay) |
+| `memory_list`       | List the memory index (id/title/summary, no body)                        |
+| `memory_update`     | Edit a memory in place (id unchanged; correct stale facts / update summary / toggle pin) |
+| `memory_forget`     | Forget a memory: archived by default (recoverable), `mode=delete` for a hard delete (pinned memories can't be deleted) |
+
+The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `MOCODE.md` and Tier-2 memory).
+
+## Slash commands
+
+| Command           | Purpose                                                              |
+| ------------------ | ----------------------------------------------------------------------- |
+| `/exit` `/quit`     | Exit MoCode                                                          |
+| `/clear`            | Clear history (keeps the system prompt) + clear screen               |
+| `/context`          | Show a context usage bar (tokens / message count, estimated or measured) |
+| `/skills`           | List discovered skills                                               |
+| `/compact`          | Compress history (optionally with a focus hint: `/compact …`)        |
+| `/resume`           | Resume a saved session                                                |
+| `/rollback`         | Menu to pick a turn to roll back to (↑↓ · Enter)                     |
+| `/memory`           | Show memory library: entry count + recent index                       |
+| `/memory_switch`   | Toggle Tier-2 memory on/off (REPL restart required — by design)       |
+| `/reflect`          | Manually trigger a background memory reflection pass                  |
+| `/model`            | Configure the LLM (baseURL / apiKey / model / context window), applied immediately + persisted |
+| `/init`             | Scan the project and generate `MOCODE.md` project memory (dispatched to the agent) |
+| `/theme`            | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)         |
+| `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
+| `/auto`             | Switch back to auto mode (full toolset execution)                     |
+| `/pet`              | Toggle the optional desktop pet (floating window mirroring agent state) |
+| `/pet skin`         | Pick a pet skin (↑↓ · Enter)                                          |
+| `/pet quit`         | Fully shut down the pet process (not just disconnect)                 |
+
+Type `/` to trigger the dropdown menu, keep typing to filter; Esc to cancel.
+
+## Quick verification (after configuring your key)
+
+```
+> hello, who are you                  # verify LLM connectivity
+> read sample.txt                     # triggers read_file
+> change foo to bar in sample.txt     # triggers read_file + edit_file
+> list all .txt files in this directory  # triggers glob
+> search the code for runAgent        # triggers grep
+> run node -e "console.log(1+1)"      # triggers run_command
+> search what's new in TypeScript 5.5 # triggers web_search
+```
+
+Each step prints `● tool name + argument summary` and `↳ result preview` in the terminal; the agent decides the next step on its own within the loop, with responses streaming in as they're generated.
+
+## Skills
+
+MoCode automatically scans the following directories for skills (each skill is a `<name>/SKILL.md` with frontmatter):
+
+- `~/.claude/skills/`
+- `~/.mocode/skills/`
+- `<cwd>/.mocode/skills/`
+
+A skill's `description` is injected into the system prompt (progressive disclosure, tier 1); the model calls `use_skill` to load the full body (tier 2) only when the task is relevant. Use `/skills` to see discovered skills.
+
+## Project memory (MOCODE.md)
+
+MoCode has a **two-tier memory** model distinct from skills:
+
+- **Tier-1 — `MOCODE.md` (auto-loaded every session):** Markdown project memory that gets concatenated into the system prompt on every turn. Discovery walks `~/.mocode/MOCODE.md` → every `MOCODE.md` from the cwd up to the filesystem root (far→near, near wins). On overflow the body is truncated with a marker pointing back at the files. Generate or refresh one with `/init`, or write it by hand — it's plain Markdown, no schema. `MOCODE.md` is also where the agent itself persists "next-session facts" it deduces (architecture, conventions, pitfalls).
+- **Tier-2 — `memory_*` tool library (agent-driven, opt-in):** Discrete tagged records (`decision` / `fact` / `pitfall` / `reference` / `feedback`) with recall-count-based decay (30-day → archived; 90-day → GC). The agent saves / searches / updates / forgets via tools; titles go in the system-prompt index (≤50), bodies fetched on demand via `memory_search`. Off by default; toggle with `MEMORY_ENABLED=true` at startup or `/memory_switch` (REPL restart required).
+
+## Type checking
+
+```bash
+npm run typecheck   # tsc --noEmit
+```
+
+## Future extensions
+
+MCP tool integration, a permission confirmation UI, and a real worktree-isolated sub-agent mode. The current version is a streaming, reasoning-visible, rollback-capable terminal coding agent with 20 tools, working-notepad planning, cross-session memory, parallel sub-agents, and an optional desktop pet.

package/README.zh-CN.md

@@ -150,6 +150,8 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `memory_update` | 原地改一条记忆(id 不变;纠正过时事实 / 改摘要 / 改 pin)                      |
 | `memory_forget` | 遗忘记忆:默认归档(可复活),`mode=delete` 硬删(pinned 拒删)               |
 
+5 个 `memory_*` 工具受启动时 `MEMORY_ENABLED=true` 总开关控制;运行时切换用 `/memory_switch`(需重启 REPL,刻意为之,见下「项目记忆」小节区分 Tier-1 / Tier-2)。
+
 ## 斜杠命令
 
 | 命令              | 作用                                                 |
@@ -162,6 +164,7 @@ agent 工作在**启动时所在的工作目录**——想让它操作某个项
 | `/resume`       | 续接已保存的会话                                           |
 | `/rollback`     | 菜单选轮次回滚(↑↓ · Enter)                                |
 | `/memory`       | 看记忆库:条目数 + 近期索引                                    |
+| `/memory_switch` | 切换 Tier-2 记忆开关(需重启 REPL,刻意为之)                  |
 | `/reflect`      | 手动触发一次后台记忆反思 pass                                   |
 | `/model`        | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
 | `/init`         | 扫描项目生成 `MOCODE.md` 项目记忆(发给 agent 执行)               |
@@ -198,6 +201,13 @@ mocode 自动扫描以下目录的 skill(每个 skill 是 `<name>/SKILL.md`,带
 
 skill 的 `description` 注入系统提示(渐进式披露第①层),模型只在任务相关时调 `use_skill` 加载完整正文(第②层)。用 `/skills` 查看已发现的 skill。
 
+## 项目记忆(MOCODE.md)
+
+mocode 的**双层记忆**模型,跟 Skills 是两件事:
+
+- **Tier-1 — `MOCODE.md`(每轮自动加载):** Markdown 项目记忆,每轮拼进 system prompt。发现路径:`~/.mocode/MOCODE.md` → 从 cwd 往上逐级 `MOCODE.md`(远→近拼接,近的覆盖更突出);超长截断并标注原始文件。运行 `/init` 生成或刷新,纯 Markdown,可手写,无 schema。agent 自己推得的「下次要记住的事实」(架构/约定/坑位)也写在这里。
+- **Tier-2 — `memory_*` 工具库(agent 主导,需启用):** 离散带标签条目(`decision` / `fact` / `pitfall` / `reference` / `feedback`),按召回计数衰减(30 天 → archived,90 天 → 硬删 GC)。agent 用工具存 / 搜 / 改 / 删;索引(标题)进系统提示(≤50 条),正文按需 `memory_search` 取。默认关,启动 `MEMORY_ENABLED=true` 或 REPL 内 `/memory_switch`(需重启 REPL,刻意为之)。
+
 ## 类型检查
 
 ```bash

package/dist/agent/index.js

@@ -7,10 +7,13 @@ import { Spinner } from '../ui/spinner.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed, } from '../ui/render.js';
 import { renderFileChange } from '../ui/diff.js';
 import * as layout from '../ui/layout.js';
+import * as batch from '../ui/batch.js';
 import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
 import { runAgentCore, isMutationTool, } from './core.js';
 import { createPetHooks } from '../pet/state.js';
+/** 当前 turn 的 batch id(runAgent 内闭包变量;一条 turn 一轮 tool batch 结束即清空)。 */
+let currentBatchId = null;
 /** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
 function firstLineOf(ui) {
     if (typeof ui === 'string')
@@ -18,15 +21,22 @@ function firstLineOf(ui) {
     const first = ui.find((p) => p.type === 'text');
     return first?.text.split('\n')[0] ?? '';
 }
-/** 工具调用 ● 头:工具名 + 参数摘要(按 tool_calls 原顺序打印,让用户看到本轮跑哪些工具)。 */
+/** 工具调用 ● 头:工具名 + 参数摘要(按 tool_calls 原顺序打印,让用户看到本轮跑哪些工具)。
+ *  重构后改为累积到 BatchRenderer,onToolBatchEnd 时统一打摘要行;
+ *  展开/折叠由 BatchRenderer + 鼠标 release 决定,本函数不再直接写屏。 */
 function writeToolHeader(tc) {
-    const summary = summarizeToolCall(tc.name, tc.arguments);
-    layout.contentWrite(`  ${ui.brightMagenta}●${ui.reset} ${ui.cyan}${tc.name}${ui.reset}  ${ui.dim}${summary}${ui.reset}\n`);
+    if (!currentBatchId)
+        currentBatchId = batch.beginBatch();
+    batch.recordCall(currentBatchId, tc.name, summarizeToolCall(tc.name, tc.arguments));
 }
-/** 渲染工具结果:mutation 成功走 diff 块(行号 + 语法高亮,仿 Claude Code);其余走一行 preview。 */
+/** 渲染工具结果:mutation 成功走 diff 块(行号 + 语法高亮,仿 Claude Code);其余走一行 preview。
+ *  同 writeToolHeader,改为累积到 BatchRenderer(只缓存字符串,不写屏)。 */
 function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
+    if (!currentBatchId)
+        return;
+    let diff = null;
     if (isMutationTool(tc.name) && parsed && !output.startsWith('错误')) {
-        layout.contentWrite(renderFileChange({
+        diff = renderFileChange({
             path: String(parsed.path ?? ''),
             kind: tc.name === 'edit_file' ? 'edit' : 'write',
             oldStr: tc.name === 'edit_file'
@@ -34,14 +44,10 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
                 : preWriteOld,
             newStr: String((tc.name === 'edit_file' ? parsed.new_string : parsed.content) ?? ''),
             startLine: tc.name === 'edit_file' ? editStartLine : 1,
-        }));
-    }
-    else {
-        const preview = summarizeToolResult(tc.name, output);
-        if (preview) {
-            layout.contentWrite(`  ${ui.gray}↳ ${preview}${ui.reset}\n`);
-        }
+        });
     }
+    const preview = diff ? '' : summarizeToolResult(tc.name, output);
+    batch.recordResult(currentBatchId, tc.name, preview, diff);
 }
 /**
  * agent 核心循环(主 agent,TUI 渲染版):
@@ -63,6 +69,7 @@ onContextUpdate) {
     // 开新轮次(回滚用):首行截断 40,供 /rollback 轮次菜单展示。
     beginTurn(truncateDisplay(firstLineOf(userInput), 40));
     layout.contentMode(); // 防御性:运行态光标归输入框光标位供 IME 锚定(enterRunningMode 已置,这里兜底)
+    currentBatchId = null; // 新 turn 清旧 batch id(防上 turn 残留)
     // spinner:状态行最前面转圈(思考中 / 生成 / 执行 工具时,状态栏 lead 位显帧 + 文字)。
     // 经 setStatus 注入状态行(spinnerFrame + statusText),composeStatus 把帧 + 文字放 lead 位;
     // 不画内容区续写位——内容区在等待期间保持干净,首 token 到达即从续写位开始写正文。
@@ -101,7 +108,16 @@ onContextUpdate) {
         onToolStart: (name) => spinner.start(`执行 ${name}`),
         onToolDone: () => spinner.stop(),
         onToolResult: (tc, output, parsed, preWriteOld, editStartLine) => writeToolResult(tc, output, parsed, preWriteOld, editStartLine),
-        onToolBatchEnd: () => layout.contentWrite('\n'),
+        onToolBatchEnd: () => {
+            // 收尾:把累积的 batch 渲染成单行摘要(批内 N 个 tool 调用共用一行,
+            // 鼠标点击该行可展开完整明细——见 ui/batch.ts)。无 batch(模型未调工具)则补空行保持间距。
+            if (currentBatchId) {
+                const id = currentBatchId;
+                currentBatchId = null;
+                batch.endBatch(id, layout);
+            }
+            layout.contentWrite('\n');
+        },
         onNoReply: () => layout.contentWrite(`${ui.dim}(无回复)${ui.reset}\n`),
         onMaxSteps: () => layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}达到最大步数(${config.maxSteps}),本轮停止。${ui.reset}\n`),
         onAbort: () => {
@@ -109,6 +125,7 @@ onContextUpdate) {
             if (lastChar && lastChar !== '\n')
                 layout.contentWrite('\n');
             layout.contentWrite(`${ui.dim}(已中断)${ui.reset}\n`);
+            currentBatchId = null; // 丢弃未收尾 batch
         },
         onDone: (elapsedMs, usage) => {
             const tok = formatTurnTokens(usage);