# Agent Manager > Employee agent lifecycle management system. Use when working with agents/ directory employee agents - starting, stopping, monitoring, or assigning tasks to Dev/QA agents running in tmux sessions. Completely independent of CAO, uses only tmux + Python. - **Type:** Skill - **Install:** `agentstack add skill-fractalmind-ai-agent-manager-skill-agent-manager` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [fractalmind-ai](https://agentstack.voostack.com/s/fractalmind-ai) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [fractalmind-ai](https://github.com/fractalmind-ai) - **Source:** https://github.com/fractalmind-ai/agent-manager-skill/tree/main/agent-manager - **Website:** https://github.com/fractalmind-ai/agent-manager-skill/blob/main/agent-manager/SKILL.md ## Install ```sh agentstack add skill-fractalmind-ai-agent-manager-skill-agent-manager ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Manager Employee agent orchestration system for managing AI agents in tmux sessions. A simple, dependency-light alternative to CAO. ## Quick Start ```bash # Project-local install path varies by tool. If `.agent/skills/` doesn't exist, try `.claude/skills/`. # List all agents python3 .agent/skills/agent-manager/scripts/main.py list python3 .claude/skills/agent-manager/scripts/main.py list # (use the same path you chose above for the remaining commands) # Start dev agent python3 .agent/skills/agent-manager/scripts/main.py start dev # Monitor output (live) python3 .agent/skills/agent-manager/scripts/main.py monitor dev --follow # Assign task python3 .agent/skills/agent-manager/scripts/main.py assign dev bottom. - If `tmux.layout` is set, `tmux.target_pane` is required. ### Launcher Types **Full path**: Local Claude Code launcher ```yaml launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc launcher_args: ["cp", "--dangerously-skip-permissions"] ``` **Provider name**: CAO provider (optional integration) ```yaml launcher: droid launcher_args: [] ``` **Provider name**: OpenAI Codex CLI ```yaml launcher: codex launcher_args: - --model=gpt-5.2 launcher_config: model_instructions_file: ${REPO_ROOT}/agents/EMP_0001/prompt/shade-main-model.md ``` `launcher_config` is the generic escape hatch for launcher/provider-specific startup config. Each CLI provider adapts this flat mapping into its own startup flags (for Codex, each entry becomes `-c key=value`). Reserved `main` agents default to the bundled skill prompt at `agent-manager/.codex/main-codex-model.md` when `launcher: codex` is used and no explicit `launcher_config.model_instructions_file` override is provided in the workspace agent config. Note: For scheduled jobs, `agent-manager` will best-effort auto-dismiss Codex's first-run/upgrade model selection prompt to keep cron runs non-interactive. ## Commands All examples below assume you already defined `$CLI` in **Command Path Parity (Docs Baseline)**. ### `list` - List All Agents Show all configured agents and their status. ```bash $CLI list # All agents $CLI list --running # Only running ``` Output: ``` πŸ“‹ Agents: βœ… Running dev (session: agent-dev) Description: Dev Agent (project-agnostic) Working Dir: /home/user/repo Skills: review-pr, bsc-contract-development β­• Stopped qa Description: QA Agent in a multi-agent system Working Dir: /home/user/repo/projects/CloudBank-feat-invite-code β›” Disabled old-dev Description: Legacy Dev Agent (deprecated) Working Dir: /home/user/repo ``` ### `start` - Start an Agent Start an agent in a tmux session. ```bash $CLI start dev # Use default working_dir $CLI start dev --working-dir /path # Override working dir ``` - Rejects if already running (one agent, one terminal) - Rejects if agent is disabled (`enabled: false` in config) - Loads skills and injects as system prompt - Session named `agent-{name}` ### `stop` - Stop a Running Agent Stop (kill) an agent's tmux session. ```bash $CLI stop dev ``` ### `status` - Show Agent Status Show one agent's runtime snapshot, including running state, runtime state, and the most recent heartbeat marker/event. ```bash $CLI status dev ``` ### `monitor` - Monitor Agent Output View agent output from tmux session. ```bash $CLI monitor dev # Last 100 lines $CLI monitor dev -n 500 # Last 500 lines $CLI monitor dev --follow # Live monitoring (Ctrl+C to stop) ``` ### `send` - Send Message to Agent Send a message/command to a running agent. ```bash $CLI send dev "Please run tests" $CLI send dev --no-enter "Draft message only" ``` By default, `send` submits the message immediately (Enter is sent automatically). Use `--no-enter` to type without submitting. ### `assign` - Assign Task to Agent Assign a task to an agent (starts if not running). ```bash # From stdin $CLI assign dev **Note**: Either `task` or `task_file` must be provided. ### Schedule Commands #### `schedule list` - List All Scheduled Jobs ```bash $CLI schedule list ``` Output: ``` πŸ“… Scheduled Jobs: dev (EMP_0001): βœ“ daily-standup 0 9 * * 1-5 (30m) βœ“ code-review 0 14 * * 1-5 (2h) βœ“ weekly-report 0 17 * * 5 (1h) qa (EMP_0002): βœ“ nightly-tests 0 2 * * * (4h) ``` #### `schedule sync` - Sync Schedules to Crontab Synchronize all agent schedules to the system crontab. ```bash # Preview changes (dry run) $CLI schedule sync --dry-run # Apply changes $CLI schedule sync ``` This generates crontab entries like: ```cron # === agent-manager schedules (auto-generated) === # dev (EMP_0001) # daily-standup 0 9 * * 1-5 cd /path/to/repo && python3 /absolute/path/to/agent-manager/scripts/main.py schedule run dev --job daily-standup >> /tmp/agent-emp-0001-daily-standup.log 2>&1 # === end agent-manager schedules === ``` #### `schedule run` - Run a Scheduled Job Manually Manually trigger a scheduled job (useful for testing). ```bash $CLI schedule run dev --job daily-standup # Override timeout $CLI schedule run dev --job daily-standup --timeout 1h ``` ## Heartbeat Heartbeat is a special type of periodic job that sends a standard check-in message to running agents. Unlike schedules (which can have multiple jobs per agent), each agent can have **0 or 1 heartbeat** configuration. ### Heartbeat Configuration Add a `heartbeat` dict to the agent's YAML frontmatter: ```yaml --- name: dev description: Dev Agent working_directory: ${REPO_ROOT} launcher: codex launcher_args: - --model=gpt-4.7 - --dangerously-bypass-approvals-and-sandbox heartbeat: cron: "*/30 * * * *" # Every 30 minutes max_runtime: 5m session_mode: auto # restore | auto | fresh mode: normal # normal (use `timer` for delayed rescue; `full_speed` is legacy) dream: enabled: true idle_after: 1h # Optional idle-window trigger after normal HEARTBEAT_OK cycles max_runtime: 30m fixed_windows: # During these windows heartbeat dispatch sends DREAM.md tasks - timezone: Asia/Shanghai start: "23:00" end: "08:00" enabled: true --- ``` **Heartbeat Fields:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `cron` | string | βœ“ | Cron expression (e.g., `*/30 * * * *`) | | `max_runtime` | string | | Maximum runtime (e.g., `5m`, `10m`) | | `session_mode` | string | | Session policy: `restore` (default), `auto` (rollover when context > /path/to/.crontab_logs/agent-emp-0001-heartbeat.log 2>&1 # === end agent-manager schedules === ``` #### `heartbeat run` - Run a Heartbeat Manually Manually trigger a heartbeat (useful for testing). ```bash $CLI heartbeat run EMP_0001 # Override timeout $CLI heartbeat run EMP_0001 --timeout 1m ``` **Heartbeat behavior:** - Skips if agent is disabled - Skips if agent is not running (does NOT start the agent) - Sends standard heartbeat message to the agent - Optional session rollover via `session_mode` (handoff first, then fresh session) - Waits for response (up to `max_runtime`) - In `auto` mode, stale pending heartbeats can schedule or trigger rescue via the timer-backed recovery path ### `timer` - Schedule Delayed Actions Use `timer` for one-shot delayed actions without cron: ```bash # Run one heartbeat in 5 seconds $CLI timer heartbeat main --delay 5s # Schedule one heartbeat rescue in 5 seconds $CLI timer rescue main --delay 5s --timeout 8m --reason auto_pending_heartbeat_rescue # Run an arbitrary agent-manager command in 5 seconds $CLI timer command --delay 5s -- heartbeat run main --timeout 8m # Inspect recent timers $CLI timer list ``` Each run appends structured JSONL audit events to: ``` .claude/state/agent-manager/heartbeat-audit/{agent_id}.jsonl ``` Event fields (standardized for observability): - `timestamp` - `agent_id` - `hb_id` - `stage` (standard stage name, default `heartbeat_attempt`) - `result` (`success` / `failure` / `pending`) - `duration` (milliseconds, alias of `duration_ms`) - `send_status` - `ack_status` - `duration_ms` - `context_left` - `failure_type` - `session_mode` - `reason_code` - `attempt` - `recovery_action` - `reason_code` Failure classification (`failure_type`) includes: - `send_fail` - `no_ack` - `timeout` - `blocked` #### `heartbeat trace` - Query Heartbeat Audit Logs ```bash # Recent events $CLI heartbeat trace # Filter by heartbeat id $CLI heartbeat trace --hb-id 20260209-120001 # Filter by agent + time range (UTC) $CLI heartbeat trace --agent EMP_0001 --since 2026-02-09T00:00:00Z --until 2026-02-10T00:00:00Z # Output JSON $CLI heartbeat trace --agent EMP_0001 --json ``` #### `heartbeat slo` - Daily/Weekly SLO Summary ```bash # Daily summary (default) $CLI heartbeat slo # Weekly summary for one agent $CLI heartbeat slo --window weekly --agent EMP_0001 # Explicit time window + JSON $CLI heartbeat slo --since 2026-02-01T00:00:00Z --until 2026-02-08T00:00:00Z --json ``` Built-in SLO checks: - Success rate target: `>= 99%` - Timeout rate target: `<= 2%` - Recovery p95 target: `<= 120000ms` Standalone summary script (same metrics): ```bash python3 scripts/heartbeat_slo.py --window daily python3 scripts/heartbeat_slo.py --window weekly --agent EMP_0001 --json ``` ### Standard Heartbeat Message The heartbeat sends this message to the agent: ``` Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. ``` Agents should respond with `HEARTBEAT_OK` if nothing needs attention, or take action based on their `HEARTBEAT.md` file contents. ## Skills Integration Agents can reference skills from `.agent/skills/`: ```yaml skills: - review-pr - bsc-contract-development - cao ``` When the agent starts, skill contents are injected as system prompt: ``` ## Available Skills ### review-pr Code review skill for GitHub PRs and local changes... ### bsc-contract-development Comprehensive BSC smart contract development expertise... ``` **Available Skills:** - `bsc-contract-development` - BSC smart contract development - `cao` - CLI Agent Orchestrator - `collab-pr-fix-loop` - QAβ†’Devβ†’QA PR iteration - `review-pr` - Code review for PRs - `skill-creator` - Creating new skills ## Architecture ``` .agent/skills/agent-manager/ β”œβ”€β”€ SKILL.md # This file β”œβ”€β”€ scripts/ β”‚ β”œβ”€β”€ main.py # CLI entry point β”‚ β”œβ”€β”€ heartbeat_slo.py # Heartbeat SLO summary script β”‚ β”œβ”€β”€ agent_config.py # Agent file parser β”‚ β”œβ”€β”€ tmux_helper.py # Tmux wrapper β”‚ └── schedule_helper.py # Crontab management β”œβ”€β”€ providers/ β”‚ └── __init__.py # CLI provider configs └── references/ └── task_templates.md # Optional task templates ``` ### Design Principles 1. **Zero CAO Dependency**: Only tmux + Python required 2. **Provider Pattern Inspiration**: Learn from CAO but implement simply 3. **Tmux-Native**: Each agent in its own tmux session 4. **YAML Frontmatter**: Leverage existing agent file format 5. **Environment Variables**: Handle `${REPO_ROOT}` expansion 6. **One Agent, One Terminal**: Reject duplicate starts ## Comparison with CAO | Feature | CAO | Agent Manager | |---------|-----|--------------| | Dependencies | CAO server, uvx, requests | tmux, Python only | | Complexity | High (HTTP API, providers) | Low (direct tmux) | | Session Mgmt | CAO server | Native tmux | | Monitoring | HTTP API calls | Native tmux | | Extensibility | Provider system | Direct script editing | | Installation | CAO server setup | No server needed | | Use Case | Complex workflows | Simple agent management | ## Error Handling - **tmux not installed**: Clear error with install command - **Agent not found**: Lists available agents - **Already running**: Prompts to stop first - **Not running**: Prompts to start first ## Runbook Checklist For operations handoff and incident response, use: - `agent-manager/docs/runbook-checklist.md` It includes: - 30-minute newcomer self-check path - heartbeat no-ack troubleshooting SOP - stuck-session recovery SOP - CI/QA merge-gate checklist and evidence template ## Advanced Usage ### Direct Tmux Interaction ```bash # Attach to agent session (interactive) tmux attach -t agent-dev # Detach from session: Ctrl+b, then d # Capture output manually tmux capture-pane -p -t agent-dev -S -100 # List all agent sessions tmux ls | grep ^agent- ``` ### Workflow Example ```bash # Morning: Start agents $CLI start dev $CLI start qa # Assign task to dev $CLI assign dev <