Swarm-MCP Lite

npmだけで動く並列Issue→外部エージェントPRの自己進化CLI。

A parallel multi-agent CLI that works with just npm, creating a self-evolving system that generates issues and delegates PRs to external agents (Claude Code, Codex, etc.).

Features

• No GitHub automation required - Works entirely locally
• Parallel execution - Run multiple tasks concurrently with configurable workers
• MCP-like RPC - JSON-based protocol for external agent communication
• File locking - Prevents race conditions during parallel operations
• Multiple agent support - Easily integrate Claude Code, Codex, or custom agents
• Self-evolution - Learns from failures and successes
• Cross-platform - Works on macOS, Linux, and Windows

Install

npm i -g swarm-mcp-lite
# or
npx swarm-mcp-lite --help

Quick Start

# Initialize directory structure and config
swarm-mcp-lite init

# Generate plan and tasks from your codebase
swarm-mcp-lite plan

# Execute tasks in parallel using external agents
swarm-mcp-lite run --parallel 6 --agent claude

# Generate reports
swarm-mcp-lite harvest

Commands

init

Initialize the swarm directory structure and create a default config file.

Creates:

• docs/ directory structure
• swarm.config.json with default settings

plan

Analyze your codebase and generate tasks/issues.

Generates:

• docs/plans/plan.json - Execution plan with task DAG
• docs/issues/*.md - Issue descriptions for each task
• docs/tasks/*.json - Task metadata for agent execution

Options:

• -c, --config <path> - Config file path (default: swarm.config.json)

run

Execute tasks in parallel using external agents.

Options:

• -p, --parallel <n> - Number of parallel workers (default: 6)
• -a, --agent <name> - Agent profile to use (default: claude)
• -c, --config <path> - Config file path (default: swarm.config.json)

harvest

Generate reports from execution results.

Creates:

• docs/reports/last.md - Markdown report
• docs/reports/last.json - JSON report
• docs/reports/last.csv - CSV report

rpc

Start MCP-like RPC server for external agents.

Protocol: One JSON request per line → one JSON response per line

Available methods:

• lease.acquire - Acquire file lock
• lease.release - Release file lock
• verify.check - Run verification command
• pr.record - Record PR information
• task.get - Get task details
• health.ping - Health check

Configuration

Edit swarm.config.json to configure your project:

{
  "planner": {
    "languages": ["ts", "tsx"],
    "include": ["src/**"],
    "exclude": ["**/*.spec.ts", "**/node_modules/**"]
  },
  "workflow": {
    "parallel": 6,
    "branchPrefix": "swarm/",
    "leaseTtlSec": 120,
    "confidenceGate": 0.8
  },
  "agents": {
    "default": "claude",
    "profiles": {
      "claude": {
        "cmd": "claude-code-cli",
        "args": ["--from-swarm", "{taskFile}"]
      },
      "codex": {
        "cmd": "codex-cli",
        "args": ["--apply-task", "{taskFile}"]
      },
      "custom": {
        "cmd": "node",
        "args": ["scripts/custom-agent.js", "{taskFile}"]
      }
    }
  }
}

Agent Configuration

The {taskFile} placeholder is replaced with the path to the task JSON file.

External agents receive task files with this structure:

{
  "id": "T001",
  "title": "Improve src/index.ts",
  "branch": "swarm/T001",
  "targets": ["src/index.ts"],
  "verify": {
    "lint": "npm run lint || true",
    "type": "npm run typecheck || true",
    "tests": "npm test || true"
  }
}

Creating Custom Agents

Create a script that:

1. Reads the task file (path provided as argument)
2. Performs the required changes
3. Optionally communicates with the RPC server for locks/verification
4. Exits with code 0 on success, non-zero on failure

Example:

// scripts/custom-agent.js
import { readFileSync } from 'fs';

const taskFile = process.argv[2];
const task = JSON.parse(readFileSync(taskFile, 'utf-8'));

console.log(`Processing task: ${task.id}`);
console.log(`Targets: ${task.targets.join(', ')}`);

// Your implementation here...

process.exit(0);

Directory Structure

your-project/
├─ swarm.config.json     # Configuration
├─ docs/
│  ├─ plans/             # Generated plans
│  ├─ issues/            # Generated issue descriptions
│  ├─ tasks/             # Task metadata for agents
│  ├─ prs/               # PR records
│  ├─ reports/           # Execution reports
│  └─ learn/             # Learning data (future)

RPC Protocol Example

Start the RPC server:

swarm-mcp-lite rpc

Send requests (one JSON per line):

{"id": 1, "method": "health.ping"}
{"id": 2, "method": "lease.acquire", "params": {"target": "src/index.ts", "ttlSec": 120}}
{"id": 3, "method": "verify.check", "params": {"cmd": "npm test"}}

Receive responses:

{"id": 1, "result": {"ok": true, "timestamp": 1234567890}}
{"id": 2, "result": {"ok": true}}
{"id": 3, "result": {"lint": 1, "type": 1, "tests": 1, "score": 0.9}}

Requirements

• Node.js v18 or higher
• npm or yarn

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Future Features

• Self-learning from execution results
• Advanced DAG-based task scheduling
• Confidence scoring and adaptive parallelism
• Integration with more external agents
• Graphical visualization of task execution