Codemini CLI

An extremely restrained coding + tasks CLI.
Every platform. Every terminal. Minimal by design.

English · 简体中文 · Web UI · Operator Guide · Deployment

---

English

What is Codemini?

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.

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.

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.

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.

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.

No SaaS. No telemetry. No mandatory registration.

Why "Restrained"?

Many coding agents pursue an ever-expanding surface — more tools, more context, more automation. Codemini takes the opposite approach.

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

It is not about delivering less capability. It is about eliminating what you should not have to carry.

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:

  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

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.

Codemini's restraint is architectural:

• 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

# 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

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.

# Interactive session (chat)
codemini "Summarize the recent Git history and write a CHANGELOG.md"

# One-off task
codemini run "Find all .env files in this repo and check for hardcoded secrets"

# Multi-role harness — planner + coder + reviewer in sequence
codemini run --harness coder "Refactor the auth module to extract middleware"

# Pipeline — sequential steps with artifact passing
codemini run --pipeline "Bump version, update CHANGELOG, and create a GitHub release draft"

Common non-coding task examples:

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

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

Skills are reusable, reviewable workflow recipes. Built-in:

Skill	When to use
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.

codemini skill list
codemini skill install <path>
codemini skill inspect <name>
codemini skill enable <name>
codemini skill disable <name>
codemini skill reindex

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.

Invoke any enabled skill as a slash command inside a session, or pass the slash command as a one-off prompt:

# Inside an interactive session
/grill-me review this release plan before I tag it
/writing-plans add OAuth refresh-token rotation

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

codemini --web

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's memory system is designed to learn from your work, not just store facts.

Command	Purpose
/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	Convert a successful workflow pattern into a reviewable SKILL.md — your toolset evolves as you work.

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.

Typical reflect loop:

# 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

# 2. Review the generated draft in the TUI/Web UI.
/yes

# 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

# 4. The same skill can also be launched directly from the shell.
codemini '/provider-tool-call-recovery audit provider message conversion'

Use --scope=global when the workflow should follow you across repositories:

/reflect --scope=global turn the release checklist I just used into a reusable skill
codemini '/release-checklist prepare a patch release'

Project Index & Code Intelligence

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.

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

Scope	Path
Global sessions	<base-config-dir>/sessions/
Project state	.codemini/
Project skills	.codemini/skills/<name>/SKILL.md
Global skills	<base-config-dir>/skills/<name>/SKILL.md
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:

npm install -g playwright
playwright install chromium

Development

npm install
npm test
npm start

Build the Web UI bundle for production:

npm run build:web

Documentation

• OPERATIONS.md — daily operations manual
• deployment.md — packaging, installation, deployment
• Releases

License

MIT

---

简体中文

Codemini 是什么？

一款刻意保持克制的 coding + tasks CLI。 不仅能写代码——Git 工作流自动化、DevOps 流水线、数据批量处理、系统诊断，它都能干。

兼容 Windows PowerShell、macOS zsh、Linux bash 等各种终端环境。兼容任何 OpenAI 兼容或 Anthropic 的 API，不绑定特定模型或提供商。提供双界面——基于 Ink + React 构建的终端 TUI 和浏览器 Web UI——共享同一引擎和会话。

支持大小模型协同工作：配置一个轻量模型处理路由和简单任务，一个大模型负责复杂推理，系统自动调度。

其他内置能力包括项目索引、持久记忆与 /reflect 自我进化、技能工作流、计划模式、审批机制，以及仅改变语气不改变行为的人格预设（Souls）。

无需 SaaS、无需遥测、无需注册。

「克制」体现在哪里？

当前多数 AI 编码工具的策略是做加法——不断堆叠工具、上下文、自动化能力。Codemini 选择了相反的方向。

• 依赖极简。 仅依赖少量精选的 npm 包。没有 Electron、Docker 或 Python 运行时。
• 上下文预算可控。 微压缩、工具结果溢出到磁盘、提示预检触发——为控制模型窗口使用而设计。
• 大小模型协同。 配置一个轻量模型处理路由和简单任务，一个大模型负责复杂推理，系统自动分派。
• 审批有度。 命令按意图分级：只读操作直接放行，破坏性操作暂停确认。阈值由你设定。
• 技能懒加载。 注册 1,000 个技能与注册 1 个的开销相同。只有被实际调用的技能才会进入提示上下文。
• 记忆择优而存，自我进化。 Inbox 本质上是临时草稿箱，Dream 循环决定晋升内容，/reflect 把成功工作流沉淀为可复用的 skill。

并非功能更少，而是不背负不必要的负担。

数据视角：「克制」的实际效果

一个真实项目的首轮 system prompt——包含 AGENTS.md、auto skill、记忆快照和项目上下文——大约消耗 5,300 tokens。具体构成如下：

  基础 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、每保存一条记忆、每编写一个规则文件，都会无条件注入。

Codemini 的克制源自架构设计：

• Skill 懒加载。 安装 10 个 skill 与安装 0 个，system prompt 开销相同。只有被命中的 skill 才会加载完整内容。
• 记忆有筛选。 Inbox 是临时噪声层，只有经过晋升的记忆才会进入提示上下文。你控制水位。
• 项目索引紧凑。 符号映射替代原始文件树。整个仓库仅需数百 token。
• 无隐藏负担。 没有遥测脚本、用量追踪，或未经你要求注入的上下文。

核心逻辑很简单：prompt 税越少，留给实际工作的预算就越多。

快速开始

# 全局安装
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 可以把任何自然语言任务变成自动化工作流——不需要写脚本。

