bullswarm 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bullswarm contributors
+
+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,67 @@
+# bullswarm
+
+Route work across coding-agent CLIs. The frontier agent keeps orchestration,
+judgment, and synthesis; bounded work goes to whichever subscription has the
+most quota left; every delegate output is judged by content before it counts.
+
+## The doctrine (non-negotiable)
+
+1. **Judge by CONTENT, not exit code.** Every delegate CLI can exit 0 while
+   having done nothing. A non-zero exit is never a success; `ok:true` requires
+   passing verification.
+2. **Pace by meter.** The scheduling resource is the subscription window:
+   elapsed% minus used%, most-behind pool wins. Pace may only promote a
+   *cheaper* pool. Lanes are work-nature, never hard-coded to pools.
+3. **Delegate output is input, never the answer.** Final synthesis,
+   architecture decisions, and anything needing live conversation context
+   stays with the caller.
+4. **Quarantine re-probes.** A benched pool must be able to return to service
+   automatically; a lane is never allowed to silently go down.
+
+## Install
+
+```bash
+npm install -g bullswarm   # or: node bin/bullswarm.js directly from a checkout
+```
+
+## Quick start
+
+```bash
+bullswarm          # first run: interactive setup wizard
+bullswarm setup    # re-run or repair
+bullswarm pools    # meter state, pace position, quarantine status
+bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
+bullswarm health   # re-judge saved outputs; catch gate failures
+```
+
+## Verbs
+
+| Verb | Purpose |
+|---|---|
+| `setup` | Discover installed agent CLIs, show quota state, toggle pools, suggest a routing table, write config. Approval-gated, idempotent. |
+| `run` | route → dispatch → watch → verify → one JSON verdict |
+| `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
+| `pools` | Show each pool's meter state, pace position, quarantine status |
+
+## The verdict
+
+```json
+{
+  "ok": true,
+  "keepOnClaude": false,
+  "why": "verified",
+  "pick": { "pool": "grok", "command": ["grok", "-p", "..."] },
+  "contentUsableDespiteExit": false,
+  "outFile": "/tmp/dlg.out"
+}
+```
+
+- `ok: true` — verified output, read the file
+- `keepOnClaude: true` — router says do it in-session; nothing ran
+- `ok: false` — `why` names the failed gate
+- `contentUsableDespiteExit: true` — non-zero exit but complete output; read
+  before re-running
+
+## License
+
+MIT

package/bin/bullswarm.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// bullswarm — route work across coding-agent CLI subscriptions.
+
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err?.message ?? err);
+    process.exit(1);
+  },
+);

package/connectors/_schema.json

@@ -0,0 +1,31 @@
+{
+  "$comment": "Connector schema. Every per-CLI quirk lives HERE, never in core logic.",
+  "name": "connector-name (matches pool name)",
+  "bin": "binary on PATH to probe for discovery",
+  "configDirs": ["~/.example", "~/.config/example"],
+  "spawn": {
+    "$comment": "argv template; {taskFile} {cwd} {outFile} are substituted",
+    "cmd": ["example-cli", "--task", "{taskFile}"],
+    "cwdMode": "add-dir|task-file-dir",
+    "$comment-cwd": "cwdMode documents how the CLI resolves its project: 'pwd' means the CLI resolves from $PWD so the watcher MUST set PWD and spawn inside --add-dir"
+  },
+  "authSignatures": ["strings in output that mean auth/throttle failure"],
+  "outputExtraction": {
+    "$comment": "how to get the real answer out of stdout+stderr+files",
+    "strategy": "stdout|stdout-tail|json-field|file",
+    "field": "optional json field path or file glob"
+  },
+  "meter": {
+    "$comment": "none | declared (manual) | reader (programmatic)",
+    "type": "none|declared|reader",
+    "window": "5h|weekly|none (for declared/reader)",
+    "readerCmd": "optional command emitting usedPct as JSON"
+  },
+  "costRank": 2,
+  "lanes": ["analyze", "build", "chore"],
+  "flags": {
+    "stealth": false,
+    "$comment-stealth": "stealth=true: prompts/completions retained by an anonymous provider — opt-in only, never a default"
+  },
+  "timeoutSec": 900
+}

package/connectors/claude-code.json

@@ -0,0 +1,17 @@
+{
+  "name": "claude-code",
+  "bin": "claude",
+  "configDirs": ["~/.claude"],
+  "spawn": {
+    "cmd": ["claude", "-p", "Read the file {taskFile} and follow its instructions exactly.", "--add-dir", "{cwd}", "--no-session"],
+    "cwdMode": "add-dir"
+  },
+  "authSignatures": ["unauthorized", "authentication failed", "credit balance"],
+  "outputExtraction": { "strategy": "stdout" },
+  "$comment-meter": "the CALLER pool — competes in analyze/build, wins only when no delegate can take the lane",
+  "meter": { "type": "reader", "window": "weekly+5h" },
+  "costRank": 4,
+  "lanes": ["analyze", "build", "chore"],
+  "flags": { "stealth": false },
+  "timeoutSec": 900
+}

package/connectors/codex.json

@@ -0,0 +1,41 @@
+{
+  "name": "codex",
+  "bin": "codex",
+  "configDirs": [
+    "~/.codex"
+  ],
+  "spawn": {
+    "cmd": [
+      "codex",
+      "exec",
+      "--skip-git-repo-check",
+      "--add-dir",
+      "{cwd}",
+      "Read {taskFile} and follow the instructions."
+    ],
+    "cwdMode": "add-dir",
+    "$comment-argv": "{cwd} is substituted by the watcher with the resolved target directory"
+  },
+  "authSignatures": [
+    "usage_credits_required",
+    "unauthorized",
+    "invalid api key"
+  ],
+  "outputExtraction": {
+    "strategy": "stdout"
+  },
+  "meter": {
+    "type": "reader",
+    "window": "weekly"
+  },
+  "costRank": 3,
+  "lanes": [
+    "analyze",
+    "build",
+    "chore"
+  ],
+  "flags": {
+    "stealth": false
+  },
+  "timeoutSec": 900
+}

package/connectors/command-code.json

@@ -0,0 +1,39 @@
+{
+  "name": "command-code",
+  "bin": "command-code",
+  "configDirs": [
+    "~/.commandcode"
+  ],
+  "spawn": {
+    "cmd": [
+      "command-code",
+      "-p",
+      "--no-session",
+      "--tools-all",
+      "--yolo",
+      "Read the file {taskFile} and follow its instructions exactly."
+    ],
+    "cwdMode": "add-dir"
+  },
+  "authSignatures": [
+    "unauthorized",
+    "authentication failed"
+  ],
+  "outputExtraction": {
+    "strategy": "stdout"
+  },
+  "meter": {
+    "type": "reader",
+    "window": "weekly+monthly+5h"
+  },
+  "costRank": 1,
+  "lanes": [
+    "build",
+    "chore"
+  ],
+  "$comment-lanes": "cannot serve analyze (upstream 403 on the frontier model)",
+  "flags": {
+    "stealth": false
+  },
+  "timeoutSec": 900
+}

package/connectors/echo-worker.mjs

@@ -0,0 +1,38 @@
+// echo-worker.mjs — deterministic test delegate for bullswarm.
+// Reads a task file; behavior is driven by directives in the task text.
+//   FAIL:auth   -> prints an auth failure, exits 0 (the lying-exit trap)
+//   FAIL:exit   -> prints a complete answer, exits 1 (exit-1-after-success)
+//   INTENT:     -> prints only an announcement, exits 0
+//   otherwise   -> echoes the task as a completed answer, exit 0
+
+import { readFileSync } from 'node:fs';
+
+const task = readFileSync(process.argv[2], 'utf8');
+
+if (task.includes('FAIL:auth')) {
+  console.log('Authentication failed: no credentials found in keychain.');
+  process.exit(0);
+}
+if (task.includes('FAIL:exit')) {
+  console.log(
+    'Refactor complete.\n\n- Renamed getUser to fetchUser across 12 files (grep-verified: zero remaining references).\n- All 47 tests pass. Files touched: src/api/user.ts, src/api/index.ts, src/hooks/useUser.ts, and 9 test files.',
+  );
+  process.exit(1);
+}
+if (task.includes('INTENT:')) {
+  console.log(
+    "I'll inspect log.ts and tail.ts, then trace the rotation path through the config loader. I'll report back with the root cause.",
+  );
+  process.exit(0);
+}
+if (task.includes('PWD:')) {
+  console.log(
+    `## Working directory report\n\nThe delegate process resolved its project context from the following locations, captured immediately at spawn time:\n\n- PWD environment variable: ${process.env.PWD ?? '(unset)'}\n- getcwd() / process.cwd(): ${process.cwd()}\n\nBoth values agree, confirming the launcher set the working directory correctly for this run.`,
+  );
+  process.exit(0);
+}
+
+console.log(
+  `## Completed\n\nProcessed the task file successfully.\n\n- Read and executed every directive found in ${process.argv[2]}.\n- Verified the output directory exists and is writable before writing.\n- Ran the full local validation suite: all checks passed with exit code 0.\n\nNo errors were encountered during the run.`,
+);
+process.exit(0);

