codemini-cli 0.5.8 → 0.5.10

package/README.md

@@ -5,7 +5,8 @@
 <h1 align="center">Codemini CLI</h1>
 
 <p align="center">
-  A sharp, controllable coding agent for teams that want the power of modern AI coding without the chaos of an oversized tool surface.
+  <b>An extremely restrained coding + tasks CLI.</b><br />
+  Every platform. Every terminal. Minimal by design.
 </p>
 
 <p align="center">
@@ -34,178 +35,229 @@
 
 ## English
 
-Codemini is a local-first coding assistant with a CLI, a polished browser UI, compact context management, project indexing, skills, personalities, planning, memory, approvals, and Windows-first shell ergonomics.
+### What is Codemini?
 
-It is built around a simple product bet: coding agents get better when their default surface is smaller, their context is cleaner, and their actions are easier to audit.
+Codemini is a **coding + tasks CLI** built for a simple premise: agentic help should work everywhere, scale from small models to frontier ones, and never waste your context budget.
 
-### Why It Feels Different
+It is equally at home refactoring a TypeScript codebase, automating a Git workflow, running a multi-step DevOps pipeline, or bulk-processing data files. **It is not limited to writing code** — it is a general-purpose task agent that happens to be very good at code.
 
-| What you get | Why it matters |
-| --- | --- |
-| **Small default tool surface** | Models spend less time choosing tools and more time doing the next useful thing. |
-| **Model-agnostic gateway config** | Works with OpenAI-compatible gateways and internal model providers. |
-| **Web UI included** | Sessions, projects, approvals, skills, souls, CodeWiki reports, and runtime status in one local browser app. |
-| **Compact context pipeline** | Micro-compact clears stale tool output; macro compact creates continuation summaries before context gets noisy. |
-| **Windows and PowerShell first** | Designed for real Windows developer machines, not just Unix demos. |
-| **Skills and souls** | Reusable workflows and response personalities without changing core execution policy. |
-| **Project index** | Keeps a lightweight `.codemini/` map so the agent can orient quickly. |
-| **Built-in safety rails** | Approvals, command policy, safe mode, todo tracking, and reviewable plans. |
+It runs on Windows, macOS, or Linux — in any terminal (PowerShell, bash, zsh, and others). It works with any OpenAI-compatible or Anthropic API, so you are never locked into a single provider. And it gives you **two surfaces** — a rich terminal TUI and a browser-based Web UI — sharing the same sessions and engine.
 
-### Quick Start
+Codemini can use **two models in one session**: a lightweight model for routing and simple tasks, and a larger model for complex reasoning. Configure both, and the system dispatches work to the right one.
 
-Requires **Node.js 22 or newer**.
+Other built-in capabilities include project indexing, persistent memory with self-evolution via `/reflect`, skill-based workflows, planning mode, approvals, and soul presets that change its tone without changing its behavior.
 
-```bash
-npm install -g codemini-cli
-codemini config set gateway.base_url http://your-gateway/v1
-codemini config set gateway.api_key your_token
-codemini config set model.name your-model
-codemini
-```
+No SaaS. No telemetry. No mandatory registration.
 
-Open the Web UI:
+### Why "Restrained"?
 
-```bash
-codemini --web
-```
+Many coding agents pursue an ever-expanding surface — more tools, more context, more automation. Codemini takes the opposite approach.
 
-On a new machine, the Web UI opens first and lets you configure the gateway from Settings, so a missing or wrong default endpoint does not block startup.
+- **Small dependency footprint.** A focused set of npm packages. No Electron, no Docker, no Python runtime.
+- **Managed context budgets.** Micro-compaction, tool-result spill-to-disk, prompt preflight triggers — designed to stay within your model's window.
+- **Dual-model dispatch.** Configure a lightweight model (for routing and simple tasks) alongside a frontier model (for complex reasoning). Work reaches the right model automatically.
+- **Proportional approvals.** Commands are classified by intent. Read-only operations pass through; destructive actions prompt for confirmation. You control the threshold.
+- **Lazy-loaded skills.** A catalog of 1,000 skills costs the same as 1. Only the invoked skill contributes to the prompt.
+- **Curated memory with self-evolution.** Inbox is temporary by design. The dream loop curates it, and `/reflect` converts successful patterns into reusable skills.
 
-### Web UI
+It is not about delivering less capability. It is about eliminating what you should not have to carry.
 
-The Web UI is bundled with the npm package and runs locally.
+#### By the Numbers: What "Restrained" Looks Like
+
+A typical first-turn system prompt in a real project — with AGENTS.md, an auto skill, memory snapshot, and project context — costs approximately **5,300 tokens**. The breakdown:
 