# 交互式会话
codemini "查看最近的 Git 提交历史，生成一份 CHANGELOG.md"

# 一次性任务
codemini run "扫描项目中所有 .env 文件，检查是否有硬编码密钥"

# 多角色组合 — planner + coder + reviewer 接力
codemini run --harness coder "重构 auth 模块，抽离中间件"

# 流水线 — 多步骤任务，步骤间传递产物
codemini run --pipeline "升级版本号、更新 CHANGELOG、创建 GitHub release 草稿"

非编码任务举例如下：

任务	命令
系统诊断	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，但完全运行在你的机器上、使用你的模型、遵循你的审批策略。

功能速览

功能	说明
🧠 持久记忆	/capture → inbox → dream 整理 → 用户/全局/项目三层记忆。让 agent 记住项目上下文。
📂 项目索引	自动维护 .codemini/ 索引，记录语言、符号、导入导出关系。编辑后增量刷新。
🛠 技能系统	路由元数据与技能体分离。可自行编写 SKILL.md，也可使用内置工作流。
🔄 自我进化	/reflect 把成功工作流转化为可复用的 SKILL.md。你的工具箱随项目成长。
⚡ 大小模型协同	配置轻量模型做路由与简单任务，大模型做复杂推理，系统自动分派。
🖥 终端 TUI	富交互终端界面——旋转动画、语法高亮代码块、实时命令输出流、自动补全命令面板。
🕸 Web UI	浏览器界面，同一引擎。终端与浏览器共享会话，可随时切换。
🎭 Souls 人格	预设语气（专业、活泼、动漫、原始人……），只改变表达方式，不改变执行策略。
📋 计划模式	多步骤实施计划，包含文件路径与验证步骤，执行前需确认。
🔒 命令审批	按风险分级：只读操作直接放行，破坏性操作暂停确认。阈值可配置。
💾 会话检查点	随时保存、回退、分支会话状态。崩溃或模型异常不丢失上下文。
🌍 全平台支持	Windows PowerShell、macOS zsh、Linux bash——同一套配置，同一套行为。

Skills

Skills 是可复用、可审阅的工作流配方。内置：

Skill	适用场景
superpowers-lite	默认编码流程：先了解、必要时计划、小范围修改、验证后汇报。
grill-me	对方案、PR、发布、想法做压力测试，发现潜在问题。
brainstorm	多种方案难以抉择时，先比较选项再行动。
writing-plans	生成包含文件路径和验证步骤的实施计划。

codemini skill list
codemini skill install <path>
codemini skill inspect <name>
codemini skill enable <name>
codemini skill disable <name>
codemini skill reindex

路由元数据集中在顶层 catalog（codemini.skills.json），仅存储 description、mode、triggers、enabled、priority 等轻量字段。启动时不读取完整 SKILL.md，仅在被命中或显式调用时才加载。catalog 缺失时回退到目录和 frontmatter。

任何启用的 skill 都可以在会话里当作 slash command 调用，也可以作为一次性 prompt 从 shell 直接启动：

# 在交互式会话中
/grill-me 帮我审一遍这个发布方案再打 tag
/writing-plans 设计 OAuth refresh-token 轮换方案

# 从 shell 一次性调用
codemini '/brainstorm 比较 SQLite、Postgres 和 DuckDB 做本地分析的取舍'
codemini '/project-requirements 为当前仓库生成一份 CodeWiki 报告'

终端 TUI 与 Web UI

Codemini 提供双界面，由同一引擎驱动。

终端 TUI——富交互界面，支持长时间任务的旋转动画、语法高亮的代码块、实时命令输出流、以及带自动补全的命令面板。在任何终端模拟器中运行，无需额外进程。

Web UI——完整的浏览器界面，与会话状态实时同步：

codemini --web

终端与浏览器共享会话，可自由切换。活动的 CLI 会话中输入 web 也可启动 Web UI。

更多 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——你的工具箱随工作进化。

Inbox 本质上是临时噪声层。Dream 循环决定哪些内容值得晋升。而 /reflect 完成了闭环：一个被你反复验证成功的工作模式，变成可复用的 skill，跟项目一起版本化管理。

典型的 reflect 闭环：

# 1. 完成一次效果很好的工作流后，让 Codemini 提炼可复用模式。
/reflect 把刚才 provider tool-call 修复成功的链路沉淀成 skill

# 2. 在 TUI/Web UI 中审阅生成的草稿。
/yes

# 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'

如果这个工作流应该跨项目复用，可以写成全局 skill：

/reflect --scope=global 把刚才的发布检查流程沉淀成可复用 skill
codemini '/release-checklist 准备一次 patch release'

项目索引与代码智能

Codemini 为每个项目构建轻量但精确的代码索引，核心使用 Tree-sitter AST 解析提取符号——而不是简单的正则或行数统计。

文件	内容
.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 语法。

数据路径

范围	路径
全局会话	<base-config-dir>/sessions/
项目状态	.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

可通过 CODEMINI_GLOBAL_DIR 环境变量覆盖基础配置目录。

可选增强

FFF 搜索加速： codemini doctor 会检测 fff-mcp 是否在系统 PATH 中，若存在则自动用于加速 grep、glob 和部分 list 操作。未安装时自动回退内置搜索。

Playwright 渲染 用于 JavaScript 重载页面：

npm install -g playwright
playwright install chromium

开发

npm install
npm test
npm start

构建 Web UI 生产包：

npm run build:web

文档

• OPERATIONS.md — 日常操作手册
• deployment.md — 打包、安装、部署
• Releases

许可证

MIT