AgentBoost Operation Guide

A complete, beginner-friendly walkthrough. English first, 中文在后半部分。

1. Installation
2. Initialize a project
3. Connect your agent
4. Planning a task
5. Managing memory
6. Verification
7. Safety & permissions
8. The dashboard
9. CLI reference
10. Configuration
11. Troubleshooting
中文操作指南

1. Installation

Requirements: Node.js ≥ 18.

You don't have to install anything — npx agentboost <command> works out of the box. For a permanent install:

npm install -g agentboost
agentboost --version

2. Initialize a project

From your project root:

cd my-project
npx agentboost init          # or: agentboost init -n "My Project"

This creates a .agentboost/ directory:

.agentboost/
├── config.yaml   # settings (permission level, verification, limits) — safe to hand-edit
├── memory.json   # project memory entries
├── plans/        # <plan-id>.json + <plan-id>.md for each plan
├── state.json    # current phase + active plan
└── audit.log     # append-only action log

Commit .agentboost/ if you want the whole team to share memory and plans, or add it to .gitignore to keep it local. Your call.

3. Connect your agent

AgentBoost's primary integration is an MCP server. Print the snippet for your tool:

npx agentboost adapters

Claude Code

Create .mcp.json in your project root (template in adapters/claude-code/.mcp.json):

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

Restart Claude Code. Then add the workflow guidance to your CLAUDE.md (see adapters/claude-code/README.md) so the agent uses AgentBoost automatically.

Cursor

Put the same shape in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), then enable the server in Settings → MCP. See adapters/cursor/.

OpenCode / Codex / other MCP agents

Any MCP-capable agent can use the server. See adapters/opencode/README.md. The universal command is npx -y agentboost mcp with AGENTBOOST_ROOT set to your project path.

4. Planning a task

With an agent, just ask it to plan first. Under the hood it calls:

plan_start { goal } → returns planning guidance + relevant memory.
plan_create { goal, spec, steps } → persists the plan, sets phase to executing.
plan_set_step_status { planId, stepId, status } → as it works.
plan_refine { id, spec?, steps? } → when the plan needs to change.

From the CLI:

agentboost plan list
agentboost plan show          # active plan as Markdown
agentboost plan show <id>

Plans are stored as readable Markdown in .agentboost/plans/<id>.md — open them in any editor. A good plan has 4–8 small steps, each with a way to verify it.

5. Managing memory

Memory keeps durable project knowledge so the agent doesn't relearn (or re-break) things. Four types: decision, architecture, preference, learning.

With an agent: memory_search at the start of a task, memory_add when a decision is made, memory_context to pull a compact block into context.

From the CLI:

agentboost memory add -t decision -T "Use SQLite" -c "Chose SQLite over Postgres for simplicity" --tags db
agentboost memory list
agentboost memory search sqlite
agentboost memory rm <id>

In the dashboard: view, add, edit, and delete entries visually.

Memory is bounded by memoryLimit (default 200). When exceeded, low-importance older entries are pruned first; entries with importance ≥ 4 are always kept.

6. Verification

After major changes, run verification. AgentBoost auto-detects commands from your project (npm scripts, tsc, pytest, go, cargo, make) or uses ones you configure.

With an agent: verify_run → returns per-check pass/fail + failing output, so the agent can fix and re-run.

From the CLI:

agentboost verify

Example output:

✅ test: npm run test --silent (exit 0, 709ms)
✅ lint: npm run lint --silent (exit 0, 331ms)
❌ build: npm run build --silent (exit 1, 120ms)
    <captured error output>

To pin exact commands, edit verification in config.yaml (see §10).

7. Safety & permissions

Three permission levels:

Level	Reads	File writes	Shell commands
`read-only`	✅	⛔	⛔
`limited-write`	✅	✅	⚠️ confirm
`full-access`	✅	✅	✅ (dangerous ones still flagged)

On top of levels, dangerous-operation detection scans shell commands for patterns like rm -rf, git push --force, DROP TABLE, DELETE without WHERE, piping curl to a shell, sudo, npm publish, and more — flagging each with a risk level and (when confirmHighRisk is on) requiring confirmation.

With an agent: call safety_check { kind, target } before running a risky command; safety_set_level { level } to change the level.

From the CLI:

agentboost safety level                 # show current level
agentboost safety level full-access     # set level
agentboost safety check "rm -rf build"  # evaluate a command (exit 1 if blocked)

