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             # start chatting (built-in OpenRouter model, preset)
min-agent models      # list models (always openrouter/free)

Usage

min-agent "your message"        # start a session and send a message
min-agent exec "your message"   # one-shot question, then exit
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

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 | | /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 | | /attach · /mcp · /skills | Attach an image · MCP servers · skills | | /tokens · /help | Usage & cost · all commands |

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

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

No setup needed — the built-in OpenRouter provider (openrouter/free) is preset:

min-agent models       # lists openrouter/free while the preset is active
min-agent provider     # show the active provider and any you've added
min-agent setup        # add your own provider (interactive)

The preset itself can't be edited or switched away from, but you can always add your own provider — once you add one it takes over automatically. min-agent provider <name> switches the active provider (add/edit/remove go through min-agent setup). Set MIN_AGENT_NO_BUILTIN_PROVIDER=1 to disable the preset entirely.

Settings live in ~/.min-agent/config.json (global). For per-project settings, run min-agent init to create .min-agent/config.json.

Extending It

• MCP servers — connect external tools: min-agent mcp -h
• Skills — reusable instructions loaded automatically: min-agent skills -h
• Project rules — add AGENTS.md or RULES.md to your project; global rules go in ~/.min-agent/rules.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             # 开始对话（内置 OpenRouter 模型，已预设）
min-agent models      # 查看模型（始终为 openrouter/free）

基本用法

min-agent "你的消息"            # 进入交互会话并立即发送消息
min-agent exec "你的消息"       # 单次提问后自动退出
min-agent --resume <id>        # 恢复之前的会话
min-agent history              # 查看已保存的会话
min-agent -i photo.png "..."   # 为一条消息附带图片
min-agent -m gpt-5.5 "..."     # 为一条消息指定模型
min-agent --provider anthropic "..."   # 为一条消息指定服务商

对话中的操作

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

| 命令 | 作用 | |---|---| | /new · /sessions | 新建会话 · 切换会话 | | /model · /provider | 切换模型 / 服务商 | | /plan | 计划模式——只看不改 | | /think · /ctx | 思考强度 · 本地模型上下文窗口 | | /memory | 开关记忆，或保存一条 | | /undo · /diff | 撤销上一轮 · 查看已产生的改动 | | /attach · /mcp · /skills | 附加图片 · MCP 服务 · 技能 | | /tokens · /help | 用量与费用 · 全部命令 |

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

掌控风险

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

配置

无需配置即可使用——内置 OpenRouter 服务商（openrouter/free）已预设：

min-agent models     # 预设生效期间始终只列出: openrouter/free
min-agent provider   # 查看当前服务商，以及你已添加的服务商
min-agent setup      # 添加自己的服务商（交互式）

预设本身不可编辑，也不能切换或删除，但你随时可以添加自己的服务商——添加后它会自动接管。min-agent provider <name> 切换当前服务商（增、删、改走 min-agent setup）。设置 MIN_AGENT_NO_BUILTIN_PROVIDER=1 可彻底关闭预设。

配置保存在 ~/.min-agent/config.json（全局生效）。项目级配置用 min-agent init 创建 .min-agent/config.json，仅对该项目生效。

扩展能力

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

API 接入

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

License

MIT