min-agent

一款在终端里运行的 AI 编程助手 · An AI coding agent that lives in your terminal

🌐 https://min-agent.lonae.com

⬇️ 请选择你的语言 / Please choose your language ⬇️

➡️ English　　➡️ 简体中文

🇬🇧 English

A minimal AI coding agent for your terminal. Works with OpenAI, Ollama, and any OpenAI-compatible provider.

🔝 Back to language selector · 🇨🇳 Switch to 简体中文

Get Started

npm install -g min-agent
min-agent setup       # pick a provider and model (interactive)
min-agent             # start chatting
min-agent models      # list the models your provider offers

min is available as a shorter alias with identical functionality (min "...", min serve, ...).

Usage

min-agent "your message"        # start a session and send a message (agent mode)
min-agent ask "your question"   # start in ask mode — web Q&A & search only
min-agent exec "your message"   # one-shot question, then exit
min-agent push                  # shortcut: git commit and push your changes
min-agent --resume <id>         # resume a previous session
min-agent history               # list saved sessions
min-agent -i photo.png "..."    # attach an image
min-agent -m gpt-5.5 "..."      # pick a model for one message
min-agent --provider anthropic "..."   # pick a provider for one message

Modes: agent (default) is the full coding agent — read/write files, run commands, manage config. ask is a separate web-Q&A mode with its own system prompt — only live search (search_web / web_fetch); it skips MCP, skills, rules, and memory. Use /ask / /agent in chat to switch (add --project to keep the choice local to this project). The choice is remembered: min-agent ask, or /ask in a session, means the next plain min-agent also starts in ask mode.

While Chatting

Type / to open the command menu; ↑/↓ selects. On an empty input, ↑/↓ recalls past messages.

| Command | What it does | |---|---| | /new · /sessions | New session · switch between sessions | | /model · /provider | Switch model / provider | | /ask · /agent | Switch to ask (web Q&A) / agent (coding) mode | | /plan | Plan mode — look, don't touch | | /think · /ctx | Thinking intensity · local-model context window | | /memory | Toggle memory or save a note | | /undo · /diff | Undo last turn · show changes so far | | /queue | List, drop or clear messages waiting behind the running turn | | /attach · /mcp · /skills | Attach an image · MCP servers · skills | | /tokens · /help | Usage, reuse & cost · all commands |

The input box stays live while the agent works: press Enter and the message joins a queue that runs in order once the current turn ends (the status bar and spinner show the backlog). Use /queue to inspect it, /queue rm <n> to pull one out, /queue clear to drop them all; Esc cancels the running turn and drops the queue.

Commands that only read state or write config — /permission, /sandbox, /memory, /plan, /ask, /agent, /reload, /rename, and the picker commands given an argument (/model <id>, /think low, /ctx 8k, …) — run immediately even mid-turn, so a permission change applies to the very next tool call instead of waiting behind the whole turn. Everything that mutates the conversation or opens an overlay queues like a message.

Shortcuts: Ctrl+C clears input (press twice to exit) · Shift+Enter / Ctrl+J inserts a newline · Ctrl+V pastes an image · Ctrl+B copies selected text · Ctrl+O expands the tool or thinking row in view · click a tool or thinking block to expand it.

Staying in Control

File edits are auto-approved by default; risky actions always ask. When several actions in one step need approval, they're combined into a single prompt instead of a stack of separate ones. Each prompt offers 允许 / 总是允许 / 拒绝 — choosing 总是允许 remembers that action for the current session, so repeated identical commands or MCP tools won't ask again.

min-agent exec (one-shot) runs more freely by default: edits and ordinary commands don't ask — only genuinely destructive commands (deleting files, dropping/truncating databases, disk-wiping, git reset --hard, etc.) still prompt. Pass --permission or --yes to override. Thinking and tool calls print as a single summary line each.

min-agent permission                 # show current setting
min-agent --permission ask           # confirm before risky actions
min-agent --permission accept-edits  # auto-approve file edits (default)
min-agent --permission allow-all     # auto-approve everything — use with care
min-agent sandbox workspace          # only allow changes inside this folder

On Windows, OS-level command isolation (macOS seatbelt / Linux bwrap) is unavailable: strict refuses shell commands; workspace still blocks file tools outside the folder. Shell commands prefer Git Bash when installed.

Off by default. Turn it on to keep facts across sessions:

min-agent memory on             # enable (writes config)
min-agent memory add "prefer bun"

In chat: /memory on|off toggles, /memory lists notes, /memory some text saves one.

Configuration

min-agent ships with a free preset OpenRouter provider (openrouter/free), so it works out of the box. Run min-agent setup any time to switch to your own provider:

min-agent setup        # add a provider (interactive; OpenAI / Ollama / any OpenAI-compatible endpoint)
min-agent provider     # show the active provider and any you've added
min-agent models       # list the models your provider offers

