<div align="center">

<h1>⚡ AgentBoost</h1>

**Make your coding agent plan better, remember more, verify its own work, and stay safe — in under 5 minutes.**

A thin, pluggable enhancement layer for the agents you already use.<br/>
_One MCP server · a clean CLI · a local dashboard._

<p>
  <a href="https://github.com/codeman008/agentboost/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/codeman008/agentboost/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
  <img alt="Node" src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg" />
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6.svg" />
  <img alt="MCP" src="https://img.shields.io/badge/protocol-MCP-8a2be2.svg" />
  <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-ff69b4.svg" />
</p>

<p>
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-features">Features</a> ·
  <a href="#-how-it-works">How it works</a> ·
  <a href="#-mcp-tools">Tools</a> ·
  <a href="docs/guide.md">Full Guide</a> ·
  <a href="#-中文简介">中文</a>
</p>

</div>

---

## Why AgentBoost?

Coding agents are powerful but unreliable in predictable ways: they **go off-track**, **over-engineer**, **lose context** between sessions, **plan weakly**, and occasionally run something **dangerous**. Most fixes mean adopting a heavy new platform.

AgentBoost takes the opposite bet. It's a **thin layer** that plugs into your existing agent and does five things well:

> **The agent keeps thinking. AgentBoost gives it structure, memory, guardrails, and feedback** — all stored in a plain `.agentboost/` folder you can read, diff, and edit.

- 🔌 **No lock-in** — works with Claude Code, Cursor, OpenCode, Codex, and any MCP client
- 🔑 **No API keys, no cloud** — your agent does the reasoning; data never leaves your machine
- ⏱️ **Useful in 5 minutes** — one command to init, one to connect, one to open the dashboard

## ✨ Features

| | Feature | What it does |
|---|---|---|
| 🧭 | **Structured Planning** | Turn a natural-language goal into a clean Spec + small, individually verifiable steps. Refine iteratively; track per-step status. |
| 🧠 | **Context & Memory** | Persistent project memory — decisions, architecture, preferences, and hard-won learnings. Keyword search, importance-aware pruning, one-call context injection. |
| ✅ | **Automatic Verification** | Auto-detects your test / typecheck / lint / build commands (npm, tsc, pytest, go, cargo, make), runs them, and returns clear pass/fail to drive fix loops. |
| 🛡️ | **Safety & Permissions** | Three permission levels + dangerous-op detection (`rm -rf`, `git push --force`, `DROP TABLE`, `DELETE` without `WHERE`…) with human-confirmation gates and an audit log. |
| 🧩 | **Parallel Sub-agents** | A bounded, concurrency-capped task runner with simple result aggregation for fan-out work. |
| 📊 | **Local Web Dashboard** | See the current phase, plan progress, memory, verification results, and a live activity log — edit memory and permissions right from the browser. |

## 📸 Dashboard

`agentboost gui` opens a clean, localhost-only dashboard that shows everything at a glance:

```
┌────────────────────────────────────────────────────────────────┐
│ ⚡ AgentBoost   my-project          [ executing ]  Permission ▾  ↻│
├────────────────────────────────┬───────────────────────────────┤
│ Current Plan                   │ Verification        [Run checks]│
│  Ship search feature           │  ✅ test    npm run test        │
│  ▓▓▓▓▓▓▓░░░  3/5 done           │  ✅ lint    npm run lint        │
│  [x] Add DB index              │  ❌ build   npm run build       │
│  [~] Wire /search API          ├───────────────────────────────┤
│  [ ] Add integration tests     │ Project Memory          [+ Add]│
├────────────────────────────────┤  [decision]     Use SQLite     │
│ Safety Check                   │  [architecture] REST, not gRPC  │
│  > rm -rf build/   ⛔ critical   │  [preference]   2-space indent  │
└────────────────────────────────┴───────────────────────────────┘
```

> 💡 Real screenshots/GIFs belong in [`docs/screenshots/`](docs/screenshots/) — run the dashboard against [`examples/demo-project`](examples/demo-project) to capture them.

## 🚀 Quick Start

```bash
# 1 · Initialize AgentBoost in your project (creates .agentboost/)
npx agentboost init

# 2 · Open the dashboard
npx agentboost gui

# 3 · Print the MCP config for your agent
npx agentboost adapters
```

**Connect Claude Code** — drop this into `.mcp.json` at your project root and restart:

```json
{
  "mcpServers": {
    "agentboost": {
      "command": "npx",
      "args": ["-y", "agentboost", "mcp"],
      "env": { "AGENTBOOST_ROOT": "." }
    }
  }
}
```

Then just tell your agent: *"Plan this with AgentBoost first."* It calls `plan_start` → `plan_create`, records decisions with `memory_add`, runs `verify_run` after changes, and checks risky commands with `safety_check` — all visible live in the dashboard.

👉 **Full walkthrough** (install, every agent, examples, troubleshooting): **[docs/guide.md](docs/guide.md)**

## 🔌 Supported agents

