MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

MinAgent

A production-grade AI agent CLI built with Bun, React 19, and Ink 7. Universal model support, powerful tools, and a terminal-native UX that rivals proprietary solutions.

一个基于 Bun、React 19 和 Ink 7 构建的生产级 AI Agent CLI。支持任何大模型、拥有丰富的工具集、以及媲美商业产品的终端原生体验。

Features / 特性

Universal Model Support / 通用模型支持
Works with any OpenAI-compatible API endpoint: OpenAI, Anthropic, Gemini, Azure, DeepSeek, Ollama, vLLM, and more. No hardcoded defaults — you control the provider.
兼容任何 OpenAI-compatible API 端点：OpenAI、Anthropic、Gemini、Azure、DeepSeek、Ollama、vLLM 等。无硬编码默认模型，完全由用户配置。
26 Built-in Tools / 26 个内置工具 File read/write/edit, grep, glob, tree, bash execution, web fetch/search, sub-agents, code execution (Python/Node/Bash), todo tracking, skill management, and more. 文件读写编辑、代码搜索、文件查找、目录树、Shell 执行、网页抓取/搜索、子 Agent、代码执行（Python/Node/Bash）、待办追踪、Skill 管理等。
Smart Permission System / 智能权限系统
5 modes: default, plan, acceptEdits, bypassPermissions, dontAsk. Destructive tools require confirmation by default.
5 种模式：default、plan、acceptEdits、bypassPermissions、dontAsk。默认情况下破坏性操作需要确认。
Terminal-First UX / 终端原生体验
Built with React + Ink for a rich terminal UI: streaming responses, tool call visualization, reasoning display, command autocomplete, input history, and plan mode batch approval.
基于 React + Ink 构建的丰富终端 UI：流式响应、工具调用可视化、推理过程显示、命令自动补全、输入历史、批量审批模式。
GitHub Integration / GitHub 集成
Native commands for PRs, issues, branches, commits, and more via gh CLI.
通过 gh CLI 原生支持 PR、Issue、分支、提交等操作。
Session Management / 会话管理
Persistent sessions, auto-compaction, context file management, @mention auto-loading, and cost tracking.
持久化会话、自动压缩、上下文文件管理、@mention 自动加载、成本追踪。
Skills System / Skill 系统 Built-in TypeScript skills plus Markdown SKILL.md skills with progressive disclosure, turn/session scopes, supporting files, pinning, and background curation. 支持内置 TypeScript Skill，也支持基于 Markdown SKILL.md 的渐进式 Skill：可按轮次或会话保持作用域，支持引用文件、固定与后台整理。
Production-Ready / 生产就绪
Zero TypeScript errors (strict mode), LLM error classification with smart retry, workspace auto-detection, and test framework auto-discovery.
TypeScript 严格模式零错误、LLM 错误分类与智能重试、工作区自动检测、测试框架自动发现。

Quick Start / 快速开始

1. Install Bun / 安装 Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install / 克隆并安装

git clone https://github.com/BruceL017/minagent.git
cd minagent
bun install

3. Configure / 配置

Set your API key and model via environment variables:
通过环境变量配置 API Key 和模型：

export MINA_PROVIDER="generic"# openai | anthropic | genericexport MINA_API_KEY="..."# Your API key / 你的 API 密钥export MINA_MODEL="..."# Model name / 模型名称export MINA_BASE_URL="..."# Custom API endpoint / 自定义 API 端点

Or use persistent config (stored in ~/.minagent/config.json):
或使用持久化配置（存储在 ~/.minagent/config.json）：

bun run src/main.tsx
/config MINA_PROVIDER generic
/config MINA_API_KEY ...
/config MINA_MODEL ...
/config MINA_BASE_URL ...

4. Run / 运行

bun run src/main.tsx
# or / 或
bun start

开发调试用热重载：

bun --hot run src/main.tsx

5. Permission Modes / 权限模式（可选）

export MINA_PERMISSION_MODE=default # 默认：破坏性工具需确认export MINA_PERMISSION_MODE=acceptEdits # 自动接受文件编辑，bash 仍需确认export MINA_PERMISSION_MODE=bypassPermissions # 跳过所有确认（危险）export MINA_PERMISSION_MODE=dontAsk # 从不询问（危险）

6. Common Commands / 常用命令速查

命令	作用
`/quit/exit`	退出并保存会话
`/help`	查看所有命令
`/plan`	进入批量审批模式
`/act`	退出 plan 模式
`/clear`	清空当前会话
`/config KEY VALUE`	修改配置
`/permissions`	查看当前权限模式
`/skills`	查看可用 skills
`/<skill-name>`	调用 v1/v2 skill
`/default`	退出当前 skill 模式
`/add <file>`	添加文件到上下文
`/changes`	查看本次会话修改的文件