-```bash
-codemini --web
-codemini --web --port 3210 --project /path/to/project
-codemini --web --session <session-id> --model <model-name> --no-open
+```
+  base system prompt          2,703 tokens  ████████████████░░░░░░░░░  51%
+  AGENTS.md project rules       535 tokens  ███░░░░░░░░░░░░░░░░░░░░░  10%
+  auto skill (superpowers)    1,371 tokens  ████████░░░░░░░░░░░░░░░░  26%
+  memory snapshot               144 tokens  █░░░░░░░░░░░░░░░░░░░░░░░   3%
+  project index snippet         447 tokens  ██░░░░░░░░░░░░░░░░░░░░░░   8%
+  reply language wrapper         27 tokens  ░░░░░░░░░░░░░░░░░░░░░░░░   1%
+  ─────────────────────────────────────────────────────────────────
+  total first turn            ~5,300 tokens
 ```
 
-Highlights:
+By contrast, many alternatives ship **15K–25K tokens** of system prompt before a user's first message. Every installed skill, saved memory, and rule file is poured in unconditionally.
 
-| Area | What it does |
-| --- | --- |
-| Chat runtime | Uses the same sessions and config as the CLI. |
-| Project switcher | Move between repositories and general chat without restarting. |
-| Approvals | Review tool calls and plans in focused dialogs/cards. |
-| Skills | Create, inspect, install, enable, and disable reusable workflows. |
-| Souls | Switch response tone without changing execution logic. |
-| CodeWiki | Generate project-requirements reports and ask read-only questions over them. |
-| Runtime status | See active mode, git branch, version state, live progress, and context usage. |
+Codemini's restraint is architectural:
 
-Local Web UI development:
+- **Skills lazy-load.** Ten skills installed = same system prompt cost as zero. Only the selected skill's body is loaded.
+- **Memory is curated.** Inbox is temporary noise; only promoted memories enter the prompt. You control the volume.
+- **Project index is compact.** Symbol maps replace raw file trees. An entire repository fits in a few hundred tokens.
+- **No hidden payloads.** No telemetry scripts, no usage trackers, no injected context you did not request.
+
+The principle is straightforward: **less prompt tax means more budget for actual work.**
+
+### Quick Start
 
 ```bash
-cd codemini-web
-bun install
-bun run dev
+# Install globally
+npm install -g codemini-cli
+
+# Configure your gateway
+codemini config set gateway.base_url http://127.0.0.1:8000/v1
+codemini config set gateway.api_key your_api_key
+codemini config set model.name your_model_name
+
+# Start a session
+codemini
 ```
 
-Single built server:
+Three commands, and you are in an interactive session.
+
+### Beyond Code: Automated Tasks
+
+Codemini's `codemini run` command turns any natural-language task into an automated workflow — no coding required.
 
 ```bash
-cd codemini-web
-npm run build
-npm run start -- --port 3210
-```
+# Interactive session (chat)
+codemini "Summarize the recent Git history and write a CHANGELOG.md"
 
-### Command Surface
+# One-off task
+codemini run "Find all .env files in this repo and check for hardcoded secrets"
 
-| Command | Description |
-| --- | --- |
-| `codemini [prompt]` | Start an interactive coding session. |
-| `codemini chat [prompt]` | Chat mode for single-turn or multi-turn use. |
-| `codemini run <task>` | Run a coding task non-interactively. |
-| `codemini run --harness <role> <task>` | Run with a specific sub-agent role such as `coder`, `planner`, or `reviewer`. |
-| `codemini run --pipeline <task>` | Run planning, implementation, and review as a pipeline. |
-| `codemini --web` | Launch the local Web UI. |
-| `codemini config set|get|list <key> [value]` | Manage gateway, model, shell, UI, context, memory, and soul settings. |
-| `codemini doctor` | Run environment diagnostics. |
-| `codemini skill list|install|enable|disable|inspect|reindex` | Manage builtin, project, and global skills. |
+# Multi-role harness — planner + coder + reviewer in sequence
+codemini run --harness coder "Refactor the auth module to extract middleware"
 
-### Context Compacting
+# Pipeline — sequential steps with artifact passing
+codemini run --pipeline "Bump version, update CHANGELOG, and create a GitHub release draft"
+```
 
-Codemini keeps long sessions usable with a two-phase compact pipeline:
+Common non-coding task examples:
 
-1. **Micro compact** replaces old tool result bodies with a lightweight marker while preserving message order.
-2. **Macro compact** summarizes older context and keeps a legal recent message window for model APIs.
+| Task | Command |
+| --- | --- |
+| **System diagnostics** | `codemini run "Check disk usage, top 5 memory processes, and recent error logs"` |
+| **Git batch operations** | `codemini run "Squash the last 3 commits with message 'fix: pagination edge cases'"` |
+| **Data migration** | `codemini run "Read users.csv, normalize emails, deduplicate by ID, write to users.json"` |
+| **Release prep** | `codemini run --pipeline "Bump patch version, update CHANGELOG, git tag, build"` |
+| **Dependency audit** | `codemini run "List all outdated npm packages and summarize breaking changes"` |
+| **Project cleanup** | `codemini run "Find orphaned test fixtures and temporary debug logs"` |
 
-The compact view is stored with the session, so follow-up prompts continue from the compressed context while the full transcript remains available in history.
+The `--harness` flag assigns a **role** (`planner`, `advisor`, `coder`, `reviewer`, `tester`) that constrains tool access. The `--pipeline` flag runs a multi-step plan where each step's output feeds the next. Both modes turn Codemini into a headless task agent — like Claude Code, but running entirely on your machine, with your model, under your approval policy.
 