package/connectors/echo.json

@@ -0,0 +1,16 @@
+{
+  "name": "echo",
+  "bin": "node",
+  "configDirs": [],
+  "spawn": {
+    "cmd": ["node", "{bullswarmDir}/connectors/echo-worker.mjs", "{taskFile}"],
+    "cwdMode": "task-file-dir"
+  },
+  "authSignatures": ["Authentication failed", "unauthorized"],
+  "outputExtraction": { "strategy": "stdout" },
+  "meter": { "type": "none" },
+  "costRank": 5,
+  "lanes": ["analyze", "build", "chore"],
+  "flags": { "stealth": false },
+  "timeoutSec": 120
+}

package/connectors/grok.json

@@ -0,0 +1,38 @@
+{
+  "name": "grok",
+  "bin": "grok",
+  "configDirs": [
+    "~/.grok"
+  ],
+  "spawn": {
+    "cmd": [
+      "grok",
+      "-p",
+      "{taskFile}"
+    ],
+    "cwdMode": "add-dir"
+  },
+  "authSignatures": [
+    "unauthorized",
+    "rate limit",
+    "invalid api key"
+  ],
+  "outputExtraction": {
+    "strategy": "stdout"
+  },
+  "meter": {
+    "type": "reader",
+    "window": "weekly"
+  },
+  "costRank": 2,
+  "lanes": [
+    "analyze",
+    "build",
+    "chore"
+  ],
+  "flags": {
+    "stealth": false
+  },
+  "timeoutSec": 900,
+  "$comment-meter": "weekly shared credit pool via billing endpoint; no 5h window exists on unified-billing accounts"
+}