7. Exit / 退出

正常退出：输入 /quit 或 /exit
强制退出：按 Ctrl + C
进程卡死：另开终端执行 pkill -f "bun run src/main.tsx"

Configuration / 配置项

Variable	Description	Required
`MINA_API_KEY`	API key for your LLM provider	Yes
`MINA_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-6`, `llama3.1:8b`)	Yes
`MINA_PROVIDER`	Provider type: `generic` (default), `openai`, `anthropic`	No
`MINA_BASE_URL`	Custom API base URL	No
`MINA_CONTEXT_WINDOW`	Context window size (default: 128000)	No
`MINA_PERMISSION_MODE`	Permission mode: `default`, `plan`, `acceptEdits`, `bypassPermissions`, `dontAsk`	No
`MINA_REASONING`	Enable reasoning display (`true`/`false`)	No
`MINA_THEME`	UI theme	No
`MINA_TRUST_LOCAL_SKILLS`	Trust and load repo-local v1 TypeScript `./skills` modules (`true`/`false`, default `false`). User-created v2 `SKILL.md` skills live under `~/.minagent/skills`.	No

Commands / 命令

Type / followed by a command name. Use Tab for autocomplete.

输入 / + 命令名。按 Tab 自动补全。

Git / 版本控制

/status, /diff, /log, /commit, /branch, /checkout, /push, /pull, /merge, /rebase, /cherry-pick, /blame, /stash, /stash-pop, /stash-list

GitHub

/pr, /pr-view, /pr-create, /issue, /issue-view, /repo

Session / 会话

/clear, /compact, /resume, /tokens, /cost, /sessions

Context / 上下文

/add <file>, /drop <file>, /context

System / 系统

/doctor, /config, /env, /model, /permissions, /plan, /act, /skills, /theme, /help, /quit

Skills / Skill

/skills lists v1 and v2 skills. Invoke a skill with /<skill-name>; v2 skills are loaded from ~/.minagent/skills and can include supporting files under references/, templates/, scripts/, or assets/. Use /default to exit active skill scopes.

Project / 项目

/test [pattern] — auto-detect and run tests / 自动检测并运行测试
/format — auto-format code / 自动格式化代码
/changes — show files changed this session / 显示本次会话修改的文件
/diff — show detailed diff of session changes / 显示会话变更的详细 diff

Architecture / 架构

src/
main.tsx # Entry point / 入口
config.ts # Configuration loader / 配置加载
types.ts # Shared types / 共享类型
agent/
index.ts # Core agent loop / 核心 Agent 循环
llm.ts # LLM client (OpenAI + Anthropic + Generic) / LLM 客户端
toolExecutor.ts # Smart concurrent tool execution / 智能并发工具执行
tools/ # 26 built-in tools / 26 个内置工具
commands/ # 40+ slash commands / 40+ 个斜杠命令
components/ # React + Ink UI / React + Ink UI 组件
utils/ # Context, compaction, cost tracking, permissions / 工具库
skills/ # v1 TypeScript skills / v1 TypeScript Skill
skills-v2/ # Markdown SKILL.md system / Markdown SKILL.md 系统
state/ # Session persistence / 会话持久化

License / 许可证

MIT

Name		Name	Last commit message	Last commit date
skills		skills
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Name		Name	Last commit message	Last commit date
skills		skills
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Name		Name	Last commit message	Last commit date
skills		skills
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Name		Name	Last commit message	Last commit date
skills		skills
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Name		Name	Last commit message	Last commit date
skills		skills
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

MinAgent

Features / 特性

Quick Start / 快速开始

1. Install Bun / 安装 Bun

2. Clone & Install / 克隆并安装

3. Configure / 配置

4. Run / 运行

5. Permission Modes / 权限模式（可选）

6. Common Commands / 常用命令速查

7. Exit / 退出

Configuration / 配置项

Commands / 命令

Git / 版本控制

GitHub

Session / 会话

Context / 上下文

System / 系统

Skills / Skill

Project / 项目

Architecture / 架构

License / 许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

MinAgent

Features / 特性

Quick Start / 快速开始

1. Install Bun / 安装 Bun

2. Clone & Install / 克隆并安装

3. Configure / 配置

4. Run / 运行

5. Permission Modes / 权限模式（可选）

6. Common Commands / 常用命令速查

7. Exit / 退出

Configuration / 配置项

Commands / 命令

Git / 版本控制

GitHub

Session / 会话

Context / 上下文

System / 系统

Skills / Skill

Project / 项目

Architecture / 架构

License / 许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

MinAgent

Features / 特性

Quick Start / 快速开始

1. Install Bun / 安装 Bun

2. Clone & Install / 克隆并安装

3. Configure / 配置

4. Run / 运行

5. Permission Modes / 权限模式（可选）