-### Skills
+| What | Why it matters |
+| --- | --- |
+| **🧠 Persistent Memory** | `/capture` → inbox → dream consolidation → user, global, and project memory tiers. Your agent learns from your project. |
+| **📂 Project Index** | Automatic `.codemini/` index with languages, symbols, imports, and exports. Refreshed incrementally after every edit. |
+| **🛠 Skills System** | Decoupled routing metadata with lazy-loaded `SKILL.md` bodies. Bring your own workflow or choose from built-in presets. |
+| **🔄 Self-Evolution** | `/reflect` converts successful workflows into reusable, reviewable `SKILL.md` files. Your toolset grows with your project. |
+| **⚡ Dual-Model Dispatch** | Configure a fast, lightweight model alongside a capable frontier model. The system routes each task to the appropriate one. |
+| **🖥 Terminal TUI** | Rich, interactive terminal UI with spinner animations, syntax-highlighted code blocks, live command output, and real-time status. |
+| **🕸 Web UI** | Full browser interface — same engine, shared sessions. Switch between terminal and browser freely. |
+| **🎭 Souls** | Tone presets (`professional`, `playful`, `anime`, `caveman`…) that change expression without affecting execution policy. |
+| **📋 Planning Mode** | Multi-step plans with file paths, verification steps, and explicit approval before execution. |
+| **🔒 Approvals** | Commands classified by risk level. Read-only passes; destructive operations pause for confirmation. Configurable thresholds. |
+| **💾 Session Checkpoints** | Save, branch, or replay session state. Context is preserved across crashes and model errors. |
+| **🌍 Cross-Platform** | PowerShell on Windows, bash/zsh on macOS and Linux — same tool, same configuration format, same behavior. |
 
-Skills are reusable workflow instructions that can be triggered explicitly or injected automatically when relevant.
+### Skills
 
-Bundled skills:
+Skills are reusable, reviewable workflow recipes. Built-in:
 
-| Skill | Use case |
+| Skill | When to use |
 | --- | --- |
-| `superpowers-lite` | Default coding workflow: inspect, plan only when useful, edit narrowly, verify. |
-| `grill-me` | Pressure-test plans, PRs, launches, or ideas. |
-| `brainstorm` | Explore several reasonable approaches before coding. |
-| `writing-plans` | Produce implementation plans with exact files and checks. |
+| `superpowers-lite` | Default coding flow: inspect, plan when needed, edit narrowly, verify. |
+| `grill-me` | Stress-test a plan, PR, release, or idea before committing. |
+| `brainstorm` | Compare options when multiple approaches are reasonable. |
+| `writing-plans` | Generate an implementation plan with file paths and verification steps. |
 
 ```bash
 codemini skill list
 codemini skill install <path>
-codemini skill install --scope=global <path>
 codemini skill inspect <name>
+codemini skill enable <name>
+codemini skill disable <name>
+codemini skill reindex
 ```
 
-### Souls
+Skills use a flat catalog (`codemini.skills.json`) with lightweight routing metadata — `description`, `mode`, `triggers`, `enabled`, `priority`. Codemini reads only this metadata at startup; the full `SKILL.md` is loaded only when a skill is selected or invoked. If the catalog is missing, the system falls back to `SKILL.md` frontmatter.
 
-Souls change tone and expression style without changing tool policy or execution behavior.
+Invoke any enabled skill as a slash command inside a session, or pass the slash command as a one-off prompt:
 
-Built-in presets:
+```bash
+# Inside an interactive session
+/grill-me review this release plan before I tag it
+/writing-plans add OAuth refresh-token rotation
 
-```text
-default, professional, ceo, playful, anime, caveman, pirate
+# One-off invocation from your shell
+codemini '/brainstorm compare SQLite, Postgres, and DuckDB for local analytics'
+codemini '/project-requirements generate a CodeWiki report for this repository'
 ```
 
+### Terminal TUI & Web UI
+
+Codemini gives you **two surfaces** powered by the same engine.
+
+**Terminal TUI** — rich interactive interface with spinner animations for long-running tasks, syntax-highlighted code blocks, live command output streaming, and a command palette with autocomplete. Runs in any terminal emulator; no separate process needed.
+
+**Web UI** — full browser interface sharing the same session state:
+
 ```bash
-codemini config set soul.preset professional
+codemini --web
 ```
 
-### Memory And Dream Loop
+Sessions are shared between terminal and browser — switch freely. From an active CLI session, type `web` to launch the browser UI.
+
+Additional Web UI options (port, project directory, session, model) are available via flags like `--port`, `--project`, `--session`, `--model`, `--no-open`.
+
+**Souls** — change the agent's tone without changing behavior. Built-in presets: `default`, `professional`, `ceo`, `playful`, `anime`, `caveman`, `pirate`. Configure with `codemini config set soul.preset professional`.
+
+### Memory, Self-Evolution & Dream Loop
 
-Codemini has native memory tools and slash commands:
+Codemini's memory system is designed to **learn from your work**, not just store facts.
 
 | Command | Purpose |
 | --- | --- |
-| `/capture <summary>` | Capture a high-signal observation into inbox. |
+| `/capture <summary>` | Record a signal into the inbox. |
 | `/inbox` | Review pending memory evidence. |
 | `/dream [--dry-run]` | Consolidate inbox entries into durable user/global/project memory. |
-| `/reflect` | Turn a successful workflow into a reviewed `SKILL.md` draft. |
+| `/reflect` | Convert a successful workflow pattern into a reviewable `SKILL.md` — your toolset evolves as you work. |
 
-Inbox is intentionally temporary and noisy. Dream consolidation decides what deserves promotion into longer-term memory.
+The inbox is intentionally noisy. The dream loop determines what deserves promotion into longer-term storage. And `/reflect` closes the loop: a pattern you've repeated successfully becomes a reusable skill, reviewed and versioned alongside your project.
 
-### Project Index
+Typical reflect loop:
 
-Codemini maintains a lightweight project map under `.codemini/`:
+```bash
+# 1. Finish a workflow that worked well, then ask Codemini to extract the pattern.
+/reflect preserve the provider tool-call recovery workflow from the last task
 
