swarm-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Vipul Maheshwari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,384 @@
+# swarm-code
+
+Open-source swarm-native coding agent orchestrator. Spawns parallel coding agents in isolated git worktrees, orchestrated by a Recursive Language Model (based on [arXiv:2512.24601](https://arxiv.org/abs/2512.24601)).
+
+## Install
+
+```bash
+npm install -g swarm-code
+```
+
+Requires **Node.js >= 20** and **Python 3**.
+
+### Supported Providers
+
+| Provider | Env Variable | Default Model |
+|----------|-------------|---------------|
+| **Anthropic** | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| **OpenAI** | `OPENAI_API_KEY` | `gpt-4o` |
+| **Google** | `GEMINI_API_KEY` | `gemini-2.5-flash` |
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### From Source
+
+```bash
+git clone https://github.com/kingjulio8238/swarm-code.git
+cd swarm-code
+npm install
+npm run build
+npm link
+```
+
+## Usage
+
+### Swarm Mode — Parallel Coding Agents
+
+Point swarm at a repo with a task. It scans the codebase, decomposes the work, and spawns coding agents in isolated git worktrees:
+
+```bash
+swarm --dir ./my-project "add error handling to all API routes"
+```
+
+The orchestrator LLM writes Python code that calls `thread()` to spawn agents, `asyncio.gather()` for parallelism, and `merge_threads()` to integrate changes:
+
+```bash
+# With auto model routing (picks best agent+model per task)
+swarm --dir ./project --auto-route "migrate from Express to Fastify"
+
+# Dry run — plan without executing
+swarm --dir ./project --dry-run "refactor auth module"
+
+# Budget cap
+swarm --dir ./project --max-budget 5.00 "add comprehensive tests"
+
+# Specific agent backend
+swarm --dir ./project --agent claude-code "review and fix security issues"
+
+# Verbose — see routing decisions and memory hints
+swarm --dir ./project --verbose --auto-route "optimize database queries"
+```
+
+### Agent Backends
+
+| Agent | Description | Best for |
+|-------|------------|----------|
+| `opencode` (default) | Open-source, multi-provider, tool-capable | General coding, testing |
+| `claude-code` | Anthropic's Claude Code CLI | Deep analysis, refactoring |
+| `codex` | OpenAI's Codex CLI | Shell commands, OpenAI models |
+| `aider` | Git-aware AI coding assistant | Targeted edits, minimal changes |
+| `direct-llm` | Bare LLM call, no agent wrapper | Analysis, planning, classification |
+
+### RLM Text Mode (inherited)
+
+The original RLM text-processing mode is preserved:
+
+```bash
+swarm run --file large-document.txt "summarize the key findings"
+swarm run --url https://example.com/data.txt "extract all dates"
+cat data.txt | swarm run --stdin "count the errors"
+```
+
+### Interactive Mode
+
+Run with `--dir` but no task to enter interactive mode — a persistent REPL with live thread monitoring:
+
+```bash
+swarm --dir ./my-project
+```
+
+Commands:
+
+| Command | Description |
+|---------|-------------|
+| `/threads` | List all threads with status, cost, duration |
+| `/thread <id>` | Show thread detail (files changed, diff, result) |
+| `/merge` | Merge all completed thread branches |
+| `/reject <id>` | Reject a thread's changes |
+| `/dag` | Show thread DAG with timing bars |
+| `/budget` | Show budget breakdown |
+| `/status` | Show session stats |
+| `/help` | List commands |
+| `/quit` | Cleanup and exit |
+
+Ctrl+C once cancels the current task. Ctrl+C twice exits.
+
+### GitHub Action
+
+Trigger swarm from issue comments. Add `.github/workflows/swarm.yml` to your repo (a template is provided in this repo):
+
+```yaml
+name: Swarm Agent
+on:
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      task:
+        description: 'Task for swarm to execute'
+        required: true
+        type: string
+
+jobs:
+  swarm:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'issue_comment' &&
+       contains(github.event.comment.body, '@swarm'))
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kingjulio8238/swarm-code@main
+        with:
+          task: ${{ github.event.inputs.task || '' }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          max_budget: '5.00'
+```
+
+Then comment on any issue:
+
+```
+@swarm fix the auth bug in src/auth.ts
+```
+
+Swarm runs, creates a PR with the changes, and posts a summary back on the issue.
+
+**Security**: Only OWNER/MEMBER/COLLABORATOR can trigger. Fork PRs are rejected. Budget hard cap of $50. API keys are masked in logs.
+
+**Action inputs**: `task`, `anthropic_api_key`, `openai_api_key`, `gemini_api_key`, `agent`, `model`, `max_budget`
+
+**Action outputs**: `success`, `pr_url`, `cost_usd`, `threads_completed`, `threads_failed`, `elapsed_s`, `answer`, `skipped`, `skip_reason`
+
+### MCP Server
+
+Expose swarm as tools for Claude Code, Cursor, or any MCP-compatible agent:
+
+```bash
+swarm mcp                       # Start MCP server (stdio)
+swarm mcp --dir ./my-project    # Start with default directory
+```
+
+**Tools exposed:**
+
+| Tool | Description |
+|------|-------------|
+| `swarm_run` | Full swarm orchestration — decompose, spawn threads, merge, return result |
+| `swarm_thread` | Spawn a single coding agent in an isolated worktree |
+| `swarm_status` | Get session status — threads, budget, costs |
+| `swarm_merge` | Merge completed thread branches back to main |
+| `swarm_cancel` | Cancel running thread(s) |
+| `swarm_cleanup` | Destroy session and clean up worktrees |
+
+**Claude Code setup:**
+
+```bash
+claude mcp add swarm-code -- npx swarm-code mcp
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "swarm-code": {
+      "command": "npx",
+      "args": ["swarm-code", "mcp", "--dir", "."],
+      "env": {
+        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Cursor setup:** Add to `.cursor/mcp.json` with the same format.
+
+Once configured, Claude Code or Cursor can call `swarm_thread` to spawn coding agents in worktrees, check progress with `swarm_status`, and merge with `swarm_merge` — giving the host agent full orchestration control.
+
+### Trajectory Viewer
+
+```bash
+swarm viewer
+```
+
+Browse saved runs in a TUI. View iterations, code, output, sub-queries, and swarm thread DAGs with timing bars and cost breakdowns. Arrow keys to navigate, Enter to drill down into thread details.
+
+### Benchmarks
+
+```bash
+swarm benchmark oolong          # Oolong Synth long-context benchmark
+swarm benchmark longbench       # LongBench NarrativeQA benchmark
+```
+
+## How It Works
+
+1. **Scan**: Codebase is scanned and loaded as context
+2. **Orchestrate**: The RLM loop runs — the LLM writes Python code using swarm primitives
+3. **Decompose**: Tasks are broken into independent, parallelizable units
+4. **Spawn**: `thread()` / `async_thread()` spawn coding agents in isolated git worktrees
+5. **Compress**: Agent output is filtered to successful operations only (episode quality)
+6. **Merge**: `merge_threads()` integrates worktree branches back to main
+7. **Verify**: Optional test thread validates the merged result
+
+### Python Primitives
+
+```python
+# Lightweight LLM query (no file changes)
+analysis = llm_query(context[:5000], "List all API endpoints")
+
+# Spawn a coding agent in an isolated worktree
+result = thread("Fix the auth bug", files=["src/auth.ts"])
+
+# Parallel threads
+import asyncio
+results = await asyncio.gather(
+    async_thread("Add validation to POST /users", files=["src/routes/users.ts"]),
+    async_thread("Add validation to POST /orders", files=["src/routes/orders.ts"]),
+)
+
+# Merge all thread branches back to main
+merge_threads()
+
+# Return final answer
+FINAL("Added input validation to all API routes")
+```
+
+### Thread DAG Composition
+
+Thread results compose naturally via Python variable persistence:
+
+```python
+# Stage 1: Research in parallel
+analysis, test_gaps = await asyncio.gather(
+    async_thread("Analyze the auth module", files=["src/auth/"]),
+    async_thread("Find files with <50% coverage", files=["package.json"]),
+)
+
+# Stage 2: Act on Stage 1 results
+await asyncio.gather(
+    async_thread("Add rate limiting", context=analysis, files=["src/auth/middleware.ts"]),
+    async_thread("Add tests for low-coverage files", context=test_gaps),
+)
+
+# Stage 3: Merge and validate
+merge_threads()
+thread("Run full test suite and fix failures")
+```
+
+## Configuration
+
+Create `swarm_config.yaml` in your project root:
+
+```yaml
+# Concurrency
+max_threads: 5                    # Max concurrent threads
+max_total_threads: 20             # Max threads per session
+thread_timeout_ms: 300000         # 5min per thread
+
+# Budget
+max_thread_budget_usd: 1.00      # Per-thread cost cap
+max_session_budget_usd: 10.00    # Total session cost cap
+
+# Agent
+default_agent: opencode           # opencode, claude-code, codex, aider, direct-llm
+default_model: anthropic/claude-sonnet-4-6
+auto_model_selection: false       # Enable auto-routing
+
+# Compression
+compression_strategy: structured  # structured, diff-only, truncate, llm-summary
+
+# Model slots — override model per task type
+# model_slot_execution: anthropic/claude-sonnet-4-6
+# model_slot_search: anthropic/claude-haiku-4-5
+# model_slot_reasoning: anthropic/claude-opus-4-6
+# model_slot_planning: anthropic/claude-opus-4-6
+
+# Episodic memory — cross-session strategy learning
+episodic_memory_enabled: false
+memory_dir: ~/.swarm/memory
+
+# Thread cache persistence
+thread_cache_persist: false
+thread_cache_dir: ~/.swarm/cache
+thread_cache_ttl_hours: 24
+```
+
+## Key Optimizations
+
+- **Episode quality**: Compression filters agent output to only successful operations — failed attempts, stack traces, and retries are stripped automatically
+- **Subthread caching**: Identical threads (same task + files + agent + model) are cached in-memory with optional disk persistence and TTL expiry
+- **Named model slots**: Tasks auto-classified into execution/search/reasoning/planning slots, each with preferred agents and optional model overrides
+- **Episodic memory**: Persists successful thread strategies to disk; trigram-based similarity recall informs agent/model selection in future sessions
+- **DAG composition**: Thread results compose via Python variable persistence (T1+T2 → T3); orchestrator prompt teaches multi-stage pipelines and failure re-routing
+- **Failure tracking**: Exponential-decay weighted failure rates per agent/model pair — recent failures penalized more, agents that keep failing get routed around
+
+## Architecture
+
+```
+src/
+├── main.ts                    CLI entry point (swarm/run/viewer/benchmark)
+├── swarm.ts                   Swarm orchestration (single-shot)
+├── interactive-swarm.ts       Interactive REPL with live monitoring
+├── cli.ts                     RLM text mode
+├── core/
+│   ├── rlm.ts                 Core RLM loop (Algorithm 1)
+│   ├── repl.ts                Python REPL bridge (JSON over stdin/stdout)
+│   ├── runtime.py             Python runtime (thread/async_thread/merge)
+│   └── types.ts               Shared type definitions
+├── agents/
+│   ├── provider.ts            AgentProvider interface + registry
+│   ├── opencode.ts            OpenCode (subprocess + server mode)
+│   ├── claude-code.ts         Claude Code CLI backend
+│   ├── codex.ts               Codex CLI backend
+│   ├── aider.ts               Aider backend
+│   └── direct-llm.ts          Bare LLM calls
+├── threads/
+│   ├── manager.ts             Thread lifecycle + concurrency + episodes
+│   └── cache.ts               Subthread cache (memory + disk)
+├── worktree/
+│   ├── manager.ts             Git worktree CRUD
+│   └── merge.ts               Branch merging
+├── compression/
+│   └── compressor.ts          Result compression strategies
+├── routing/
+│   └── model-router.ts        Auto model/agent selection + failure tracking
+├── memory/
+│   └── episodic.ts            Cross-session strategy learning
+├── prompts/
+│   └── orchestrator.ts        Swarm system prompt
+├── mcp/
+│   ├── server.ts              MCP server entry point (stdio transport)
+│   ├── tools.ts               Tool definitions + handlers
+│   └── session.ts             Per-directory session state
+├── ui/
+│   ├── onboarding.ts          First-run setup wizard
+│   ├── spinner.ts             CLI spinner
+│   ├── dashboard.ts           Live progress dashboard
+│   └── summary.ts             Session summary + JSON output
+└── viewer.ts                  Trajectory TUI + DAG viewer
+action/
+├── entrypoint.ts              GitHub Action orchestration
+├── parse-trigger.ts           @swarm comment parsing
+├── security.ts                Auth + fork detection + budget caps
+└── pr.ts                      PR creation + issue commenting
+```
+
+## Development
+
+```bash
+npm install                    # Install deps
+npx tsx src/main.ts --dir .    # Run in dev mode
+npm run build                  # Compile TypeScript
+npm test                       # Run tests
+```
+
+## License
+
+MIT

package/bin/swarm.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+/**
+ * swarm — Swarm-Native Coding Agent CLI
+ *
+ * This shim boots the CLI entry point. It tries the compiled dist first,
+ * then falls back to tsx for development.
+ */
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(__dirname, "..", "dist", "main.js");
+
+if (existsSync(distEntry)) {
+	// Production: use compiled JS (pathToFileURL needed for Windows)
+	await import(pathToFileURL(distEntry).href);
+} else {
+	// Development: use tsx to run TypeScript directly
+	const srcEntry = join(__dirname, "..", "src", "main.ts");
+	const { register } = await import("node:module");
+
+	// Try to register tsx loader, then import
+	try {
+		const tsxPath = join(__dirname, "..", "node_modules", "tsx", "dist", "esm", "index.mjs");
+		if (existsSync(tsxPath)) {
+			register(pathToFileURL(tsxPath).href);
+		}
+		await import(pathToFileURL(srcEntry).href);
+	} catch {
+		// Fallback: spawn tsx as a child process
+		const { spawn } = await import("node:child_process");
+		const tsxBin = join(__dirname, "..", "node_modules", ".bin", "tsx");
+		const child = spawn(tsxBin, [srcEntry, ...process.argv.slice(2)], {
+			stdio: "inherit",
+		});
+		child.on("exit", (code) => process.exit(code ?? 1));
+		child.on("error", (err) => {
+			console.error(`Failed to start swarm: ${err.message}`);
+			process.exit(1);
+		});
+	}
+}

package/dist/agents/aider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Aider agent backend.
+ *
+ * Runs tasks via `aider --yes-always --no-auto-commits --message "prompt"` subprocess.
+ * Aider is a git-aware AI coding assistant that makes targeted edits.
+ *
+ * Output format: Plain text (no JSON mode available).
+ * Edit confirmations appear as "Applied edit to <file>" lines.
+ */
+import type { AgentProvider } from "../core/types.js";
+declare const aiderProvider: AgentProvider;
+export default aiderProvider;

package/dist/agents/aider.js

@@ -0,0 +1,182 @@
+/**
+ * Aider agent backend.
+ *
+ * Runs tasks via `aider --yes-always --no-auto-commits --message "prompt"` subprocess.
+ * Aider is a git-aware AI coding assistant that makes targeted edits.
+ *
+ * Output format: Plain text (no JSON mode available).
+ * Edit confirmations appear as "Applied edit to <file>" lines.
+ */
+import { spawn } from "node:child_process";
+import * as os from "node:os";
+import { registerAgent } from "./provider.js";
+async function commandExists(cmd) {
+    return new Promise((resolve) => {
+        const proc = spawn("which", [cmd], { stdio: "pipe" });
+        proc.on("close", (code) => resolve(code === 0));
+        proc.on("error", () => resolve(false));
+    });
+}
+/** Whitelist of env vars safe to pass to agent subprocess. */
+function buildAgentEnv() {
+    const homeDir = os.homedir();
+    return {
+        PATH: process.env.PATH,
+        HOME: homeDir,
+        USERPROFILE: homeDir,
+        SHELL: process.env.SHELL,
+        TERM: process.env.TERM,
+        LANG: process.env.LANG,
+        // Aider supports multiple providers via these keys
+        ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+        OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+        GEMINI_API_KEY: process.env.GEMINI_API_KEY,
+        // Aider-specific env vars
+        AIDER_MODEL: process.env.AIDER_MODEL,
+        AIDER_DARK_MODE: process.env.AIDER_DARK_MODE,
+        // Git config
+        GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME,
+        GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL,
+        GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME,
+        GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL,
+        // Python (aider is Python-based)
+        VIRTUAL_ENV: process.env.VIRTUAL_ENV,
+        CONDA_DEFAULT_ENV: process.env.CONDA_DEFAULT_ENV,
+        PYTHONPATH: process.env.PYTHONPATH,
+        // Windows
+        ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+        ...(process.env.SYSTEMROOT ? { SYSTEMROOT: process.env.SYSTEMROOT } : {}),
+    };
+}
+/** Map provider/model format to aider model flag. */
+function resolveModel(model) {
+    // Aider accepts provider/model format natively (e.g., "anthropic/claude-sonnet-4-6")
+    // It also has short aliases: sonnet, opus, haiku, 4o, etc.
+    return model;
+}
+/** Parse aider output to extract edited file paths. */
+function extractFilesChanged(output) {
+    const files = [];
+    // Aider outputs lines like:
+    //   "Applied edit to src/auth.ts"
+    //   "Wrote src/auth.ts"
+    //   "Committing src/auth.ts ..."
+    //   "Created new file src/utils.ts"
+    const patterns = [
+        /Applied edit to\s+(.+?)(?:\s*$)/gm,
+        /Wrote\s+(.+?)(?:\s*$)/gm,
+        /Committing\s+(.+?)(?:\s+\.\.\.|\s*$)/gm,
+        /(?:Created|Added)\s+new file\s+(.+?)(?:\s*$)/gm,
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(output)) !== null) {
+            const file = match[1].trim();
+            if (file) {
+                files.push(file);
+            }
+        }
+    }
+    return [...new Set(files)];
+}
+const aiderProvider = {
+    name: "aider",
+    async isAvailable() {
+        return commandExists("aider");
+    },
+    async run(options) {
+        const { task, workDir, model, files, signal } = options;
+        const startTime = Date.now();
+        const args = [
+            "--yes-always", // Auto-confirm all prompts (except shell commands)
+            "--no-auto-commits", // Don't auto-commit (worktree manager handles commits)
+            "--no-pretty", // Disable ANSI colors for clean parsing
+            "--no-stream", // Don't stream (capture full output)
+            "--no-fancy-input", // Disable prompt toolkit input
+            "--no-suggest-shell-commands", // Suppress shell command suggestions
+            "--no-detect-urls", // Suppress URL detection prompts
+        ];
+        if (model) {
+            args.push("--model", resolveModel(model));
+        }
+        // Pass the task via --message (non-interactive mode)
+        args.push("--message", task);
+        // Add specific files to edit if provided
+        if (files && files.length > 0) {
+            for (const file of files) {
+                args.push("--file", file);
+            }
+        }
+        return new Promise((resolve) => {
+            const proc = spawn("aider", args, {
+                cwd: workDir,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: buildAgentEnv(),
+            });
+            let stdout = "";
+            let stderr = "";
+            let resolved = false;
+            const doResolve = (result) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(result);
+            };
+            proc.stdout?.on("data", (chunk) => {
+                const text = chunk.toString();
+                stdout += text;
+                options.onOutput?.(text);
+            });
+            proc.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString();
+            });
+            if (signal) {
+                const onAbort = () => {
+                    proc.kill("SIGTERM");
+                    const killTimer = setTimeout(() => {
+                        try {
+                            if (proc.exitCode === null)
+                                proc.kill("SIGKILL");
+                        }
+                        catch {
+                            /* already dead */
+                        }
+                    }, 3000);
+                    proc.on("exit", () => clearTimeout(killTimer));
+                };
+                if (signal.aborted) {
+                    onAbort();
+                }
+                else {
+                    signal.addEventListener("abort", onAbort, { once: true });
+                    proc.on("exit", () => signal.removeEventListener("abort", onAbort));
+                }
+            }
+            proc.on("close", (code) => {
+                const durationMs = Date.now() - startTime;
+                const filesChanged = extractFilesChanged(stdout);
+                doResolve({
+                    success: code === 0,
+                    output: stdout || stderr,
+                    filesChanged,
+                    diff: "", // Diff is captured separately by worktree manager
+                    durationMs,
+                    error: code !== 0 ? `aider exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}` : undefined,
+                });
+            });
+            proc.on("error", (err) => {
+                doResolve({
+                    success: false,
+                    output: "",
+                    filesChanged: [],
+                    diff: "",
+                    durationMs: Date.now() - startTime,
+                    error: `Failed to spawn aider: ${err.message}`,
+                });
+            });
+        });
+    },
+};
+registerAgent(aiderProvider);
+export default aiderProvider;
+//# sourceMappingURL=aider.js.map

package/dist/agents/claude-code.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Claude Code agent backend.
+ *
+ * Runs tasks via `claude -p --output-format json "prompt"` subprocess.
+ * Parses structured JSON output for results, cost, and file changes.
+ */
+import type { AgentProvider } from "../core/types.js";
+declare const claudeCodeProvider: AgentProvider;
+export default claudeCodeProvider;