Agent Manager

Agent Manager

Employee agent orchestration system for managing AI agents in tmux sessions. A simple, dependency-light alternative to CAO.

Quick Start

# 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)

launcher: droid
launcher_args: []

Provider name: OpenAI Codex CLI

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.

$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.

$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.

$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.

$CLI status dev

monitor - Monitor Agent Output

View agent output from tmux session.

$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.

$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).

# 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.

# Preview changes (dry run)
$CLI schedule sync --dry-run

# Apply changes
$CLI schedule sync

This generates crontab entries like:

# === 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).

$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:

---
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:

# 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

# 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

# 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):

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/:

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

# 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

# Morning: Start agents
$CLI start dev
$CLI start qa

# Assign task to dev
$CLI assign dev <<EOF
Implement the user profile feature:
1. Profile update API
2. Profile view component
3. Integration tests
EOF

# Quick runtime snapshot
$CLI status dev

# Monitor progress
$CLI monitor dev --follow

# Send clarification if needed
$CLI send dev "Please add validation for email format"

# After dev completes, assign to QA
$CLI assign qa <<EOF
Review the user profile feature:
- Security check
- Edge cases
- Test coverage
EOF

# Evening: Stop agents
$CLI stop dev
$CLI stop qa

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fractalmind-ai
• Source: fractalmind-ai/agent-manager-skill
• License: MIT
• Homepage: https://github.com/fractalmind-ai/agent-manager-skill/blob/main/agent-manager/SKILL.md

Install and usage instructions live in the source repository linked above.