Blade Agent Runtime

Blade Agent Runtime (BAR)

A local execution runtime for AI agents: isolated workspace + step ledger + diff/rollback + resumable tasks.

**一句话价值**：让任何 agent（你自己的或第三方 CLI）在隔离区里干活，并且**每一步可审计、可回滚、可恢复**。


为什么需要 BAR？

当你使用 Claude Code、Cursor、Copilot 等 AI Coding Agent 时：

痛点	BAR 的解决方案
Agent 直接修改主 repo，改错了难以回滚	在 git worktree 隔离区执行，随时 rollback
不知道 Agent 到底改了什么	每一步都有 diff 记录，完整审计日志
中断后无法恢复	Task 状态持久化，支持 resume
想试多种方案对比	多个 task 并行，互不干扰

安装

一键安装（推荐）

curl -fsSL https://echovic.github.io/blade-agent-runtime/install.sh | sh

使用 Go 安装

go install github.com/echoVic/blade-agent-runtime/cmd/bar@latest

自定义安装

# 指定安装目录
BAR_INSTALL_DIR=/usr/local/bin curl -fsSL https://echovic.github.io/blade-agent-runtime/install.sh | sh

# 指定版本
BAR_VERSION=v0.0.1 curl -fsSL https://echovic.github.io/blade-agent-runtime/install.sh | sh

快速开始

cd your-repo

# 创建任务（自动初始化，无需 bar init）
bar task start fix-null-pointer

# 方式 1：包装交互式 agent（推荐）
bar wrap -- claude           # Claude Code
bar wrap -- aider            # Aider
bar wrap -- cursor .         # Cursor

# 方式 2：运行一次性命令
bar run -- npm install lodash
bar run -- sh -c 'echo "hello" > test.txt'

# 查看 agent 做了什么
bar diff

# 满意就应用到主分支
bar apply --message "feat: fixed by AI"

# 不满意就回滚
bar rollback

核心概念

Task（任务）

一个独立的工作单元，包含：

• 隔离的 git worktree
• 独立的分支 bar/
• 完整的操作日志（ledger）

Step（步骤）

Task 中的每一个操作，包括：

• run: 执行外部命令/agent
• apply: 将变更应用到主分支
• rollback: 回滚到某个状态

Ledger（账本）

记录所有 step 的日志，包含：

• 执行的命令
• 开始/结束时间
• diff 统计
• stdout/stderr

CLI 命令

命令	说明
bar init	初始化 BAR（创建 .bar/ 目录）
bar task start	创建新任务
bar task list	列出所有任务
bar task switch	切换到指定任务
bar task close	关闭当前任务并删除 worktree
bar task close --keep	关闭任务但保留 worktree
bar task close --delete	关闭任务并删除所有记录
`bar task close --