agent-manager

用途

Agent Manager 是一个简单、与安装方式无关的 AI 智能体生命周期管理工具，基于 tmux + Python 实现。它用于在本地管理多个 AI 智能体，无需运行服务器、无需接入 HTTP API，也无需引入重型依赖。

适用场景包括：

在 tmux 会话中启动、停止、监控 AI 智能体
通过 cron 调度智能体任务（每日站会、代码审查、夜间测试）
向运行中的智能体发送心跳检查
从文件或标准输入向智能体分配任务
管理定义在 agents/EMP_*.md YAML frontmatter 文件中的智能体

主要能力

智能体配置

智能体以 agents/EMP_*.md 文件定义，使用 YAML frontmatter。关键字段包括：name、description、enabled（默认 true）、working_directory（支持 ${REPO_ROOT}）、launcher、launcher_args、launcher_config、skills、schedules、heartbeat、tmux。

示例：

---
name: dev
description: Dev Agent
working_directory: ${REPO_ROOT}
launcher: claude
launcher_args:
  - --dangerously-skip-permissions
skills:
  - review-pr
schedules:
  - name: daily-standup
    cron: "0 9 * * 1-5"
    task: |
      Review GitHub issues, prioritize today's work
    max_runtime: 30m
heartbeat:
  cron: "*/30 * * * *"
  max_runtime: 5m
  session_mode: auto
---

启动器类型

支持完整路径（如 Claude Code）或提供方名称（如 Codex CLI）：

# Full path (Claude Code)
launcher: ${REPO_ROOT}/path/to/launcher
launcher_args: ["--dangerously-skip-permissions"]

# Provider name (Codex CLI)
launcher: codex
launcher_args: [--model=gpt-4.7]
launcher_config:
  model_instructions_file: ${REPO_ROOT}/agents/prompt.md

命令

$CLI list                    # All agents (running/stopped/disabled)
$CLI list --running          # Only running agents
$CLI start dev               # Start agent in tmux session agent-dev
$CLI start dev --working-dir /path  # Override working dir
$CLI stop dev                # Kill agent tmux session
$CLI status dev              # Runtime snapshot + last heartbeat
$CLI monitor dev             # Last 100 lines of output
$CLI monitor dev -n 500      # Last 500 lines
$CLI monitor dev --follow    # Live tail (Ctrl+C to stop)
$CLI send dev "message"      # Send message (auto-submits)
$CLI send dev --no-enter "draft"  # Type without submitting
$CLI assign dev <<EOF        # Assign task from stdin
Task: Fix login bug
1. Reproduce, 2. Fix, 3. Test
EOF
$CLI assign dev --task-file task.md  # Assign from file
$CLI doctor                  # Sanity check setup

调度

schedules:
  - name: daily-standup
    cron: "0 9 * * 1-5"
    task: |
      Review issues and prioritize work
    max_runtime: 30m
    enabled: true

$CLI schedule list           # Show all scheduled jobs
$CLI schedule sync           # Write to system crontab
$CLI schedule sync --dry-run # Preview changes
$CLI schedule run dev --job daily-standup  # Manual trigger

心跳

每个智能体可配置一个心跳用于周期性检查：

heartbeat:
  cron: "*/30 * * * *"
  max_runtime: 5m
  session_mode: auto   # restore | auto | fresh

$CLI heartbeat list          # Show all heartbeat configs
$CLI heartbeat sync          # Sync to crontab
$CLI heartbeat run EMP_0001  # Manual trigger
$CLI heartbeat trace --agent EMP_0001 --since 2026-01-01T00:00:00Z
$CLI heartbeat slo           # Daily SLO summary (target: ≥99% success)
$CLI heartbeat slo --window weekly --agent EMP_0001

发送给智能体的心跳消息为：

"Read HEARTBEAT.md if it exists. Follow it strictly. If nothing needs attention, reply HEARTBEAT_OK."

禁用智能体

---
name: dev
enabled: false   # ← prevents start; running sessions not stopped
---

技能集成

智能体 frontmatter 中列出的技能会在启动时作为系统提示注入：

skills:
  - review-pr
  - bsc-contract-development

技能解析顺序（首个匹配生效）：

<repo>/.agent/skills/<skill>/SKILL.md
~/.agent/skills/<skill>/SKILL.md
<repo>/.claude/skills/<skill>/SKILL.md
~/.claude/skills/<skill>/SKILL.md

使用方式

快速开始

# Install
bash ~/.agent-skills/agent-manager/scripts/install.sh

# Setup in your project
bash ~/.agent-skills/agent-manager/scripts/setup.sh

# Define CLI alias (pick path matching your install)
CLI="python3 ~/.claude/skills/agent-manager/scripts/main.py"

# Use
$CLI list
$CLI start EMP_0001
$CLI status EMP_0001
$CLI monitor EMP_0001 --follow
$CLI stop EMP_0001

操作步骤

确认 agent-manager 是合适的工具：当用户需要基于 tmux 与 Python 的轻量本地智能体编排，而非托管控制平面时使用。若请求仅涉及单次进程内子智能体运行且无持久会话，应改用原生编排方式。
在改动活动会话前先安装或验证：新环境或不明确的环境从 scripts/install.sh 与 scripts/setup.sh 开始；首次真实运行前、移动仓库后或启用调度与心跳前，建议先运行 $CLI doctor；写入 crontab 前使用 schedule sync --dry-run 与 heartbeat sync --dry-run。
通过 markdown frontmatter 建模智能体：每个智能体放在 agents/EMP_*.md 中，明确 working_directory、launcher、skills 以及可选的 schedules 或 heartbeat；使用 enabled: false 安全停用智能体而不删除配置；每个智能体保持稳定名称与窄职责。
以明确的运行时证据操作：发送新工作前使用 $CLI list、$CLI status、$CLI monitor 检查当前状态；start、assign 或 schedule 变更后，用 $CLI status NAME 或 $CLI monitor NAME --follow 验证；长任务优先使用 --task-file。

适用场景

本地开发智能体的启动与监控
工作日站会与心跳的安全调度
从文件分配较长任务

限制与要求

需要 Python 3.x
需要 tmux
智能体需定义在 agents/ 目录下

架构

agent-manager/
├── SKILL.md
├── scripts/
│   ├── main.py              # CLI entry point
│   ├── agent_config.py      # YAML frontmatter parser
│   ├── tmux_helper.py       # tmux session wrapper
│   ├── schedule_helper.py   # crontab management
│   └── heartbeat_slo.py     # SLO summary script
├── providers/
│   └── __init__.py          # CLI provider configs
├── references/
│   └── quick-reference.md   # Command cheat sheet
└── scripts/
    ├── install.sh            # Installation script
    └── setup.sh              # Project setup script

最佳实践

在新仓库启用调度或心跳前运行 $CLI doctor。
改动 crontab 前使用 schedule sync --dry-run 与 heartbeat sync --dry-run。
保持每个智能体配置窄而稳定，避免将单个 tmux 会话变成万能工作器。
长提示或周期性任务优先使用 assign --task-file，便于审查。
维护窗口使用 enabled: false，而非删除智能体定义。

参考

quick-reference
install script
setup script
https://github.com/fractalmind-ai/agent-manager-skill