min-agent provider <name> switches the active provider (add/edit/remove go through min-agent setup).

Adding an OpenCode Go / OpenCode Zen endpoint (e.g. https://opencode.ai/zen/go/v1) is detected during setup, and every request then carries the x-opencode-session header that endpoint requires — one stable id per conversation. Use --opencode-session / --no-opencode-session to force it on or off (e.g. for a gateway that proxies OpenCode Go under another host).

The built-in OpenRouter preset (openrouter/free) is never written to disk. Set MIN_AGENT_BUILTIN_API_KEY to override it with a key of your own. While the preset is active it can't be edited or switched away from, but adding your own provider takes over automatically; MIN_AGENT_NO_BUILTIN_PROVIDER=1 disables it outright.

Settings live in ~/.min-agent/config.json (global). Per-project settings go to ~/.min-agent/sessions/<project-key>/config.json (auto-created; nothing is written inside the project directory).

Extending It

• MCP servers — connect external tools: min-agent mcp -h
• Skills — reusable instructions the agent loads on demand: min-agent skills -h
• Project rules — add AGENTS.md or RULES.md to your project; global rules go in ~/.min-agent/rules.md or ~/.min-agent/AGENTS.md

API Access

min-agent serve starts a local HTTP API for other apps to talk to. Reference: docs/API.md

License

MIT

🇨🇳 简体中文

一款可在终端里运行的极简 AI 编程助手，支持 OpenAI、Ollama 以及任何兼容 OpenAI 接口的服务商。

🔝 返回语言选择 · 🇬🇧 Switch to English

快速上手

npm install -g min-agent
min-agent setup       # 选择服务商与模型（交互式）
min-agent             # 开始对话
min-agent models      # 查看当前服务商可用的模型

min 是等价的短命令，功能完全相同（min "..."、min serve 等）。

基本用法

min-agent "你的消息"            # 进入交互会话并立即发送消息（agent 模式）
min-agent ask "你的问题"        # 以 ask 模式进入——仅联网问答与搜索
min-agent exec "你的消息"       # 单次提问后自动退出
min-agent push                  # 快捷指令：git 提交并推送代码
min-agent --resume <id>        # 恢复之前的会话
min-agent history              # 查看已保存的会话
min-agent -i photo.png "..."   # 为一条消息附带图片
min-agent -m gpt-5.5 "..."     # 为一条消息指定模型
min-agent --provider anthropic "..."   # 为一条消息指定服务商

会话模式：agent（默认）是完整编码智能体——读写文件、执行命令、管理配置；ask 是独立的联网问答模式，使用专门的系统提示词，仅保留联网搜索（search_web / web_fetch），不加载 MCP、skills、规则与记忆。对话中用 /ask / /agent 随时切换（加 --project 只对当前项目生效）。切换会被记住：min-agent ask 或在会话里 /ask 之后，下次直接运行 min-agent 也以 ask 模式启动。

对话中的操作

输入 / 弹出命令菜单，用 ↑/↓ 移动高亮；输入框为空时，↑/↓ 翻看之前消息。

| 命令 | 作用 | |---|---| | /new · /sessions | 新建会话 · 切换会话 | | /model · /provider | 切换模型 / 服务商 | | /ask · /agent | 切换 ask（联网问答）/ agent（编码）会话模式 | | /plan | 计划模式——只看不改 | | /think · /ctx | 思考强度 · 本地模型上下文窗口 | | /memory | 开关记忆，或保存一条 | | /undo · /diff | 撤销上一轮 · 查看已产生的改动 | | /queue | 查看、移出或清空排在当前任务后面的消息 | | /attach · /mcp · /skills | 附加图片 · MCP 服务 · 技能 | | /tokens · /help | 用量、复用与费用 · 全部命令 |

任务执行时输入框依然可用：按 Enter 会把消息排进队列，当前任务结束后按顺序执行（运行提示行显示排队数量）。/queue 查看队列，/queue rm <序号> 移出一条，/queue clear 全部清空；Esc 取消当前任务，并丢弃排队消息。

只读取状态或只写配置的命令——/permission、/sandbox、/memory、/plan、/ask、/agent、/reload、/rename，以及带参数的选择类命令（/model <id>、/think low、/ctx 8k 等）——在任务执行中也会立即执行：改完确认模式马上对下一次工具调用生效，不必等整轮结束。会改动对话内容或打开浮层的命令则和消息一样排队。

快捷键：Ctrl+C 清空输入（连按两次退出）· Shift+Enter / Ctrl+J 换行 · Ctrl+V 粘贴图片 · Ctrl+B 复制选中的文本 · Ctrl+O 展开视图中间的工具/思考行 · 点击工具或思考块可展开收起。

掌控风险

文件修改默认自动批准，危险操作仍会询问；同一步里有多个操作需要授权时，会合并成一个弹窗逐条列出，而不是弹出一堆。弹窗提供 允许 / 总是允许 / 拒绝 三个选项——选「总是允许」会在本次会话内记住该操作，之后重复的相同命令或 MCP 工具不再询问。

min-agent exec（单次执行）默认更放手：文件修改和普通命令都不询问，只有真正具破坏性的命令（删除文件、drop/truncate 数据库、抹盘、git reset --hard 等）才会询问。加 --permission 或 --yes 可覆盖此默认。思考过程和工具调用各占一行摘要，不展开全文。

min-agent permission                 # 查看当前设置
min-agent --permission ask           # 有风险操作前先询问
min-agent --permission accept-edits  # 仅自动批准文件修改（默认）
min-agent --permission allow-all     # 自动批准所有操作——请谨慎使用
min-agent sandbox workspace          # 仅允许修改当前文件夹内内容

Windows 上没有 macOS/Linux 那种命令级隔离：strict 会拒绝执行 shell；workspace 仍会限制文件工具写到目录外。装了 Git Bash 时优先用它跑命令。

记忆

默认关闭。想让偏好跨会话保留时再打开：

min-agent memory on             # 开启记忆（写入配置）
min-agent memory add "prefer bun"

对话里用 /memory on|off 开关，/memory 查看，/memory 一段话 保存一条。

配置

min-agent 不附带任何密钥，首次运行会引导你走 min-agent setup：

min-agent setup      # 添加服务商（交互式；OpenAI / Ollama / 任意 OpenAI 兼容接口）
min-agent provider   # 查看当前服务商，以及你已添加的服务商
min-agent models     # 查看当前服务商可用的模型

min-agent provider <name> 切换当前服务商（增、删、改走 min-agent setup）。

添加 OpenCode Go / OpenCode Zen 接口（如 https://opencode.ai/zen/go/v1）时会自动识别，之后每次调用都会带上该接口要求的 x-opencode-session 头，同一会话固定一个 id。用 --opencode-session / --no-opencode-session 可强制开启或关闭（例如换了域名的自建网关）。

min-agent 内置一个免费的 OpenRouter 预设（openrouter/free），开箱即用，该预设不会写入配置文件。如果要换成自己的 key，设置 MIN_AGENT_BUILTIN_API_KEY 即可覆盖默认 key。预设生效期间不可编辑、不可切换或删除，但添加自己的服务商后会自动接管；MIN_AGENT_NO_BUILTIN_PROVIDER=1 可彻底关闭预设。

配置保存在 ~/.min-agent/config.json（全局生效）。项目级配置保存在 ~/.min-agent/sessions/<project-key>/config.json（自动创建，不会在项目目录里生成任何文件），仅对该项目生效。

扩展能力

• MCP 服务：连接外部工具与数据源，min-agent mcp -h
• 技能（Skills）：由 agent 按需加载的可复用指令集，min-agent skills -h
• 项目规则：在项目里添加 AGENTS.md 或 RULES.md；全局规则写入 ~/.min-agent/rules.md 或 ~/.min-agent/AGENTS.md

API 接入

min-agent serve 可启动本地 HTTP API 服务，供其他应用调用。完整说明见 docs/API.md

网页版

min-agent web

启动 HTTP API 并附带网页版对话助手（默认 http://127.0.0.1:8787），浏览器打开即用，无需 CORS 或令牌配置。网页版支持：

• 流式对话、思考过程与工具调用展示、图片粘贴/上传
• 会话模式切换：agent（完整编码智能体）/ ask（仅联网问答与搜索）
• 工作目录切换：顶栏目录菜单直接切换项目目录（记住后下次启动自动进入）
• 会话管理：历史列表、重命名、删除、撤销最后一轮、压缩历史
• 设置页（完整覆盖 CLI 配置，无需命令行即可修改）：
  • 服务商：添加/编辑/删除/切换，含 API Key、类型与上下文窗口
  • 模型：默认模型（全局/项目作用域）、本次会话模型、Ollama 上下文档位
  • Skills：启用/禁用（全局/项目）、查看详情、新建、重新扫描、孤儿引用清理
  • MCP：添加/编辑/删除、启用/禁用、连接状态与工具列表
  • 记忆：开关、条目增删与搜索、全局/项目作用域
  • 规则：全局与项目规则文件在线编辑，保存即刻生效
  • 行为与隔离：思考强度、确认模式、沙箱级别/联网/目录白名单
• 危险操作确认与代理提问的交互回复（开启输入框的「确认」模式）
• 明暗主题、移动端适配

--host / --port 与 serve 相同。产物缺失时先在仓库内执行 bun run build:web（npm 发布包已内置），或用 MIN_AGENT_WEB_DIST 指定产物目录。

后台运行与停止：

min-agent web -d       # 后台运行（日志: ~/.min-agent/serve.log）
min-agent web --status # 查看后台服务运行状态
min-agent web --stop   # 停止后台服务

License

MIT