claude-army

🪖 ClaudeArmy

An MCP server that lets Claude orchestrate multiple Claude Code agents working autonomously across different projects.

What It Does

ClaudeArmy gives Claude (in the chat interface) the ability to spawn background Claude Code processes that work independently on coding tasks. Think of it as a chain of command:

• You → give strategic direction
• Claude (chat) → breaks it down and dispatches agents
• Claude Code agents → execute autonomously, spawning their own sub-agents as needed

This means you can kick off work across multiple projects simultaneously, keep chatting normally, and check in on progress whenever you want.

Tools

Tool	Description
dispatch_task	Deploy a Claude Code agent to a project directory. Supports mode: "team" for multi-agent coordination
check_tasks	Monitor status of all running/completed agents
get_task_output	Retrieve what an agent did and its full output
get_agent_team	Detailed view of a lead agent and all its sub-agents
cancel_task	Stop a running agent gracefully
purge_tasks	Clean up completed/failed tasks

Setup

• Clone this repo

• npm install

• Add to your Claude Desktop config:

  • Linux: ~/.config/Claude/claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

"claude-army": {
  "command": "node",
  "args": ["/path/to/claude-army/src/index.js"]
}

Windows note: Use forward slashes in the path value (e.g. "C:/Users/you/claude-army/src/index.js").

• Restart Claude Desktop

Usage Examples

Single project task:

"Refactor GarbageFire's app.py into modular components"

Multi-project parallel work:

"Refactor GarbageFire to be more modular, and add a Salesforce adapter to my Reporting Tool"

Claude will dispatch separate agents to each project directory and let them work autonomously.

Check progress:

"How are the agents doing?"

Agent Teams

Use mode: "team" on dispatch_task to have the lead agent automatically decompose work and spawn specialized sub-agents that run in parallel.

How it works:

• The lead agent analyzes the task and breaks it into focused subtasks
• Each subtask is delegated to a sub-agent via Claude Code's Task tool
• Sub-agents work in parallel, each with a well-defined scope
• The lead agent synthesizes results once all sub-agents complete

Monitoring teams:

• check_tasks shows a sub-agent summary (e.g. "3 sub-agents: 1 running, 2 completed")
• get_agent_team gives a detailed tree view of the lead agent and every sub-agent, including status, runtime, and output previews

Configuration

Edit the constants at the top of src/index.js:

• CLAUDE_BINARY - Path to your Claude Code binary
• MAX_CONCURRENT_TASKS - Max simultaneous agents (default: 5)

Requirements

• Claude Code installed and authenticated
• Node.js 18+
• Claude Desktop or any MCP-compatible client

Changelog

v0.4.1

• Bump @modelcontextprotocol/sdk to ^1.26.0, resolving 3 high severity supply chain vulnerabilities
• Add repository field to package.json

v0.4.0

• Agent team support: track sub-agents spawned via Claude Code Task tool
• New get_agent_team tool: tree view of lead + all sub-agents
• check_tasks now shows sub-agent summary for team operations
• dispatch_task gains mode parameter: solo (default) or team
• Cross-platform: fixed Windows binary (claude.cmd) and signal handling
• Error messages now show platform-appropriate diagnostic commands
• README: added setup paths for Linux, macOS, and Windows

v0.3.0

• Fixed stream-json parsing to correctly handle assistant message content arrays
• Staleness indicator: check_tasks now shows time since last agent activity
• Better error surfacing: actionable messages for CLI not found, permission denied, and mid-run failures
• Fixed output duplication in get_task_output
• Demo GIF added to README

v0.2.0

• Real-time progress tracking via Claude Code's stream-json output
• check_tasks now shows recent agent activity (file reads, edits, bash commands) instead of just runtime
• get_task_output includes a full progress timeline with timestamps
• Structured event parsing for tool use, assistant messages, and results

v0.1.0

• Initial release
• Core tools: dispatch_task, check_tasks, get_task_output, cancel_task, purge_tasks
• Fire-and-forget architecture with background process management
• Max 5 concurrent agents
• stdio transport for MCP communication

License

MIT