Agent of Empires（aoe）技能

使用 aoe 在 tmux 中创建、管理与监控 AI 编码代理会话（如 Claude Code、Codex、OpenCode 等）。相较于直接使用原始 tmux 命令，应优先选用 aoe 进行代理会话管理。

适用场景

• 在项目目录中启动一个或多个 AI 编码代理
• 监控代理运行状态（等待中 / 运行中 / 空闲中）
• 捕获代理输出以供人工审查
• 将代理按组或配置文件进行归类组织
• 搭建基于 git worktree 的并行开发环境

请勿将本技能用于与编码代理无关的通用 tmux 窗口/面板管理任务。

核心概念

• 会话（Session）：运行于 tmux 会话中的一个代理进程。每个会话具有唯一 ID、标题、工具类型（例如 claude）及项目路径。
• 组（Group）：用于组织会话的命名文件夹（支持通过 / 实现嵌套，例如 backend/api）。
• 配置文件（Profile）：一个独立的工作区，拥有其自身的会话集合与配置。可通过全局参数 -p 指定，或设置环境变量 AGENT_OF_EMPIRES_PROFILE。
• 状态（Status）：取值为以下之一：running、waiting、idle、stopped、error、starting、unknown。

命令参考

添加会话

# 为当前目录添加会话
aoe add . -t "my feature"

# 指定组并立即启动
aoe add /path/to/repo -t "API work" -g backend -l

# 指定特定工具
aoe add . -t "codex session" -c codex

# 在 git worktree（并行分支）中添加
aoe add . -t "fix-123" -w fix/issue-123 -l

# 在 Docker sandbox 中添加
aoe add . -t "sandboxed" -s -l

# 作为另一会话的子会话添加
aoe add . -t "sub task" -P 

# 启用 YOLO 模式（跳过权限确认提示）
aoe add . -t "yolo" -y -l

列出会话

# 以人类可读格式列出
aoe list

# 输出 JSON 格式（便于程序解析）
aoe list --json

# 列出所有配置文件下的会话
aoe list --all

JSON 输出结构（aoe list --json）：

[
  {
    "id": "a1b2c3d4-...",
    "title": "my feature",
    "path": "/home/user/project",
    "group": "backend",
    "tool": "claude",
    "command": "claude",
    "profile": "default",
    "created_at": "2025-01-01T00:00:00Z",
    "workspace_repos": []
  }
]

若 command 字段为空，则该字段不会出现在 JSON 输出中；worktree 字段仅对基于 worktree 的会话存在。list --json 不包含实时运行状态；如需获取状态，请使用 aoe status --json 或 aoe session capture --json。

会话生命周期管理

aoe session start 
aoe session stop 
aoe session restart 
aoe session attach    # 交互式连接

检查会话

# 显示会话元数据
aoe session show  --json

# 捕获 tmux 面板内容（监控关键操作）
aoe session capture  --json
aoe session capture  -n 100 --strip-ansi
aoe session capture    # 纯文本格式，适合管道传递

# 快速状态概览
aoe status --json
aoe status -q   # 仅返回等待中数量（适用于脚本）

JSON 输出结构（aoe session capture --json）：

{
  "id": "a1b2c3d4-...",
  "title": "my feature",
  "status": "waiting",
  "tool": "claude",
  "content": "... pane text ...",
  "lines": 50
}

JSON 输出结构（aoe session show --json）：

{
  "id": "a1b2c3d4-...",
  "title": "my feature",
  "path": "/home/user/project",
  "group": "backend",
  "tool": "claude",
  "command": "claude",
  "status": "running",
  "profile": "default"
}

JSON 输出结构（aoe status --json）：

{
  "waiting": 1,
  "running": 2,
  "idle": 1,
  "stopped": 1,
  "error": 0,
  "total": 5
}

自动识别（在 tmux 面板内调用时）

当从 aoe 托管的 tmux 会话内部调用时，可省略会话标识符：

aoe session show          # 自动识别当前会话
aoe session capture       # 自动识别当前会话
aoe session current --json

重命名与组织

aoe session rename  -t "new title"
aoe session rename  -g "new/group"

aoe group create mygroup
aoe group move  mygroup
aoe group list --json
aoe group delete mygroup --force

配置文件（Profiles）

aoe profile list
aoe profile create staging
aoe profile delete staging
aoe profile default staging   # 设为默认配置文件
aoe -p staging list            # 内联指定配置文件

Worktree 相关命令

aoe worktree list
aoe worktree info 
aoe worktree cleanup -f

移除会话

aoe remove 
aoe remove  --delete-worktree --force

典型工作流模式

单代理工作流

aoe add /path/to/repo -t "feature X" -l
# ... 等待执行完成 ...
aoe session capture "feature X" --json

并行 worktree 代理工作流

aoe add . -t "issue-100" -w fix/issue-100 -l
aoe add . -t "issue-101" -w fix/issue-101 -l
aoe add . -t "issue-102" -w fix/issue-102 -l
aoe status --json   # 一次性检查全部状态

轮询监控循环

持续轮询所有会话，直至无任何会话处于运行或等待状态：

while true; do
  status=$(aoe status --json)
  waiting=$(echo "$status" | jq '.waiting')
  running=$(echo "$status" | jq '.running')
  if [ "$running" -eq 0 ] && [ "$waiting" -eq 0 ]; then
    echo "All agents finished"
    break
  fi
  echo "Running: $running, Waiting: $waiting"
  sleep 30
done

批量捕获与审查

for id in $(aoe list --json | jq -r '.[].id'); do
  echo "=== $id ==="
  aoe session capture "$id" -n 100 --strip-ansi
  echo
done

通过 TUI 进行组级操作

组（Groups）主要通过 aoe 的 TUI（终端用户界面）进行管理（直接运行不带参数的 aoe 即可启动）。TUI 支持对组内所有会话执行批量启动/停止/重启操作。如需自动化脚本控制，请使用上方所列 CLI 命令。