@swarp/cli 0.0.4 → 0.1.0-rc.34

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "swarp",
+  "version": "0.1.0",
+  "description": "Agent orchestration platform — deploy remote Claude agents",
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "swarp": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/src/mcp-server/index.mjs"]
+    }
+  }
+}

package/hooks/confirm-cost.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+if [ -z "$TOOL_NAME" ]; then
+  jq -n '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"block","permissionDecisionReason":"Could not determine tool name."}}' >&2
+  exit 1
+fi
+
+make_decision() {
+  local decision="$1"
+  local reason="$2"
+  jq -n \
+    --arg d "$decision" \
+    --arg r "$reason" \
+    '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":$d,"permissionDecisionReason":$r}}'
+}
+
+case "$TOOL_NAME" in
+  *swarp_deploy_router)
+    COST_INFO="Fly Machine (shared-cpu-1x, 256MB): ~\$1.94/mo + 1GB volume: ~\$0.15/mo + shared IPv4: \$0/mo. Total: ~\$2.09/mo."
+    make_decision "ask" "This will create a Fly Machine + volume. $COST_INFO Billed to your Fly.io account."
+    ;;
+
+  *swarp_deploy)
+    AGENT=$(echo "$INPUT" | jq -r '.tool_input.agent // "unknown"')
+    make_decision "ask" "This will create a Fly Sprite for agent '$AGENT'. Sprites cost ~\$0.007/min while running (paused when idle). A typical 30-min session costs ~\$0.21. Billed to your Fly.io account."
+    ;;
+
+  *swarp_destroy)
+    AGENT=$(echo "$INPUT" | jq -r '.tool_input.agent // "unknown"')
+    make_decision "ask" "This will PERMANENTLY destroy the sprite for agent '$AGENT'. Lost: runner process state, session files on sprite. Agent config (agent.yaml) is preserved locally. This cannot be undone."
+    ;;
+
+  *)
+    make_decision "ask" "Unknown destructive action: $TOOL_NAME. Proceed with caution."
+    ;;
+esac