-| File | Purpose |
-| --- | --- |
-| `.codemini/project-map.json` | Languages, roots, tests, entry candidates, and repo-level facts. |
-| `.codemini/file-index.json` | Imports, exports, functions, classes, and symbol hints. |
+# 2. Review the generated draft in the TUI/Web UI.
+/yes
 
-The index is initialized when entering a project and refreshed after edits/writes/patches.
+# 3. Codemini writes .codemini/skills/provider-tool-call-recovery/SKILL.md
+#    and immediately exposes it as a slash skill.
+/provider-tool-call-recovery fix the same issue in the Anthropic adapter
 
-### Optional Accelerators
+# 4. The same skill can also be launched directly from the shell.
+codemini '/provider-tool-call-recovery audit provider message conversion'
+```
 
-FFF search acceleration:
+Use `--scope=global` when the workflow should follow you across repositories:
 
 ```bash
-codemini doctor
+/reflect --scope=global turn the release checklist I just used into a reusable skill
+codemini '/release-checklist prepare a patch release'
 ```
 
-If `fff-mcp` is present in `PATH`, Codemini can use it for faster `grep`, `glob`, and selected `list` paths. If it is missing, built-in search is used.
+### Project Index & Code Intelligence
 
-Playwright rendering for JavaScript-heavy pages:
+Codemini builds a lightweight but precise code index for every project you work in. It uses **Tree-sitter AST parsing** to extract symbols — not naive regex or line counting.
 
-```bash
-npm install -g playwright
-playwright install chromium
-```
+| File | Content |
+| --- | --- |
+| `.codemini/project-map.json` | Languages, source roots, test directories, entry candidates, repository facts. |
+| `.codemini/file-index.json` | Per-file imports, exports, function and class declarations, interfaces, type aliases — extracted via language-aware AST queries. |
+
+The index powers every code-aware tool in the system:
+
+- **`grep` and `glob`** use the file map to skip irrelevant directories (node_modules, build artifacts, .git) before touching the filesystem.
+- **`ast_query` / `read_ast_node`** resolve symbol targets to precise line and column ranges, enabling surgical edits without manual offset math.
+- **`read` with AST context** can return enclosing function bodies or class definitions around a cursor position.
+
+Index freshness is maintained incrementally: after every `edit`, `write`, or `patch` call, only the affected file is re-parsed and its index entry replaced. No full rebuild on every change.
+
+Language support covers JavaScript, TypeScript, TSX, Python, Go, C, C++, Rust, Java, C#, PHP, Ruby, and Bash — each with a dedicated Tree-sitter grammar.
 
 ### Data Paths
 
@@ -215,9 +267,22 @@ playwright install chromium
 | Project state | `.codemini/` |
 | Project skills | `.codemini/skills/<name>/SKILL.md` |
 | Global skills | `<base-config-dir>/skills/<name>/SKILL.md` |
-| Windows config | `%APPDATA%\codemini-global\` |
-| macOS config | `~/Library/Preferences/codemini-global` |
-| Linux/XDG config | `$XDG_CONFIG_HOME/codemini-global` |
+| Windows | `%APPDATA%\codemini-global\` |
+| macOS | `~/Library/Preferences/codemini-global` |
+| Linux / XDG | `$XDG_CONFIG_HOME/codemini-global` |
+
+The base config directory can be overridden via the `CODEMINI_GLOBAL_DIR` environment variable.
+
+### Optional Accelerators
+
+**FFF search acceleration:** `codemini doctor` checks for `fff-mcp` in the system PATH and uses it for faster `grep`, `glob`, and selected `list` operations. Falls back to built-in search if unavailable.
+
+**Playwright rendering** for JavaScript-heavy pages:
+
+```bash
+npm install -g playwright
+playwright install chromium
+```
 
 ### Development
 
@@ -227,7 +292,7 @@ npm test
 npm start
 ```
 