8. The dashboard

agentboost gui            # opens http://127.0.0.1:4477
agentboost gui -p 5000    # custom port
agentboost gui --no-open  # don't auto-open the browser

The dashboard (localhost-only) shows:

Phase badge — Planning / Executing / Verifying
Current plan with a progress bar; click a step's status chip to cycle it
Verification — run checks and see results inline
Memory — search, add, edit, delete
Safety check — test any command against the current level
Activity log — recent actions from the agent, CLI, and GUI

It auto-refreshes every few seconds, so agent activity appears live.

9. CLI reference

agentboost init [-n name]              Initialize .agentboost/ in the project
agentboost status                      Phase, active plan, permission, memory count
agentboost plan list                   List plans
agentboost plan show [id]              Show a plan (defaults to active) as Markdown
agentboost memory list                 List memory entries
agentboost memory add -t -T -c [...]   Add a memory entry
agentboost memory search <query>       Search memory
agentboost memory rm <id>              Delete a memory entry
agentboost verify                      Run verification checks
agentboost safety level [level]        Get/set permission level
agentboost safety check <command...>   Evaluate a shell command
agentboost log [-n lines]              Show the audit log
agentboost gui [-p port] [--no-open]   Launch the dashboard
agentboost mcp                         Run the MCP server (stdio)
agentboost adapters                    Print agent integration snippets

10. Configuration

.agentboost/config.yaml — safe to hand-edit; invalid values fall back to defaults.

project: my-project
permission: limited-write          # read-only | limited-write | full-access
confirmHighRisk: true              # require confirmation for high/critical ops
memoryLimit: 200                   # max memory entries before pruning
maxParallel: 3                     # sub-agent concurrency cap
guiPort: 4477
verification:                      # leave empty to auto-detect
  - kind: test
    command: npm test
  - kind: typecheck
    command: npx tsc --noEmit

11. Troubleshooting

AgentBoost is not initialized here — run agentboost init in the project root.

Agent doesn't see the tools — confirm the MCP server is registered (correct .mcp.json / .cursor/mcp.json), restart the agent, and check AGENTBOOST_ROOT points at the right project. Test the server directly with npx agentboost mcp (it prints AgentBoost MCP server ready to stderr and waits for stdio).

verify finds no checks — your project has no recognized scripts. Add verification entries to config.yaml (§10).

Dashboard port in use — run agentboost gui -p <other-port> or change guiPort in config.

A safe command is flagged — detection is deliberately conservative. Lower risk by setting confirmHighRisk: false, or raise the permission level. You can always proceed after reviewing; AgentBoost informs, it doesn't hard-block your CLI.

中文操作指南

面向新手的完整操作指南。

1. 安装
2. 初始化项目
3. 接入你的 Agent
4. 规划任务
5. 管理记忆
6. 自动验证
7. 安全与权限
8. 面板
9. CLI 命令速查
10. 配置
11. 常见问题

1. 安装

要求:Node.js ≥ 18。无需安装即可用 npx agentboost <命令>。永久安装:

npm install -g agentboost

2. 初始化项目

在项目根目录运行:

npx agentboost init          # 或 agentboost init -n "我的项目"

会生成 .agentboost/ 目录:config.yaml(配置)、memory.json(记忆)、 plans/(计划)、state.json(状态)、audit.log(操作日志)。想让团队共享记忆和计划就提交它,想只在本地用就加进 .gitignore。

3. 接入你的 Agent

主要通过 MCP 服务接入。打印你所用工具的配置片段:

npx agentboost adapters

Claude Code:在项目根目录创建 .mcp.json(模板见 adapters/claude-code/),重启即可。
Cursor:放到 .cursor/mcp.json 或全局 ~/.cursor/mcp.json,在设置 → MCP 里启用。
OpenCode / Codex 等:任何支持 MCP 的 Agent 都能用,见 adapters/opencode/README.md。

通用命令:npx -y agentboost mcp,并把 AGENTBOOST_ROOT 设为你的项目路径。

建议在 CLAUDE.md / .cursorrules / AGENTS.md 里加入工作流提示,让 Agent 默认使用这些工具。

4. 规划任务

用 Agent:让它「先规划」。底层会依次调用 plan_start(返回规划指引+相关记忆)、 plan_create(保存计划、进入执行阶段)、plan_set_step_status(更新步骤状态)、 plan_refine(需要调整时)。

