claude-agent-manager

Claude Agent Manager

A Claude Code plugin for spawning and managing autonomous background agents with persistent state across sessions.

What it does

• Spawn background agents that work in isolated git worktrees
• Track agent status with a persistent registry (.claude/agents/registry.json)
• Auto-detect completion via hooks — registry updates in real-time when agents finish
• Resume stopped or failed agents from where they left off
• Merge completed agent work back into your main branch
• Monitor agent activity with logs, diffs, and watch mode
• Learn from previous tasks via persistent worker memory

Install

claude plugin install agent-manager

When enabling, you'll be prompted for optional defaults:

• Default model — haiku, sonnet, or opus (leave empty to inherit from session)
• Default effort — low, medium, high, or max (leave empty for high)

Or test locally:

claude --plugin-dir /path/to/claude-agent-manager

Requirements

• Git — agents work in isolated git worktrees
• Node.js — used by the hook script (always available since Claude Code runs on Node)
• No other external dependencies

Commands

Core

Command	Description
/agent "task"	Spawn a new background agent
/agent list	Show all agents and their status
/agent switch <id>	View details of a specific agent
/agent stop <id>	Stop a running agent
/agent merge <id>	Merge a completed agent's branch
/agent history	Show full agent history
/agent clean	Remove finished agents and worktrees

Recovery

Command	Description
/agent resume <id>	Resume a stopped/failed agent on its existing branch
/agent retry <id>	Re-spawn a failed agent with the same task from scratch

Inspection

Command	Description
/agent diff <id>	Quick inline diff preview of agent's changes
/agent logs <id>	Summarized activity log of what the agent did
/agent stats	Lifetime stats — total spawned, success rate, etc.

Advanced

Command	Description
/agent batch "task1" "task2"	Spawn multiple agents in parallel
/agent note <id> "text"	Attach a note to an agent
/agent watch <id>	Poll a running agent until completion
/agent rebase <id>	Rebase agent branch onto latest main
/agent export <id>	Export changes as a .patch file

Templates

Spawn with a pre-defined template:

/agent --template api "add user profile endpoint"

Templates are stored in .claude/agents/templates/ as JSON files:

{
  "name": "api",
  "description": "API endpoint template",
  "verifyCommand": "npm test",
  "commitFormat": "feat(api): {description}"
}

Required fields: name, description. Optional: verifyCommand (overrides Phase 4 auto-detection), commitFormat (overrides conventional commit format).

Spawn Flags

Flag	Values	Description
--model	haiku, sonnet, opus	Choose which model the agent uses
--effort	low, medium, high, max	Effort level metadata (worker runs at high)
--color	red, blue, green, yellow, purple, orange, pink, cyan	Visual color for agent identification
--max-turns	<number>	Max turns metadata (worker default: 200)
--template	<name>	Use a pre-defined template

Note: --model is the only flag that changes agent behavior at runtime (via the Agent tool's model parameter). --effort and --max-turns are stored in the registry for tracking but the worker subagent always uses effort: high and maxTurns: 200 from its definition. --color sets the agent's display color.

Examples:

/agent --model sonnet "refactor the auth module"
/agent --model haiku --color blue "add JSDoc comments to utils/"
/agent --max-turns 50 "quick formatting fix"
/agent batch --model sonnet "task one" "task two"

How it works

1. Each spawned agent runs as a custom worker subagent in an isolated git worktree
2. The worker follows a structured 5-phase process:
   • Analyze — read project conventions, identify relevant files
   • Plan — break task into 3-8 ordered steps with fallbacks
   • Implement — execute incrementally, verify after each step
   • Verify — auto-detect build system and run checks (or use template's verifyCommand)
   • Commit — conventional commit, write result file back to main repo
3. A SubagentStop hook auto-updates the registry when agents complete
4. Workers accumulate project knowledge via persistent memory (.claude/agent-memory/worker/)
5. Resume agents that failed, or retry them from scratch
6. When ready, merge the agent's branch back into your working branch

Plugin Structure