-Build the bundled Web UI:
+Build the Web UI bundle for production:
 
 ```bash
 npm run build:web
@@ -235,9 +300,9 @@ npm run build:web
 
 ### Documentation
 
-- [OPERATIONS.md](./OPERATIONS.md) - day-to-day operator guide
-- [deployment.md](./deployment.md) - packaging, installation, and deployment
-- [Releases](https://github.com/havingautism/Codemini-CLI/releases) - changelog
+- [OPERATIONS.md](./OPERATIONS.md) — daily operations manual
+- [deployment.md](./deployment.md) — packaging, installation, deployment
+- [Releases](https://github.com/havingautism/Codemini-CLI/releases)
 
 ### License
 
@@ -249,178 +314,229 @@ npm run build:web
 
 ## 简体中文
 
-Codemini 是一个本地优先的 coding agent：既有 CLI，也有精致的本地 Web UI；内置上下文压缩、项目索引、Skills、Souls、计划审批、记忆演化和 Windows / PowerShell 友好的执行体验。
+### Codemini 是什么？
 
-它的核心判断很简单：coding agent 不应该默认暴露一堆工具、塞满上下文、让用户看不清它做了什么。Codemini 选择更小的默认工具面、更干净的上下文、更可审计的执行链路。
+**一款刻意保持克制的 coding + tasks CLI。** 不仅能写代码——Git 工作流自动化、DevOps 流水线、数据批量处理、系统诊断，它都能干。
 
-### 为什么看起来更像一个产品
+兼容 Windows PowerShell、macOS zsh、Linux bash 等各种终端环境。兼容任何 OpenAI 兼容或 Anthropic 的 API，不绑定特定模型或提供商。提供**双界面**——基于 Ink + React 构建的终端 TUI 和浏览器 Web UI——共享同一引擎和会话。
 
-| 你得到什么 | 为什么重要 |
-| --- | --- |
-| **精简默认工具面** | 模型少犹豫，少乱走，优先做下一件有用的事。 |
-| **模型网关可配置** | 支持 OpenAI 兼容接口，也适合内部模型网关。 |
-| **内置 Web UI** | 会话、项目、审批、技能、人格、CodeWiki、运行状态集中管理。 |
-| **上下文压缩链路** | micro compact 清理旧工具输出，macro compact 生成可继续工作的摘要。 |
-| **Windows / PowerShell 一等支持** | 面向真实 Windows 开发机，而不是只适配 Unix demo。 |
-| **Skills 和 Souls** | 把稳定工作流沉淀成技能，把回复风格和执行逻辑分开。 |
-| **轻量项目索引** | 在 `.codemini/` 里维护事实索引，让模型更快理解仓库。 |
-| **安全和审计** | 审批、命令策略、safe mode、todo、计划卡片都内置。 |
+支持**大小模型协同工作**：配置一个轻量模型处理路由和简单任务，一个大模型负责复杂推理，系统自动调度。
 
-### 快速开始
+其他内置能力包括项目索引、持久记忆与 `/reflect` 自我进化、技能工作流、计划模式、审批机制，以及仅改变语气不改变行为的人格预设（Souls）。
 
-需要 **Node.js 22 或更高版本**。
+无需 SaaS、无需遥测、无需注册。
 
-```bash
-npm install -g codemini-cli
-codemini config set gateway.base_url http://your-gateway/v1
-codemini config set gateway.api_key your_token
-codemini config set model.name your-model
-codemini
-```
+### 「克制」体现在哪里？
 
-启动 Web UI：
+当前多数 AI 编码工具的策略是做加法——不断堆叠工具、上下文、自动化能力。Codemini 选择了相反的方向。
 
-```bash
-codemini --web
-```
+- **依赖极简。** 仅依赖少量精选的 npm 包。没有 Electron、Docker 或 Python 运行时。
+- **上下文预算可控。** 微压缩、工具结果溢出到磁盘、提示预检触发——为控制模型窗口使用而设计。
+- **大小模型协同。** 配置一个轻量模型处理路由和简单任务，一个大模型负责复杂推理，系统自动分派。
+- **审批有度。** 命令按意图分级：只读操作直接放行，破坏性操作暂停确认。阈值由你设定。
+- **技能懒加载。** 注册 1,000 个技能与注册 1 个的开销相同。只有被实际调用的技能才会进入提示上下文。
+- **记忆择优而存，自我进化。** Inbox 本质上是临时草稿箱，Dream 循环决定晋升内容，`/reflect` 把成功工作流沉淀为可复用的 skill。
 
-新电脑上即使默认接口还没配置好，Web UI 也会先打开，然后在设置里配置 Base URL、API Key 和模型，不会因为默认接口 404 卡住启动。
+并非功能更少，而是不背负不必要的负担。
 
-### Web UI
+#### 数据视角：「克制」的实际效果
 
-Web UI 随 npm 包一起发布，本地运行：
+一个真实项目的首轮 system prompt——包含 AGENTS.md、auto skill、记忆快照和项目上下文——大约消耗 **5,300 tokens**。具体构成如下：
 
-```bash
-codemini --web
-codemini --web --port 3210 --project /path/to/project
-codemini --web --session <session-id> --model <model-name> --no-open
+```
+  基础 system prompt           2,703 tokens  ████████████████░░░░░░░░░  51%
+  AGENTS.md 项目规则             535 tokens  ███░░░░░░░░░░░░░░░░░░░░░  10%
+  auto skill（superpowers）    1,371 tokens  ████████░░░░░░░░░░░░░░░░  26%
+  记忆快照                       144 tokens  █░░░░░░░░░░░░░░░░░░░░░░░   3%
+  项目索引片段                   447 tokens  ██░░░░░░░░░░░░░░░░░░░░░░   8%
+  回复语言包装                    27 tokens  ░░░░░░░░░░░░░░░░░░░░░░░░   1%
+  ─────────────────────────────────────────────────────────────────
+  首轮总计                     ~5,300 tokens
 ```
 
-能力概览：
+相比之下，许多同类工具在用户发出第一条消息之前，**system prompt 已占用 15K–25K tokens**。每安装一个 skill、每保存一条记忆、每编写一个规则文件，都会无条件注入。
 