package/connectors/opencode2.json

@@ -0,0 +1,18 @@
+{
+  "name": "opencode2",
+  "bin": "opencode",
+  "configDirs": ["~/.config/opencode"],
+  "spawn": {
+    "cmd": ["opencode", "run", "{taskFile}"],
+    "cwdMode": "pwd",
+    "$comment-cwdMode": "QUIRK: resolves its project from $PWD, not the spawn cwd. The watcher MUST set env.PWD and spawn with cwd inside the target repo, or it will silently analyse the wrong repository and answer confidently about it."
+  },
+  "authSignatures": ["No cookie auth credentials found", "unauthorized"],
+  "outputExtraction": { "strategy": "stdout" },
+  "$comment-exit1": "known failure mode: writes a complete correct answer, then dies with a Console-sync auth error and exit 1. The verdict sets contentUsableDespiteExit instead of discarding the work.",
+  "meter": { "type": "none" },
+  "costRank": 1,
+  "lanes": ["analyze", "build", "chore"],
+  "flags": { "stealth": false },
+  "timeoutSec": 900
+}

package/mcp/server.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// bullswarm MCP server — exposes run/health/pools over stdio JSON-RPC 2.0.
+// One implementation; every MCP client (Claude Code, Codex, Cursor, …)
+// can offload without shell plumbing.
+
+import { createInterface } from 'node:readline';
+import { main } from '../src/cli.js';
+import { getVersion } from '../src/lib/version.js';
+
+const VERSION = getVersion();
+
+const TOOLS = [
+  {
+    name: 'bullswarm_run',
+    description:
+      'Offload a task to the best available coding-agent pool, routed by quota pace and verified by content. Returns a verdict: ok=true means read outFile; keepOnClaude=true means do it in-session; ok=false means the why field names the failed gate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        lane: { type: 'string', enum: ['analyze', 'build', 'chore'] },
+        task: { type: 'string', description: 'The task text to delegate.' },
+        addDir: { type: 'string', description: 'Target repository directory.' },
+        timeout: { type: 'number' },
+      },
+      required: ['lane', 'task'],
+    },
+  },
+  {
+    name: 'bullswarm_health',
+    description:
+      'Re-judge saved offload outputs against their verdicts; report verify-gate failures and quarantine clusters. Run after every offload round.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'bullswarm_pools',
+    description: 'Show each pool meter state, pace position, and quarantine status.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function write(msg) {
+  process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+
+function result(id, r) {
+  write({ jsonrpc: '2.0', id, result: r });
+}
+
+async function callTool(name, args) {
+  // Reuse the CLI verbs but capture stdout instead of leaking to our protocol
+  // stream: swap console.log for the duration of the call.
+  const chunks = [];
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = (...a) => chunks.push(a.join(' '));
+  console.error = () => {};
+  try {
+    const argv =
+      name === 'bullswarm_run'
+        ? [
+            'run',
+            '--lane',
+            args.lane,
+            '--json',
+            ...(args.addDir ? ['--add-dir', args.addDir] : []),
+            ...(args.timeout ? ['--timeout', String(args.timeout)] : []),
+            ...args.task.split(' '),
+          ]
+        : name === 'bullswarm_health'
+          ? ['health']
+          : ['pools', '--json'];
+    const code = await main(argv);
+    let parsed = null;
+    try {
+      parsed = JSON.parse(chunks.join('\n'));
+    } catch {
+      parsed = chunks.join('\n');
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ exitCode: code, verdict: parsed }, null, 2) }] };
+  } finally {
+    console.log = origLog;
+    console.error = origErr;
+  }
+}
+
+function handleMessage(line) {
+  if (!line.trim()) return;
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case 'initialize':
+      result(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'bullswarm', version: VERSION },
+      });
+      break;
+    case 'notifications/initialized':
+      break; // no response for notifications
+    case 'tools/list':
+      result(id, { tools: TOOLS });
+      break;
+    case 'tools/call':
+      callTool(params.name, params.arguments ?? {})
+        .then((r) => id != null && result(id, r))
+        .catch((err) =>
+          id != null &&
+          write({
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32603, message: err?.message ?? 'internal error' },
+          }),
+        );
+      break;
+    case 'ping':
+      result(id, {});
+      break;
+    default:
+      if (id != null) {
+        write({
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        });
+      }
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', handleMessage);
+rl.on('close', () => process.exit(0));

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "bullswarm",
+  "version": "0.1.4",
+  "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
+  "type": "module",
+  "bin": {
+    "bullswarm": "./bin/bullswarm.js",
+    "bullswarm-mcp": "./mcp/server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "connectors/",
+    "skill/",
+    "mcp/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"tests/*.test.js\"",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cowcow02/bullswarm.git"
+  },
+  "homepage": "https://github.com/cowcow02/bullswarm#readme",
+  "bugs": {
+    "url": "https://github.com/cowcow02/bullswarm/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "orchestration",
+    "claude",
+    "codex",
+    "grok",
+    "opencode",
+    "quota",
+    "routing",
+    "mcp"
+  ],
+  "author": "cowcow02",
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bullswarm-setup
+description: Use when the user wants to offload work to other coding-agent subscriptions, asks about bullswarm, or wants quota-aware routing across agent CLIs. Guides the user to run the bullswarm setup wizard, which discovers installed agent CLIs, shows quota state, and configures routing.
+---
+
+# bullswarm setup companion
+
+You are a guide, not the installer. The CLI owns the flow; you nudge.
+
+## When to use
+
+- The user asks to route/offload work to other agent CLIs (codex, grok, opencode, etc.)
+- The user mentions quota exhaustion on one subscription while others sit idle
+- The user asks what bullswarm is or how to set it up
+
+## What to do
+
+1. Check whether bullswarm is configured:
+
+   ```bash
+   ls ~/.bullswarm/state.json 2>/dev/null && echo configured || echo not-configured
+   ```
+
+2. If **not-configured**, tell the user:
+
+   > bullswarm routes work across your installed coding-agent CLIs, paced by
+   > each subscription's quota window, and verifies every delegate's output
+   > by content before trusting it. Run `bullswarm` (bare) to start the
+   > setup wizard — it discovers your installed agent CLIs, shows their
+   > quota state, and lets you pick which pools to enable. No credentials
+   > are entered anywhere; it only reads what's already on your machine.
+
+   Then offer: "Want me to run `bullswarm setup` for you now?"
+
+3. If **configured**, surface the current state:
+
+   ```bash
+   bullswarm pools
+   ```
+
+   and remind them of the daily habit:
+
+   > After every offload round, run `bullswarm health` — it re-judges saved
+   > outputs against their verdicts and catches verify-gate failures that
+   > would otherwise be invisible.
+
+## Hard rules
+
+- NEVER edit `~/.bullswarm/` state directly; the CLI owns it.
+- NEVER bypass the wizard's approval gates by writing CLAUDE.md/AGENTS.md
+  blocks yourself — direct the user through `bullswarm setup` so the diff is
+  shown and approved.
+- Delegate output is input to verify, never the answer you present.