package/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__swarp__swarp_deploy_router",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/confirm-cost.sh" }]
+      },
+      {
+        "matcher": "mcp__swarp__swarp_deploy",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/confirm-cost.sh" }]
+      },
+      {
+        "matcher": "mcp__swarp__swarp_destroy",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/confirm-cost.sh" }]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarp/cli",
-  "version": "0.0.4",
+  "version": "0.1.0-rc.34",
   "description": "SWARP agent orchestration platform — CLI, MCP server, generator",
   "type": "module",
   "bin": {
@@ -15,12 +15,14 @@
     "./runtimes/fly-sprites": "./src/runtimes/fly-sprites.mjs"
   },
   "files": [
+    ".claude-plugin/",
+    ".mcp.json",
+    "hooks/",
+    "skills/",
     "bin/",
-    "src/",
-    "proto/"
+    "src/"
   ],
   "scripts": {
-    "prepack": "mkdir -p proto/swarp/v1 && cp ../proto/swarp/v1/swarp.proto proto/swarp/v1/",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/skills/swarp/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: swarp
+description: Agent orchestration — setup, create agents, deploy, manage. Use when user says /swarp, asks about agents, wants to deploy or manage remote Claude agents.
+---
+
+# /swarp
+
+SWARP deploys remote Claude agents on Fly Sprites, orchestrated through a central gRPC router.
+
+## First Run
+
+If the user runs `/swarp` or asks about setting up agents, call the `swarp_onboard` tool with no arguments. It will tell you the current setup status and what to do next. Follow its instructions exactly.
+
+The onboard tool manages a 4-phase workflow:
+
+1. **Prerequisites** — checks flyctl, sprite, gh CLIs are installed
+2. **Router** — deploys the SWARP router to Fly.io (requires user cost approval)
+3. **Secrets** — guides setting GitHub repo secrets for CI
+4. **First Agent** — creates and deploys the first agent
+
+Each phase must complete before the next can start. The tool enforces this — do not try to skip phases.
+
+## Commands
+
+### `/swarp` (no arguments)
+
+Call `swarp_onboard` with action `status`. Show the result to the user.
+
+### `/swarp create <name>`
+
+Help the user create an agent. Ask:
+
+1. What should this agent do? (natural language description)
+2. What model should it use? (suggest Haiku for fast/cheap, Sonnet for balanced, Opus for complex)
+3. Any specific tools it should have access to?
+
+Generate `agents/<name>/agent.yaml` with appropriate modes based on the answers. Use the Write tool to create the file.
+
+### `/swarp deploy <name>`
+
+Call the `swarp_deploy` MCP tool with the agent name. This triggers a cost confirmation prompt — the user must approve before infrastructure is created.
+
+### `/swarp deploy --all`
+
+Deploy all agents found in the agents directory. Call `swarp_deploy` for each one. Each triggers its own cost confirmation.
+
+### `/swarp destroy <name>`
+
+Call the `swarp_destroy` MCP tool with the agent name. This triggers a confirmation prompt warning about data loss.
+
+### `/swarp status`
+
+Call `swarm_status` MCP tool (no arguments for all agents, or with agent name for one).
+
+## Agent YAML Format
+
+When creating agents, generate YAML like this:
+
+```yaml
+name: <agent-name>
+version: '1.0.0'
+grpc_port: 50052
+router_url: '${SWARP_ROUTER_URL}'
+
+preamble: |
+  <describe what the agent does and its personality>
+
+modes:
+  - name: <primary-mode>
+    description: '<what this mode does>'
+    model: <claude-sonnet-4-6 or claude-haiku-4-5-20251001>
+    max_turns: <10-40 depending on complexity>
+    timeout_minutes: <5-30>
+    prompt: '{{ task }}'
+    allowed_tools:
+      - Read
+      - Edit
+      - Write
+      - Bash
+      - Glob
+      - Grep
+```
+
+## Important Notes
+
+- **Cost gates**: `swarp_deploy`, `swarp_deploy_router`, and `swarp_destroy` all trigger cost confirmation hooks. The user WILL be prompted by Claude Code before these execute. Set their expectations: "This will create infrastructure — you'll see a cost estimate and need to approve."
+- **WireGuard**: Agent sprites connect to the router via WireGuard tunnels over Fly's private network. This is handled automatically during deploy.
+- **OAuth**: External clients (like this Claude Code session) authenticate to the router via Supabase OAuth at swarp.dev. The MCP server handles the token automatically.

package/src/init/index.mjs

@@ -1,108 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { runWizard } from './wizard.mjs';
-import { generateSkill } from '../skill/generate.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const TEMPLATES_DIR = path.resolve(__dirname, '../templates');
-
-// ── Prerequisite check ────────────────────────────────────────────────────────
-
-const REQUIRED_TOOLS = ['flyctl', 'gh', 'sprite'];
-
-/**
- * Checks whether a binary exists on PATH via `which`.
- * Returns true if found, false if not.
- *
- * @param {string} tool
- * @returns {boolean}
- */
-function toolExists(tool) {
-  try {
-    execFileSync('which', [tool], { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Checks all required tools and prints warnings for missing ones.
- * Missing tools are non-fatal — init continues.
- *
- * @param {string[]} tools
- * @returns {string[]} names of missing tools
- */
-function checkPrerequisites(tools = REQUIRED_TOOLS) {
-  const missing = tools.filter((t) => !toolExists(t));
-  for (const tool of missing) {
-    console.warn(`Warning: '${tool}' not found on PATH. Some features will not work until it is installed.`);
-  }
-  return missing;
-}
-
-// ── File writers ──────────────────────────────────────────────────────────────
-
-/**
- * Writes a file only if it does not already exist.
- * Prints a skip or create message.
- *
- * @param {string} filePath - Absolute path
- * @param {string} content
- */
-function writeIfAbsent(filePath, content) {
-  if (fs.existsSync(filePath)) {
-    console.log(`  skip  ${filePath} (already exists)`);
-    return;
-  }
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-  console.log(`  create ${filePath}`);
-}
-
-/**
- * Reads a template file and replaces {{key}} placeholders.
- *
- * @param {string} templateName - File name inside src/templates/
- * @param {Record<string, string>} vars
- * @returns {string}
- */
-function renderTemplate(templateName, vars) {
-  const tplPath = path.join(TEMPLATES_DIR, templateName);
-  let content = fs.readFileSync(tplPath, 'utf8');
-  for (const [key, value] of Object.entries(vars)) {
-    content = content.replaceAll(`{{${key}}}`, value);
-  }
-  return content;
-}
-
-// ── .swarp.json ───────────────────────────────────────────────────────────────
-
-function buildSwarpJson(routerUrl, agentsDir, flyApp) {
-  return JSON.stringify({ router_url: routerUrl, agents_dir: agentsDir, fly_app: flyApp }, null, 2) + '\n';
-}
-
-// ── router.yaml ───────────────────────────────────────────────────────────────
-
-function buildRouterYaml() {
-  return `router:
-  grpc_port: 50051
-
-registration:
-  ttl_minutes: 30
-  persist_path: /data/registry.json
-`;
-}
 
 // ── .mcp.json ─────────────────────────────────────────────────────────────────
 
 /**
  * Adds a `swarp` entry to .mcp.json if one does not exist.
- * If .mcp.json does not exist, creates it from scratch.
- *
- * @param {string} cwd - Project root
+ * This is for standalone (non-plugin) usage only.
+ * Plugin users get the MCP server automatically.
  */
 function updateMcpJson(cwd) {
   const mcpPath = path.join(cwd, '.mcp.json');
@@ -112,11 +16,11 @@ function updateMcpJson(cwd) {
     try {
       config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
     } catch {
-      console.warn('  warn   .mcp.json is not valid JSON — skipping update');
+      console.warn('  warn   .mcp.json is not valid JSON — skipping');
       return;
     }
     if (config.mcpServers?.swarp) {
-      console.log(`  skip  ${mcpPath} swarp entry (already exists)`);
+      console.log(`  skip  ${mcpPath} (swarp entry already exists)`);
       return;
     }
   }
@@ -128,58 +32,23 @@ function updateMcpJson(cwd) {
   };
 
   fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  console.log(`  update ${mcpPath} — added swarp entry`);
+  console.log(`  create ${mcpPath} — added swarp MCP server`);
 }
 
-
 // ── Main entry point ──────────────────────────────────────────────────────────
 
 /**
- * Runs the SWARP init command.
+ * Minimal init for standalone (non-plugin) usage.
+ * Creates .mcp.json entry so Claude Code can find the MCP server.
+ * All other setup happens via the /swarp skill in Claude Code.
  *
  * @param {object} [opts]
  * @param {string} [opts.cwd] - Project root directory (default: process.cwd())
- * @param {object} [opts.wizardAnswers] - Pre-filled answers (skips interactive prompts, for testing)
- * @param {NodeJS.ReadableStream} [opts.input] - Wizard stdin override
- * @param {NodeJS.WritableStream} [opts.output] - Wizard stdout override
  */
-export async function runInit({ cwd = process.cwd(), wizardAnswers, input, output } = {}) {
-  // 1. Prerequisites
-  checkPrerequisites();
-
-  // 2. Wizard
-  const answers = wizardAnswers ?? (await runWizard({ input, output }));
-  const { agentsDir, flyOrg, firstAgentName } = answers;
-
-  const flyApp = flyOrg ? `${flyOrg}-swarp-router` : 'my-org-swarp-router';
-  const routerUrl = flyOrg ? `${flyOrg}-swarp-router.fly.dev:50051` : 'your-router.fly.dev:50051';
-
-  console.log('\nGenerating files...\n');
+export async function runInit({ cwd = process.cwd() } = {}) {
+  console.log('\nSWARP init\n');
 
-  // 3. agents/<name>/agent.yaml — fully commented sample
-  const agentYamlContent = renderTemplate('agent.yaml.example.hbs', { firstAgentName });
-  writeIfAbsent(path.join(cwd, agentsDir, firstAgentName, 'agent.yaml'), agentYamlContent);
-
-  // 4. .swarp.json
-  writeIfAbsent(path.join(cwd, '.swarp.json'), buildSwarpJson(routerUrl, agentsDir, flyApp));
-
-  // 5. router.yaml
-  writeIfAbsent(path.join(cwd, 'router.yaml'), buildRouterYaml());
-
-  // 6. .github/workflows/deploy-agents.yml
-  const workflowContent = fs.readFileSync(path.join(TEMPLATES_DIR, 'workflow.yml'), 'utf8');
-  writeIfAbsent(path.join(cwd, '.github', 'workflows', 'deploy-agents.yml'), workflowContent);
-
-  // 7. .mcp.json
   updateMcpJson(cwd);
 
-  // 8. .claude/skills/swarp/SKILL.md — generated from agent configs
-  const skillContent = generateSkill({
-    agentsDir: path.resolve(cwd, agentsDir),
-    routerUrl,
-  });
-  writeIfAbsent(path.join(cwd, '.claude', 'skills', 'swarp', 'SKILL.md'), skillContent);
-
-  // 9. Done
-  console.log('\nNext steps: run /swarp in Claude Code to dispatch tasks to your agents\n');
+  console.log('\n  Open Claude Code and run /swarp to get started.\n');
 }

package/src/init/index.test.mjs

@@ -4,26 +4,6 @@ import path from 'node:path';
 import os from 'node:os';
 import { runInit } from './index.mjs';
 
-// Track calls made to execFileSync by the module under test.
-// We cannot vi.spyOn a CJS binding in ESM, so we use a shared call log
-// populated via vi.mock instead.
-const execFileSyncCalls = [];
-let execFileSyncImpl = null;
-
-vi.mock('node:child_process', async (importOriginal) => {
-  const original = await importOriginal();
-  return {
-    ...original,
-    execFileSync: (...args) => {
-      execFileSyncCalls.push(args);
-      if (execFileSyncImpl) return execFileSyncImpl(...args);
-      return original.execFileSync(...args);
-    },
-  };
-});
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
 function makeTmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'swarp-init-test-'));
 }
@@ -32,159 +12,57 @@ function cleanDir(dir) {
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
-// Pre-filled wizard answers used by most tests
-const DEFAULT_ANSWERS = {
-  agentsDir: 'agents/',
-  flyOrg: 'myorg',
-  firstAgentName: 'example',
-};
-
-// ── Tests ─────────────────────────────────────────────────────────────────────
-
 describe('runInit', () => {
   let tmpDir;
 
   beforeEach(() => {
     tmpDir = makeTmpDir();
-    execFileSyncCalls.length = 0;
-    execFileSyncImpl = null;
-    // Silence stdout/stderr during tests
     vi.spyOn(console, 'log').mockImplementation(() => {});
     vi.spyOn(console, 'warn').mockImplementation(() => {});
   });
 
   afterEach(() => {
     cleanDir(tmpDir);
-    execFileSyncImpl = null;
     vi.restoreAllMocks();
   });
 
-  it('creates agents/<name>/agent.yaml', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-    const p = path.join(tmpDir, 'agents', 'example', 'agent.yaml');
-    expect(fs.existsSync(p)).toBe(true);
-    const content = fs.readFileSync(p, 'utf8');
-    expect(content).toContain('name: example');
-  });
-
-  it('substitutes firstAgentName in agent.yaml template', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: { ...DEFAULT_ANSWERS, firstAgentName: 'dominic' } });
-    const content = fs.readFileSync(
-      path.join(tmpDir, 'agents', 'dominic', 'agent.yaml'),
-      'utf8',
-    );
-    expect(content).toContain('name: dominic');
-    expect(content).not.toContain('{{firstAgentName}}');
-  });
-
-  it('creates .swarp.json with correct fields', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-    const p = path.join(tmpDir, '.swarp.json');
-    expect(fs.existsSync(p)).toBe(true);
-    const config = JSON.parse(fs.readFileSync(p, 'utf8'));
-    expect(config.router_url).toBe('myorg-swarp-router.fly.dev:50051');
-    expect(config.agents_dir).toBe('agents/');
-    expect(config.fly_app).toBe('myorg-swarp-router');
-  });
-
-  it('creates router.yaml', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-    const p = path.join(tmpDir, 'router.yaml');
-    expect(fs.existsSync(p)).toBe(true);
-    const content = fs.readFileSync(p, 'utf8');
-    expect(content).toContain('grpc_port: 50051');
-    expect(content).toContain('grpc_port: 50051');
-  });
-
-  it('creates .github/workflows/deploy-agents.yml', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-    const p = path.join(tmpDir, '.github', 'workflows', 'deploy-agents.yml');
-    expect(fs.existsSync(p)).toBe(true);
-    const content = fs.readFileSync(p, 'utf8');
-    expect(content).toContain('dl3consulting/swarp-actions');
-  });
-
-  it('adds swarp entry to .mcp.json when none exists', async () => {
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-    const config = JSON.parse(fs.readFileSync(path.join(tmpDir, '.mcp.json'), 'utf8'));
-    expect(config.mcpServers.swarp).toBeDefined();
-    expect(config.mcpServers.swarp.command).toBe('npx');
-  });
-
-  it('merges swarp entry into existing .mcp.json without clobbering other entries', async () => {
+  it('creates .mcp.json with swarp entry', async () => {
+    await runInit({ cwd: tmpDir });
     const mcpPath = path.join(tmpDir, '.mcp.json');
-    fs.writeFileSync(
-      mcpPath,
-      JSON.stringify({ mcpServers: { dl3: { command: 'bun', args: [] } } }, null, 2),
-      'utf8',
-    );
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
+    expect(fs.existsSync(mcpPath)).toBe(true);
     const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-    expect(config.mcpServers.dl3).toBeDefined();
     expect(config.mcpServers.swarp).toBeDefined();
+    expect(config.mcpServers.swarp.command).toBe('npx');
+    expect(config.mcpServers.swarp.args).toContain('@swarp/cli');
   });
 
-  describe('idempotency', () => {
-    it('skips files that already exist on re-run', async () => {
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-
-      // Overwrite agent.yaml with sentinel content
-      const agentYaml = path.join(tmpDir, 'agents', 'example', 'agent.yaml');
-      fs.writeFileSync(agentYaml, 'SENTINEL', 'utf8');
-
-      // Second run must not overwrite
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      expect(fs.readFileSync(agentYaml, 'utf8')).toBe('SENTINEL');
-    });
+  it('does not overwrite existing swarp entry in .mcp.json', async () => {
+    const mcpPath = path.join(tmpDir, '.mcp.json');
+    const existing = { mcpServers: { swarp: { command: 'custom', args: [] } } };
+    fs.writeFileSync(mcpPath, JSON.stringify(existing), 'utf8');
 
-    it('skips .swarp.json on re-run', async () => {
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      const p = path.join(tmpDir, '.swarp.json');
-      fs.writeFileSync(p, '{"sentinel":true}', 'utf8');
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      expect(JSON.parse(fs.readFileSync(p, 'utf8')).sentinel).toBe(true);
-    });
+    await runInit({ cwd: tmpDir });
 
-    it('skips swarp entry in .mcp.json on re-run', async () => {
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      const mcpPath = path.join(tmpDir, '.mcp.json');
-      const before = fs.readFileSync(mcpPath, 'utf8');
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      expect(fs.readFileSync(mcpPath, 'utf8')).toBe(before);
-    });
+    const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    expect(config.mcpServers.swarp.command).toBe('custom');
   });
 
-  describe('missing tools', () => {
-    it('prints warning for missing tool and continues', async () => {
-      // Mock execFileSync to simulate flyctl missing by importing the module and
-      // checking that a missing tool does not throw.
-      // We verify by observing console.warn was called and files were still created.
-      const warnSpy = vi.spyOn(console, 'warn');
+  it('preserves other MCP entries in .mcp.json', async () => {
+    const mcpPath = path.join(tmpDir, '.mcp.json');
+    const existing = { mcpServers: { other: { command: 'other-tool', args: [] } } };
+    fs.writeFileSync(mcpPath, JSON.stringify(existing), 'utf8');
 
-      // Force toolExists to return false for flyctl by patching child_process at module
-      // level is complex in ESM; instead we verify the warning path via a direct import
-      // of checkPrerequisites internals by calling runInit with a cwd where all tools
-      // are absent from the PATH simulation. Since we cannot mock execFileSync in ESM
-      // without additional setup, we verify the critical contract: runInit completes
-      // even when a tool check would warn.
-      await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
-      // Files are created regardless of tool presence
-      expect(fs.existsSync(path.join(tmpDir, '.swarp.json'))).toBe(true);
-    });
+    await runInit({ cwd: tmpDir });
 
-    it('uses placeholder router URL when flyOrg is empty', async () => {
-      await runInit({ cwd: tmpDir, wizardAnswers: { ...DEFAULT_ANSWERS, flyOrg: '' } });
-      const config = JSON.parse(fs.readFileSync(path.join(tmpDir, '.swarp.json'), 'utf8'));
-      expect(config.router_url).toBe('your-router.fly.dev:50051');
-      expect(config.fly_app).toBe('my-org-swarp-router');
-    });
+    const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+    expect(config.mcpServers.other).toBeDefined();
+    expect(config.mcpServers.swarp).toBeDefined();
   });
 
   it('prints next-steps message', async () => {
     const logSpy = vi.spyOn(console, 'log');
-    await runInit({ cwd: tmpDir, wizardAnswers: DEFAULT_ANSWERS });
+    await runInit({ cwd: tmpDir });
     const messages = logSpy.mock.calls.map((c) => c[0]).join('\n');
     expect(messages).toContain('/swarp');
   });
-
 });

package/src/mcp-server/index.mjs

@@ -8,10 +8,19 @@ import { DispatchClient } from './dispatch.mjs';
 import { loadConfig } from '../config.mjs';
 import { auditConfigs } from '../generator/audit.mjs';
 import { generateRunnerConfig } from '../generator/generate.mjs';
+import { handleOnboard, onboardToolDef } from './onboard.mjs';
 
 export async function startMcpServer() {
-  const config = loadConfig('.swarp.json');
-  const client = new DispatchClient(config.router_url);
+  let config = {};
+  let client = null;
+
+  try {
+    config = loadConfig('.swarp.json');
+    client = new DispatchClient(config.router_url);
+  } catch {
+    // No config yet — onboarding mode. Only swarp_onboard tool is available.
+    console.error('[swarp] No .swarp.json found — running in onboarding mode');
+  }
 
   const server = new Server(
     { name: 'swarp', version: '1.0.0' },
@@ -21,20 +30,22 @@ export async function startMcpServer() {
   const agentTools = [];
   let agentList = [];
 
-  try {
-    const { agents } = await client.listAgents();
-    agentList = agents ?? [];
-    for (const agent of agentList) {
-      agentTools.push(buildAgentTool(agent));
+  if (client) {
+    try {
+      const { agents } = await client.listAgents();
+      agentList = agents ?? [];
+      for (const agent of agentList) {
+        agentTools.push(buildAgentTool(agent));
+      }
+    } catch (err) {
+      console.error(`[swarp] Warning: could not reach router at ${config.router_url}: ${err.message}`);
     }
-  } catch (err) {
-    console.error(`[swarp] Warning: could not reach router at ${config.router_url}: ${err.message}`);
   }
 
-  const localTools = buildLocalTools(config);
+  const localTools = client ? buildLocalTools(config) : [];
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: [...agentTools, ...localTools] };
+    return { tools: [onboardToolDef, ...agentTools, ...localTools] };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -45,6 +56,7 @@ export async function startMcpServer() {
       return handleAgentDispatch(client, agent.name, toolArgs);
     }
 
+    if (name === 'swarp_onboard') return handleOnboard(toolArgs);
     if (name === 'swarm_audit') return handleAudit(config, toolArgs);
     if (name === 'swarm_generate') return handleGenerate(config, toolArgs);
     if (name === 'swarm_status') return handleStatus(client, toolArgs);