-| 区域 | 作用 |
-| --- | --- |
-| 对话运行时 | 复用 CLI 的会话和配置。 |
-| 项目切换 | 不重启进程也能切换仓库和普通会话。 |
-| 审批 | 用弹窗/卡片审阅工具调用和计划。 |
-| Skills | 创建、查看、安装、启用、禁用可复用工作流。 |
-| Souls | 切换表达风格，不影响执行策略。 |
-| CodeWiki | 生成项目需求报告，并基于报告做只读问答。 |
-| 运行状态 | 展示执行模式、git 分支、版本状态、实时进度和上下文占用。 |
+Codemini 的克制源自架构设计：
 
-本地开发：
+- **Skill 懒加载。** 安装 10 个 skill 与安装 0 个，system prompt 开销相同。只有被命中的 skill 才会加载完整内容。
+- **记忆有筛选。** Inbox 是临时噪声层，只有经过晋升的记忆才会进入提示上下文。你控制水位。
+- **项目索引紧凑。** 符号映射替代原始文件树。整个仓库仅需数百 token。
+- **无隐藏负担。** 没有遥测脚本、用量追踪，或未经你要求注入的上下文。
+
+核心逻辑很简单：**prompt 税越少，留给实际工作的预算就越多。**
+
+### 快速开始
 
 ```bash
-cd codemini-web
-bun install
-bun run dev
+# 全局安装
+npm install -g codemini-cli
+
+# 配置网关
+codemini config set gateway.base_url http://127.0.0.1:8000/v1
+codemini config set gateway.api_key 你的 API Key
+codemini config set model.name 你的模型名称
+
+# 启动会话
+codemini
 ```
 
-构建后单进程运行：
+三步完成配置，进入交互式会话。
+
+### 不止写代码：自动化任务
+
+`codemini run` 可以把任何自然语言任务变成自动化工作流——不需要写脚本。
 
 ```bash
-cd codemini-web
-npm run build
-npm run start -- --port 3210
+# 交互式会话
+codemini "查看最近的 Git 提交历史，生成一份 CHANGELOG.md"
+
+# 一次性任务
+codemini run "扫描项目中所有 .env 文件，检查是否有硬编码密钥"
+
+# 多角色组合 — planner + coder + reviewer 接力
+codemini run --harness coder "重构 auth 模块，抽离中间件"
+
+# 流水线 — 多步骤任务，步骤间传递产物
+codemini run --pipeline "升级版本号、更新 CHANGELOG、创建 GitHub release 草稿"
 ```
 
-### 命令概览
+非编码任务举例如下：
 
-| 命令 | 说明 |
+| 任务 | 命令 |
 | --- | --- |
-| `codemini [prompt]` | 启动交互式编码会话。 |
-| `codemini chat [prompt]` | 单轮或多轮对话模式。 |
-| `codemini run <task>` | 非交互式执行编码任务。 |
-| `codemini run --harness <role> <task>` | 用指定 sub-agent 角色执行任务。 |
-| `codemini run --pipeline <task>` | 计划、实现、审查流水线。 |
-| `codemini --web` | 打开本地 Web UI。 |
-| `codemini config set|get|list <key> [value]` | 管理网关、模型、shell、UI、上下文、记忆、人格配置。 |
-| `codemini doctor` | 环境诊断。 |
-| `codemini skill list|install|enable|disable|inspect|reindex` | 管理内置、项目级、全局 Skills。 |
+| **系统诊断** | `codemini run "检查磁盘使用率、Top 5 内存进程、最近错误日志"` |
+| **Git 批量操作** | `codemini run "把最近 3 个 commit 压缩成一个，提交信息为 fix: pagination edge cases"` |
+| **数据迁移** | `codemini run "读取 users.csv，标准化邮箱字段，按 ID 去重，写入 users.json"` |
+| **版本发布** | `codemini run --pipeline "升级 patch 版本、更新 CHANGELOG、git tag、构建"` |
+| **依赖审计** | `codemini run "列出所有过时的 npm 包，概述 breaking changes"` |
+| **项目清理** | `codemini run "查找孤立的测试 fixture 文件和临时调试日志"` |
 
-### 上下文压缩
+`--harness` 参数指定一个**角色**（`planner`、`advisor`、`coder`、`reviewer`、`tester`），每个角色有独立的工具访问权限。`--pipeline` 执行多步骤计划，每步输出自动传入下一步。两种模式让 Codemini 变成无头任务 agent——类似 Claude Code，但完全运行在你的机器上、使用你的模型、遵循你的审批策略。
 
-Codemini 用两阶段 compact 保持长会话可继续：
+### 功能速览
 
-1. **Micro compact**：把旧 tool result 正文替换成轻量标记，保留消息顺序。
-2. **Macro compact**：把旧上下文总结成 continuation summary，并保留合法的最近消息窗口。
-
-compact view 会写入 session，后续提问使用压缩视图继续；完整历史仍留在 session 里。
+| 功能 | 说明 |
+| --- | --- |
+| **🧠 持久记忆** | `/capture` → inbox → dream 整理 → 用户/全局/项目三层记忆。让 agent 记住项目上下文。 |
+| **📂 项目索引** | 自动维护 `.codemini/` 索引，记录语言、符号、导入导出关系。编辑后增量刷新。 |
+| **🛠 技能系统** | 路由元数据与技能体分离。可自行编写 `SKILL.md`，也可使用内置工作流。 |
+| **🔄 自我进化** | `/reflect` 把成功工作流转化为可复用的 `SKILL.md`。你的工具箱随项目成长。 |
+| **⚡ 大小模型协同** | 配置轻量模型做路由与简单任务，大模型做复杂推理，系统自动分派。 |
+| **🖥 终端 TUI** | 富交互终端界面——旋转动画、语法高亮代码块、实时命令输出流、自动补全命令面板。 |
+| **🕸 Web UI** | 浏览器界面，同一引擎。终端与浏览器共享会话，可随时切换。 |
+| **🎭 Souls 人格** | 预设语气（专业、活泼、动漫、原始人……），只改变表达方式，不改变执行策略。 |
+| **📋 计划模式** | 多步骤实施计划，包含文件路径与验证步骤，执行前需确认。 |
+| **🔒 命令审批** | 按风险分级：只读操作直接放行，破坏性操作暂停确认。阈值可配置。 |
+| **💾 会话检查点** | 随时保存、回退、分支会话状态。崩溃或模型异常不丢失上下文。 |
+| **🌍 全平台支持** | Windows PowerShell、macOS zsh、Linux bash——同一套配置，同一套行为。 |
 
 ### Skills
 
