Skip to main content

Swarm Tools

Tools for executing coding tasks via agent swarms. The coding swarm system provisions isolated git workspaces, spawns coding agents, and handles the full lifecycle from task execution through PR creation.

Available Tools​

swarm_execute​

Start a coding swarm execution. Clones the target repository, creates a feature branch, spawns an agent, and sends the task.

{
  "name": "swarm_execute",
  "arguments": {
    "workspaceId": "ws_123",
    "repoUrl": "https://github.com/org/repo",
    "taskDescription": "Add input validation to the user registration endpoint",
    "agentType": "claude-code",
    "baseBranch": "main",
    "taskContext": "The endpoint is in src/routes/auth.ts. Use zod for validation."
  }
}

Arguments:

ArgumentTypeRequiredDescription
workspaceIdstringYesWorkspace ID
repoUrlstringYesGit repository URL to clone
taskDescriptionstringYesWhat the agent should implement
spaceIdstringNoSpace to associate with
experimentIdstringNoLink execution to a research experiment
agentTypestringNoAgent type (claude-code, codex, gemini, aider). Defaults to claude-code
baseBranchstringNoBranch to base work on (default: main)
taskContextstringNoAdditional context for the agent
triggeredBystringNoWhat triggered this execution (e.g., experiment, manual)

Response:

{
  "executionId": "exec_abc123",
  "status": "pending"
}

swarm_status​

Get the current status and results of a coding swarm execution.

{
  "name": "swarm_status",
  "arguments": {
    "executionId": "exec_abc123"
  }
}

Response:

{
  "id": "exec_abc123",
  "status": "completed",
  "agentType": "claude-code",
  "agentId": "agent_456",
  "taskDescription": "Add input validation to the user registration endpoint",
  "outputSummary": "Added zod validation schema for registration payload...",
  "exitCode": 0,
  "results": {
    "prUrl": "https://github.com/org/repo/pull/42",
    "branchName": "swarm/exec-abc123",
    "commitCount": 2
  },
  "filesChanged": ["src/routes/auth.ts", "src/schemas/user.ts"],
  "startedAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:15:00Z",
  "createdAt": "2024-01-15T09:59:00Z"
}

swarm_list​

List coding swarm executions in a workspace.

{
  "name": "swarm_list",
  "arguments": {
    "workspaceId": "ws_123",
    "status": "completed",
    "limit": 10
  }
}

Arguments:

ArgumentTypeRequiredDescription
workspaceIdstringYesWorkspace ID
statusstringNoFilter by status
experimentIdstringNoFilter by experiment
limitnumberNoMax results (default: 20)

Response:

{
  "executions": [
    {
      "id": "exec_abc123",
      "status": "completed",
      "agentType": "claude-code",
      "taskDescription": "Add input validation...",
      "experimentId": null,
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:15:00Z",
      "createdAt": "2024-01-15T09:59:00Z"
    }
  ]
}

swarm_stop​

Stop a running coding swarm execution.

{
  "name": "swarm_stop",
  "arguments": {
    "executionId": "exec_abc123"
  }
}

Response:

{
  "success": true,
  "message": "Execution cancelled"
}

swarm_logs​

Get terminal output logs from a coding swarm execution.

{
  "name": "swarm_logs",
  "arguments": {
    "executionId": "exec_abc123",
    "limit": 100
  }
}

Arguments:

ArgumentTypeRequiredDescription
executionIdstringYesExecution ID
limitnumberNoMax lines to return

Execution Lifecycle​

The coding swarm follows a multi-phase lifecycle:

StatusDescription
pendingExecution created, waiting for processing
provisioningCloning repository, creating feature branch
spawningGenerating credentials, writing agent memory file, starting agent
runningAgent is actively working on the task
capturingAgent finished, extracting results and changed files
finalizingCommitting changes, pushing branch, creating pull request
completedExecution finished successfully
failedExecution encountered an error
cancelledExecution was stopped by the user

How It Works​

Workspace Preparation​

Before an agent starts, the system prepares its workspace:

  1. MCP API Key — Generates a scoped API key so the agent can call back to Raven
  2. Memory File — Writes a .raven-memory.md file with workspace context, long-term memory, and API documentation
  3. Environment Variables — Sets MCP_API_KEY, MCP_SERVER_URL, RAVEN_WORKSPACE_ID, and other credentials
  4. Approval Config — Pre-configures approval settings if auto-approval is enabled

Agent Execution​

The agent runs in an isolated PTY session with full terminal access. It receives the task description and memory file, then works autonomously to implement the changes.

Finalization​

After the agent completes:

  1. All changes are staged and committed
  2. The feature branch is pushed to the remote
  3. A pull request is created with the task description as the body
  4. Results (PR URL, files changed, output summary) are recorded

Example: Full Workflow​

// 1. Start execution
const { executionId } = await mcp.call("swarm_execute", {
  workspaceId: "ws_123",
  repoUrl: "https://github.com/org/repo",
  taskDescription: "Add unit tests for the UserService class",
  agentType: "claude-code"
});

// 2. Poll for completion
let status;
do {
  await sleep(10000);
  status = await mcp.call("swarm_status", { executionId });
} while (!["completed", "failed", "cancelled"].includes(status.status));

// 3. Check results
if (status.status === "completed") {
  console.log(`PR created: ${status.results.prUrl}`);
  console.log(`Files changed: ${status.filesChanged.join(", ")}`);
}

Linking to Experiments​

Coding swarm executions can be linked to research experiments for traceability:

// Create an experiment
const exp = await mcp.call("experiment_register", {
  workspaceId: "ws_123",
  spaceId: "space_456",
  title: "Test rate limiting implementation",
  hypothesisId: "page_hyp_123"
});

// Execute with experiment link
await mcp.call("swarm_execute", {
  workspaceId: "ws_123",
  repoUrl: "https://github.com/org/repo",
  taskDescription: "Implement rate limiting middleware",
  experimentId: exp.page.id,
  triggeredBy: "experiment"
});