agent-manager

name agent-manager description 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. license MIT allowed-tools ["Read","Write","Edit","Bash","Task"] 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 << EOF Fix the login bug in the auth module EOF # Stop agent python3 .agent/skills/agent-manager/scripts/main.py stop dev Command Path Parity (Docs Baseline) For consistency with README.md and runbook examples, define one CLI alias and reuse it in your session: # Installed skill path (pick one that exists) CLI= "python3 .agent/skills/agent-manager/scripts/main.py" # CLI="python3 .claude/skills/agent-manager/scripts/main.py" # If operating from a cloned repo instead of installed skill: # CLI="python3 agent-manager/scripts/main.py" $CLI doctor $CLI list $CLI status EMP_0001 Core Concepts Agent Configuration Agents are defined in agents/EMP_*.md files with YAML frontmatter: --- name: dev description: Dev Agent (project-agnostic) working_directory: ${REPO_ROOT} launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc launcher_args: - cp - --dangerously-skip-permissions skills: - review-pr - bsc-contract-development --- # DEV AGENT ## Role and Identity You are the Dev Agent... Fields: name : Agent identifier (dev, qa) description : Agent description enabled : Whether agent can be started (default: true , set false to disable) working_directory : Default working directory (supports ${REPO_ROOT} ) launcher : Full path OR provider name launcher_args : Arguments for launcher launcher_config : Optional launcher/provider-specific startup config skills : Array of skill names from .agent/skills/ (optional, injected at start) schedules : Array of scheduled jobs (optional, see Scheduling section) tmux : Optional tmux layout metadata (layout + target pane) Tmux Sessions Each agent runs in a dedicated tmux session ( agent-{name} ): Easy monitoring : tmux capture-pane -t agent-dev Direct interaction : tmux attach -t agent-dev Clean separation : No process pollution Optional: Tmux Layouts You can auto-create a tmux layout and launch the agent in a specific pane: tmux: layout: split: h panes: - {} - split: v panes: - {} - {} target_pane: "1.1" Notes: split : h (left/right) or v (top/bottom). horizontal / vertical also work. target_pane : dot-separated path of 0 / 1 indexes into the layout tree. 0 = left/top, 1 = right/bottom. "1.1" means right -> bottom. If tmux.layout is set, tmux.target_pane is required. Launcher Types Full path : Local Claude Code launcher 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 ). Provider name : Kimi Code CLI launcher: kimi launcher_args: - --auto Kimi Code provider notes: session restore uses --session <id> ; system prompt injection currently uses tmux paste fallback; MCP config is not injected at launch time. 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. message - Agent-to-Agent Protocol Messages Compose or send a minimal Agent-to-Agent protocol envelope with three sections: required Meta , required Body , and optional plain-text Footer reply hint. # Print an envelope to stdout only $CLI message compose --from EMP_0001 --to EMP_0017 --body "Review PR #123." # Send a protocol message through tmux $CLI message send EMP_0017 --from EMP_0001 --body "Review PR #123." --footer "Reply with QA Verdict: PASS/FAIL." # Send a protocol reply $CLI message reply --from EMP_0017 --to EMP_0001 --reply-to msg_20260724_153012_ab12cd34 --body "QA Verdict: PASS" When sending to an agent that may not have this protocol installed, keep Footer to one sentence: Read the agent-manager skill's message protocol and reply with reply_to: msg_20260724_153012_ab12cd34. Envelope format: --- Meta --- id: msg_20260724_153012_ab12cd34 type: message from: EMP_0001 to: EMP_0017 --- Body --- Review PR #123. --- Footer --- Reply with QA Verdict: PASS/FAIL. Meta is deliberately minimal: id , type ( message or reply ), from , to , and optional reply_to for replies. Body is plain text and may be multiline. Footer is optional, plain text only, and should be used only for reply hints. For cross-agent compatibility, prefer a one-sentence Footer that points the receiver to the agent-manager skill instead of embedding a protocol tutorial. This protocol is stateless: it does not create inbox/outbox files, acknowledgements, retries, replay records, or thread logs. Command success only means the tmux send operation succeeded; the sending side remains responsible for confirming delivery and processing. assign - Assign Task to Agent Assign a task to an agent (starts if not running). # From stdin $CLI assign dev << EOF 🎯 Task: Fix the login bug 1. Reproduce the issue 2. Identify root cause 3. Implement fix 4. Add tests EOF # From file $CLI assign dev --task-file task.md assign submits automatically (Enter is sent by default), so no manual tmux Enter step is required. Disabling Agents Agents can be temporarily disabled to prevent them from being started (useful for maintenance, testing, or decommissioning). Disable an Agent Add enabled: false to the agent's YAML frontmatter: --- name: dev description: Dev Agent (project-agnostic) enabled: false # ← Agent cannot be started working_directory: ${REPO_ROOT} launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc --- Behavior When an agent is disabled: ⛔ list command shows "Disabled" status ⚠️ start command is rejected with error message schedule sync skips all schedules for the disabled agent Running sessions are NOT automatically stopped (manual stop required) To re-enable: Set enabled: true or remove the field (defaults to true ) Use Cases Maintenance : Temporarily disable an agent while updating its configuration Testing : Prevent a scheduled agent from running during testing Decommissioning : Mark an agent as obsolete before removing its file Scheduling Agents can be configured to run automatically on a schedule using cron expressions. Schedule Configuration Add a schedules array to the agent's YAML frontmatter: --- name: dev description: Dev Agent working_directory: ${REPO_ROOT} launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc launcher_args: - cp - --dangerously-skip-permissions skills: - bsc-contract-development schedules: - name: daily-standup cron: "0 9 * * 1-5" task: | Review GitHub issues, prioritize today's work max_runtime: 30m - name: code-review cron: "0 14 * * 1-5" task_file: ${REPO_ROOT}/tasks/templates/code-review.md max_runtime: 2h - name: weekly-report cron: "0 17 * * 5" task: | Generate weekly progress report and commit to docs/ max_runtime: 1h enabled: true --- Schedule Fields: Field Type Required Description name string ✓ Unique job identifier cron string ✓ Cron expression (e.g., 0 9 * * 1-5 ) task string △ Inline task description task_file string △ Path to task file (supports ${REPO_ROOT} ) max_runtime string Maximum runtime (e.g., 30m , 2h , 8h ) enabled bool Default: true Note : Either task or task_file must be provided. Schedule Commands schedule list - List All Scheduled Jobs $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