-Skill 是可复用工作流，可以显式触发，也可以在适合时自动注入。
-
-内置 Skills：
+Skills 是可复用、可审阅的工作流配方。内置：
 
 | Skill | 适用场景 |
 | --- | --- |
-| `superpowers-lite` | 默认编码流程：先理解、必要时计划、小范围编辑、验证后报告。 |
-| `grill-me` | 对方案、PR、发布、想法做压力测试。 |
-| `brainstorm` | 多种方案都合理时，先比较选项再动手。 |
-| `writing-plans` | 生成带文件路径和验证步骤的实施计划。 |
+| `superpowers-lite` | 默认编码流程：先了解、必要时计划、小范围修改、验证后汇报。 |
+| `grill-me` | 对方案、PR、发布、想法做压力测试，发现潜在问题。 |
+| `brainstorm` | 多种方案难以抉择时，先比较选项再行动。 |
+| `writing-plans` | 生成包含文件路径和验证步骤的实施计划。 |
 
 ```bash
 codemini skill list
 codemini skill install <path>
-codemini skill install --scope=global <path>
 codemini skill inspect <name>
+codemini skill enable <name>
+codemini skill disable <name>
+codemini skill reindex
 ```
 
-### Souls
+路由元数据集中在顶层 catalog（`codemini.skills.json`），仅存储 `description`、`mode`、`triggers`、`enabled`、`priority` 等轻量字段。启动时不读取完整 `SKILL.md`，仅在被命中或显式调用时才加载。catalog 缺失时回退到目录和 frontmatter。
 
-Soul 只改变语气和表达风格，不改变工具策略或执行逻辑。
+任何启用的 skill 都可以在会话里当作 slash command 调用，也可以作为一次性 prompt 从 shell 直接启动：
 
-内置预设：
+```bash
+# 在交互式会话中
+/grill-me 帮我审一遍这个发布方案再打 tag
+/writing-plans 设计 OAuth refresh-token 轮换方案
 
-```text
-default, professional, ceo, playful, anime, caveman, pirate
+# 从 shell 一次性调用
+codemini '/brainstorm 比较 SQLite、Postgres 和 DuckDB 做本地分析的取舍'
+codemini '/project-requirements 为当前仓库生成一份 CodeWiki 报告'
 ```
 
+### 终端 TUI 与 Web UI
+
+Codemini 提供**双界面**，由同一引擎驱动。
+
+**终端 TUI**——富交互界面，支持长时间任务的旋转动画、语法高亮的代码块、实时命令输出流、以及带自动补全的命令面板。在任何终端模拟器中运行，无需额外进程。
+
+**Web UI**——完整的浏览器界面，与会话状态实时同步：
+
 ```bash
-codemini config set soul.preset professional
+codemini --web
 ```
 
-### 记忆与 Dream Loop
+终端与浏览器共享会话，可自由切换。活动的 CLI 会话中输入 `web` 也可启动 Web UI。
 
-Codemini 内置记忆工具和斜杠命令：
+更多 Web UI 选项（端口、项目目录、会话、模型等）通过 `--port`、`--project`、`--session`、`--model`、`--no-open` 等参数配置。
+
+**Souls**——改变 agent 语气的预设（`default`、`professional`、`ceo`、`playful`、`anime`、`caveman`、`pirate`），不影响执行策略。配置：`codemini config set soul.preset professional`。
+
+### 记忆、自我进化与 Dream Loop
+
+Codemini 的记忆系统设计为**从你的工作中学习**，而不仅仅是存储事实。
 
 | 命令 | 作用 |
 | --- | --- |
-| `/capture <summary>` | 捕获高信号观察到 inbox。 |
-| `/inbox` | 查看待整理记忆证据。 |
-| `/dream [--dry-run]` | 把 inbox 整理进长期/项目记忆。 |
-| `/reflect` | 把成功工作流沉淀成可审阅的 `SKILL.md` 草稿。 |
+| `/capture <summary>` | 将高信号观察记录到 inbox。 |
+| `/inbox` | 查看待整理的记忆素材。 |
+| `/dream [--dry-run]` | 将 inbox 整理到用户/全局/项目三层长期记忆。 |
+| `/reflect` | 将成功的工作流模式沉淀为可审阅的 `SKILL.md`——你的工具箱随工作进化。 |
 
-Inbox 是临时的、可能带噪的证据层；Dream consolidation 决定哪些内容值得晋升为长期记忆。
+Inbox 本质上是临时噪声层。Dream 循环决定哪些内容值得晋升。而 `/reflect` 完成了闭环：一个被你反复验证成功的工作模式，变成可复用的 skill，跟项目一起版本化管理。
 
-### 项目索引
+典型的 reflect 闭环：
 
-Codemini 会维护 `.codemini/` 轻量索引：
+```bash
+# 1. 完成一次效果很好的工作流后，让 Codemini 提炼可复用模式。
+/reflect 把刚才 provider tool-call 修复成功的链路沉淀成 skill
 