用 CLI:

agentboost plan list
agentboost plan show        # 查看当前计划(Markdown)

计划以可读的 Markdown 存放在 .agentboost/plans/<id>.md。好的计划是 4–8 个可验证的小步骤。

5. 管理记忆

记忆保存项目的长期知识,避免 Agent 反复重学或重复犯错。四种类型: 决策 decision、架构 architecture、偏好 preference、经验 learning。

用 Agent:任务开始时 memory_search,做决定时 memory_add,memory_context 拉取精简上下文块。

用 CLI:

agentboost memory add -t decision -T "使用 SQLite" -c "为简单起见选 SQLite 而非 Postgres" --tags db
agentboost memory list
agentboost memory search sqlite
agentboost memory rm <id>

用面板:可视化地查看、新增、编辑、删除。

记忆总量受 memoryLimit 限制(默认 200),超出时优先修剪较旧、低重要度的条目; 重要度 ≥ 4 的条目永远保留。

6. 自动验证

重大改动后运行验证。AgentBoost 会自动识别你项目里的命令(npm 脚本、tsc、 pytest、go、cargo、make),也可自定义。

用 Agent:verify_run 返回每项检查的通过/失败与失败输出,便于修复后重跑。

用 CLI:

agentboost verify

想固定具体命令,编辑 config.yaml 里的 verification(见 §10)。

7. 安全与权限

三级权限:

级别	读	写文件	Shell 命令
`read-only` 只读	✅	⛔	⛔
`limited-write` 有限写入	✅	✅	⚠️ 需确认
`full-access` 完全访问	✅	✅	✅(危险命令仍会标记)

在权限之上,危险操作检测会扫描 shell 命令中的危险模式:rm -rf、git push --force、 DROP TABLE、不带 WHERE 的 DELETE、curl 管道到 shell、sudo、npm publish 等, 并给出风险等级;当 confirmHighRisk 开启时要求确认。

用 CLI:

agentboost safety level                 # 查看当前级别
agentboost safety level full-access     # 设置级别
agentboost safety check "rm -rf build"  # 评估命令(被拦截时退出码为 1)

8. 面板

agentboost gui            # 打开 http://127.0.0.1:4477
agentboost gui -p 5000    # 自定义端口
agentboost gui --no-open  # 不自动打开浏览器

面板(仅本机可访问)展示:阶段徽标、带进度条的当前计划(点状态标签可循环切换)、验证结果、记忆管理、安全检查、操作日志。每几秒自动刷新,Agent 的动作会实时出现。

9. CLI 命令速查

见上文英文 §9 的命令列表,用法完全一致。

10. 配置

.agentboost/config.yaml 可手动编辑,非法值会回退到默认:

project: my-project
permission: limited-write          # read-only | limited-write | full-access
confirmHighRisk: true              # 高/危操作是否需要确认
memoryLimit: 200                   # 记忆修剪阈值
maxParallel: 3                     # 子 Agent 并发上限
guiPort: 4477
verification:                      # 留空则自动识别
  - kind: test
    command: npm test

11. 常见问题

提示未初始化 — 在项目根目录运行 agentboost init。

Agent 看不到工具 — 确认 MCP 配置正确、重启 Agent、AGENTBOOST_ROOT 指向正确项目; 可直接运行 npx agentboost mcp 测试(会在 stderr 打印 ready 并等待 stdio)。

验证找不到检查项 — 项目没有可识别的脚本,请在 config.yaml 增加 verification。

面板端口被占用 — 用 agentboost gui -p <其他端口> 或改配置里的 guiPort。

安全命令被误标 — 检测偏保守。可将 confirmHighRisk 设为 false 或提高权限级别; AgentBoost 只提示、不会硬性阻止你的 CLI 操作。

FilesExpand file tree

guide.md

Latest commit

History

guide.md

File metadata and controls

AgentBoost Operation Guide

1. Installation

2. Initialize a project

3. Connect your agent

Claude Code

Cursor

OpenCode / Codex / other MCP agents

4. Planning a task

5. Managing memory

6. Verification

7. Safety & permissions

8. The dashboard

9. CLI reference

10. Configuration

11. Troubleshooting

中文操作指南

1. 安装

2. 初始化项目

3. 接入你的 Agent

4. 规划任务

5. 管理记忆

6. 自动验证

7. 安全与权限

8. 面板

9. CLI 命令速查

10. 配置

11. 常见问题