| Agent | Integration | Config |
|---|---|---|
| **Claude Code** | MCP server | [`adapters/claude-code`](adapters/claude-code) → `.mcp.json` |
| **Cursor** | MCP server | [`adapters/cursor`](adapters/cursor) → `.cursor/mcp.json` |
| **OpenCode / Codex** | MCP server | [`adapters/opencode`](adapters/opencode) |
| **Any MCP client** | stdio MCP | `npx -y agentboost mcp` |
| **No agent (CLI)** | terminal | every feature works standalone |

## 🛠️ How it works

```
                    ┌─────────────────────────────┐
   your agent  ────▶│     AgentBoost MCP server    │
   (Claude/…)       │  plan · memory · verify ·    │
                    │  safety · status             │
                    └──────────────┬──────────────┘
   you ──▶ CLI  ───────────────────┤   one shared core
   you ──▶ GUI  ───────────────────┘        │
                                             ▼
                              .agentboost/  (plain files)
             config.yaml · memory.json · plans/ · state.json · audit.log
```

The MCP server, CLI, and dashboard are **three faces of one core**, reading and writing a single plain-file data directory. Nothing is hidden — inspect it, diff it in git, or hand-edit it.

## 🧰 MCP tools

The agent-facing surface is 13 focused tools:

| Category | Tools |
|---|---|
| **Planning** | `plan_start` · `plan_create` · `plan_refine` · `plan_set_step_status` · `plan_get` |
| **Memory** | `memory_add` · `memory_search` · `memory_context` · `memory_edit` |
| **Verification** | `verify_run` |
| **Safety** | `safety_check` · `safety_set_level` |
| **Status** | `status` |

## 📂 Project structure

```
agentboost/
├── src/
│   ├── core/      planning · memory · verification · safety · audit · sub-agents · facade
│   ├── mcp/       MCP server (primary agent integration)
│   ├── gui/       local dashboard: http server + static SPA (no build step)
│   └── cli/       command-line tool
├── adapters/      Claude Code · Cursor · OpenCode config templates
├── examples/      runnable demo project
├── docs/          bilingual operation guide + screenshots
└── test/          node --test suite
```

## 📦 Install

Zero-install via `npx agentboost <command>`, or install globally:

```bash
npm install -g agentboost
```

**Requirements:** Node.js ≥ 18. Minimal dependencies — MCP SDK, commander, yaml, zod.

## 🧪 Development

```bash
npm install
npm run build          # compile TS + copy static assets to dist/
npm test               # run the test suite (node --test)
npm run dev -- status  # run the CLI from source via tsx
```

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## 🗺️ Roadmap

- [ ] Real dashboard screenshots & a short demo GIF
- [ ] `plan_start` templates for common task types (bugfix, feature, refactor)
- [ ] Richer verification (coverage thresholds, custom gates)
- [ ] Optional standing-context sync with `AGENTS.md` / `CLAUDE.md`
- [ ] Publish to npm

## 📄 License

[MIT](LICENSE) © AgentBoost contributors

---

<div align="center">

## 🀄 中文简介

</div>

**AgentBoost** 是一个轻量、可插拔的增强层,让你现有的编码 Agent(Claude Code、Cursor、OpenCode、Codex)**规划更清晰、记忆更持久、能自动验证、操作更安全**。

它不是又一个庞大的 Agent 平台,而是一层薄薄的增强:**Agent 负责思考,AgentBoost 负责提供结构(计划)、持久化(记忆)、护栏(安全)和反馈(验证)** —— 全部存放在项目里可读、可 diff、可手改的 `.agentboost/` 纯文本目录。

- 🔌 **无锁定**:兼容 Claude Code、Cursor、OpenCode、Codex 及任何 MCP 客户端
- 🔑 **无需 API key、无需联网**:推理交给你的 Agent,数据不出本机
- ⏱️ **五分钟见效**:一条命令初始化,一条接入,一条打开面板

### 核心功能

| | 功能 | 说明 |
|---|---|---|
| 🧭 | **结构化规划** | 把自然语言目标拆成清晰的 Spec + 可逐条验证的小步骤,支持迭代细化与进度跟踪 |
| 🧠 | **上下文与记忆** | 持久化项目记忆(决策/架构/偏好/经验),关键词搜索、按重要度智能修剪、一键上下文注入 |
| ✅ | **自动验证** | 自动识别并运行测试 / 类型检查 / lint / 构建,给出清晰通过/失败,驱动修复循环 |
| 🛡️ | **安全与权限** | 只读 / 有限写入 / 完全访问 三级权限 + 危险操作检测(`rm -rf`、强推、`DROP TABLE` 等)+ 人工确认 + 审计日志 |
| 🧩 | **并行子 Agent** | 有并发上限的任务执行器 + 结果聚合 |
| 📊 | **本地 Web 面板** | 实时查看阶段、计划进度、记忆、验证结果与操作日志,可在浏览器里直接编辑 |

### 三分钟上手

```bash
npx agentboost init      # 在项目里初始化(生成 .agentboost/)
npx agentboost gui       # 打开本地面板
npx agentboost adapters  # 打印你所用 Agent 的 MCP 接入配置
```

详细中文操作指南(中英双语)见 **[docs/guide.md](docs/guide.md)**。