-| 文件 | 作用 |
-| --- | --- |
-| `.codemini/project-map.json` | 语言、源码目录、测试目录、入口候选和仓库事实。 |
-| `.codemini/file-index.json` | imports、exports、functions、classes 和 symbol 提示。 |
+# 2. 在 TUI/Web UI 中审阅生成的草稿。
+/yes
 
-进入项目时初始化，编辑/写入/patch 后增量刷新。
+# 3. Codemini 写入 .codemini/skills/provider-tool-call-recovery/SKILL.md
+#    并立即暴露为 slash skill。
+/provider-tool-call-recovery 把同类问题修到 Anthropic adapter
 
-### 可选增强
+# 4. 也可以从 shell 直接一次性启动这个 skill。
+codemini '/provider-tool-call-recovery 审计 provider message conversion'
+```
 
-FFF 搜索加速：
+如果这个工作流应该跨项目复用，可以写成全局 skill：
 
 ```bash
-codemini doctor
+/reflect --scope=global 把刚才的发布检查流程沉淀成可复用 skill
+codemini '/release-checklist 准备一次 patch release'
 ```
 
-如果 `fff-mcp` 在 `PATH` 中，Codemini 会自动用于更快的 `grep`、`glob` 和部分 `list`。缺失时自动回退内置搜索。
+### 项目索引与代码智能
 
-Playwright 网页渲染：
+Codemini 为每个项目构建轻量但精确的代码索引，核心使用 **Tree-sitter AST 解析**提取符号——而不是简单的正则或行数统计。
 
-```bash
-npm install -g playwright
-playwright install chromium
-```
+| 文件 | 内容 |
+| --- | --- |
+| `.codemini/project-map.json` | 语言、源码目录、测试目录、入口候选、仓库事实。 |
+| `.codemini/file-index.json` | 每个文件的 imports、exports、函数和类声明、接口、类型别名——基于语言感知的 AST 查询提取。 |
+
+索引为系统中的每个代码感知工具提供支持：
+
+- **`grep` 和 `glob`** 利用文件映射跳过无关目录（node_modules、构建产物、.git），操作前无需触碰文件系统。
+- **`ast_query` / `read_ast_node`** 将符号目标解析为精确的行列范围，实现手术刀式编辑，无需手动偏移计算。
+- **`read` 带 AST 上下文** 可在光标位置附近返回包裹的函数体或类定义。
+
+索引的 freshness 通过增量维护：每次 `edit`、`write` 或 `patch` 调用后，仅重新解析受影响的文件并替换其索引条目。无需每次变更都全量重建。
+
+语言支持覆盖 JavaScript、TypeScript、TSX、Python、Go、C、C++、Rust、Java、C#、PHP、Ruby 和 Bash——每种语言使用独立的 Tree-sitter 语法。
 
 ### 数据路径
 
@@ -430,9 +546,22 @@ playwright install chromium
 | 项目状态 | `.codemini/` |
 | 项目 Skills | `.codemini/skills/<name>/SKILL.md` |
 | 全局 Skills | `<base-config-dir>/skills/<name>/SKILL.md` |
-| Windows 配置 | `%APPDATA%\codemini-global\` |
-| macOS 配置 | `~/Library/Preferences/codemini-global` |
-| Linux/XDG 配置 | `$XDG_CONFIG_HOME/codemini-global` |
+| Windows | `%APPDATA%\codemini-global\` |
+| macOS | `~/Library/Preferences/codemini-global` |
+| Linux / XDG | `$XDG_CONFIG_HOME/codemini-global` |
+
+可通过 `CODEMINI_GLOBAL_DIR` 环境变量覆盖基础配置目录。
+
+### 可选增强
+
+**FFF 搜索加速：** `codemini doctor` 会检测 `fff-mcp` 是否在系统 PATH 中，若存在则自动用于加速 `grep`、`glob` 和部分 `list` 操作。未安装时自动回退内置搜索。
+
+**Playwright 渲染** 用于 JavaScript 重载页面：
+
+```bash
+npm install -g playwright
+playwright install chromium
+```
 
 ### 开发
 
@@ -442,7 +571,7 @@ npm test
 npm start
 ```
 
-构建 Web UI：
+构建 Web UI 生产包：
 
 ```bash
 npm run build:web
@@ -450,9 +579,9 @@ npm run build:web
 
 ### 文档
 
-- [OPERATIONS.md](./OPERATIONS.md) - 日常操作手册
-- [deployment.md](./deployment.md) - 打包、安装、部署
-- [Releases](https://github.com/havingautism/Codemini-CLI/releases) - 更新记录
+- [OPERATIONS.md](./OPERATIONS.md) — 日常操作手册
+- [deployment.md](./deployment.md) — 打包、安装、部署
+- [Releases](https://github.com/havingautism/Codemini-CLI/releases)
 
 ### 许可证