claude-octopus 1.0.0

package/dist/tools/query.js

@@ -0,0 +1,134 @@
+import { z } from "zod/v4";
+import { resolve } from "node:path";
+import { query, } from "@anthropic-ai/claude-agent-sdk";
+import { isDescendantPath, mergeAllowedTools, mergeDisallowedTools, buildResultPayload, formatErrorMessage, } from "../lib.js";
+async function runQuery(prompt, overrides, baseOptions) {
+    const options = { ...baseOptions };
+    if (overrides.cwd) {
+        const baseCwd = baseOptions.cwd || process.cwd();
+        if (isDescendantPath(overrides.cwd, baseCwd)) {
+            options.cwd = resolve(baseCwd, overrides.cwd);
+        }
+    }
+    if (overrides.model)
+        options.model = overrides.model;
+    if (overrides.maxTurns !== undefined && overrides.maxTurns > 0) {
+        options.maxTurns = overrides.maxTurns;
+    }
+    if (overrides.maxBudgetUsd != null)
+        options.maxBudgetUsd = overrides.maxBudgetUsd;
+    if (overrides.resumeSessionId)
+        options.resume = overrides.resumeSessionId;
+    if (overrides.allowedTools?.length) {
+        options.allowedTools = mergeAllowedTools(baseOptions.allowedTools, overrides.allowedTools);
+    }
+    if (overrides.disallowedTools?.length) {
+        options.disallowedTools = mergeDisallowedTools(baseOptions.disallowedTools, overrides.disallowedTools);
+    }
+    if (overrides.systemPrompt) {
+        if (typeof baseOptions.systemPrompt === "object" &&
+            baseOptions.systemPrompt?.type === "preset") {
+            const baseAppend = baseOptions.systemPrompt.append || "";
+            options.systemPrompt = {
+                type: "preset",
+                preset: "claude_code",
+                append: [baseAppend, overrides.systemPrompt].filter(Boolean).join("\n"),
+            };
+        }
+        else if (typeof baseOptions.systemPrompt === "string") {
+            options.systemPrompt = baseOptions.systemPrompt;
+            options.extraArgs = {
+                ...options.extraArgs,
+                "append-system-prompt": overrides.systemPrompt,
+            };
+        }
+        else {
+            options.systemPrompt = {
+                type: "preset",
+                preset: "claude_code",
+                append: overrides.systemPrompt,
+            };
+        }
+    }
+    const q = query({ prompt, options });
+    let result;
+    for await (const message of q) {
+        if (message.type === "result") {
+            result = message;
+        }
+    }
+    if (!result) {
+        throw new Error("No result message received from Claude Code");
+    }
+    return result;
+}
+function formatResult(result) {
+    const payload = buildResultPayload(result);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(payload, null, 2) },
+        ],
+        isError: result.is_error,
+    };
+}
+function formatError(error) {
+    return {
+        content: [
+            { type: "text", text: `Error: ${formatErrorMessage(error)}` },
+        ],
+        isError: true,
+    };
+}
+export function registerQueryTools(server, baseOptions, toolName, toolDescription) {
+    const replyToolName = `${toolName}_reply`;
+    server.registerTool(toolName, {
+        description: toolDescription,
+        inputSchema: z.object({
+            prompt: z.string().describe("Task or question for Claude Code"),
+            cwd: z.string().optional().describe("Working directory (overrides CLAUDE_CWD)"),
+            model: z.string().optional().describe('Model override (e.g. "sonnet", "opus", "haiku")'),
+            allowedTools: z.array(z.string()).optional().describe("Tool whitelist override"),
+            disallowedTools: z.array(z.string()).optional().describe("Tool blacklist override"),
+            maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
+            maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+            systemPrompt: z.string().optional().describe("Additional system prompt (appended to server default)"),
+        }),
+    }, async ({ prompt, cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt }) => {
+        try {
+            const result = await runQuery(prompt, {
+                cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt,
+            }, baseOptions);
+            return formatResult(result);
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    if (baseOptions.persistSession !== false) {
+        server.registerTool(replyToolName, {
+            description: [
+                `Continue a previous ${toolName} conversation by session ID.`,
+                "Use this for follow-up questions, iterative refinement,",
+                "or multi-step workflows that build on prior context.",
+            ].join(" "),
+            inputSchema: z.object({
+                session_id: z.string().describe(`Session ID from a prior ${toolName} response`),
+                prompt: z.string().describe("Follow-up instruction or question"),
+                cwd: z.string().optional().describe("Working directory override"),
+                model: z.string().optional().describe("Model override"),
+                maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
+                maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+            }),
+        }, async ({ session_id, prompt, cwd, model, maxTurns, maxBudgetUsd }) => {
+            try {
+                const result = await runQuery(prompt, {
+                    cwd, model, maxTurns, maxBudgetUsd, resumeSessionId: session_id,
+                }, baseOptions);
+                return formatResult(result);
+            }
+            catch (error) {
+                return formatError(error);
+            }
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+export interface InvocationOverrides {
+    cwd?: string;
+    model?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    systemPrompt?: string;
+    resumeSessionId?: string;
+}
+export interface OptionCatalogEntry {
+    key: string;
+    envVar: string;
+    label: string;
+    hint: string;
+    example: string;
+}
+export type { Options };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "claude-octopus",
+  "version": "1.0.0",
+  "description": "One brain, many arms — spawn multiple specialized Claude Code agents as MCP servers",
+  "type": "module",
+  "bin": {
+    "claude-octopus": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.2"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+import type { Options } from "./types.js";
+import {
+  envStr,
+  envList,
+  envNum,
+  envBool,
+  envJson,
+  validatePermissionMode,
+} from "./lib.js";
+
+export function buildBaseOptions(): Options {
+  const opts: Options = {
+    cwd: envStr("CLAUDE_CWD") || process.cwd(),
+    persistSession: envBool("CLAUDE_PERSIST_SESSION", true),
+  };
+
+  const rawPerm = envStr("CLAUDE_PERMISSION_MODE") || "default";
+  const permMode = validatePermissionMode(rawPerm);
+  if (rawPerm !== permMode) {
+    console.error(
+      `claude-octopus: invalid CLAUDE_PERMISSION_MODE "${rawPerm}", using "default"`
+    );
+  }
+  opts.permissionMode = permMode as Options["permissionMode"];
+  if (permMode === "bypassPermissions") {
+    opts.allowDangerouslySkipPermissions = true;
+  }
+
+  const model = envStr("CLAUDE_MODEL");
+  if (model) opts.model = model;
+
+  const allowed = envList("CLAUDE_ALLOWED_TOOLS");
+  if (allowed) opts.allowedTools = allowed;
+  const disallowed = envList("CLAUDE_DISALLOWED_TOOLS");
+  if (disallowed) opts.disallowedTools = disallowed;
+
+  const maxTurns = envNum("CLAUDE_MAX_TURNS");
+  if (maxTurns !== undefined && maxTurns > 0 && Number.isInteger(maxTurns)) {
+    opts.maxTurns = maxTurns;
+  }
+  const maxBudget = envNum("CLAUDE_MAX_BUDGET_USD");
+  if (maxBudget !== undefined && maxBudget > 0) {
+    opts.maxBudgetUsd = maxBudget;
+  }
+
+  const sysPrompt = envStr("CLAUDE_SYSTEM_PROMPT");
+  const appendPrompt = envStr("CLAUDE_APPEND_PROMPT");
+  if (sysPrompt) {
+    opts.systemPrompt = sysPrompt;
+  } else if (appendPrompt) {
+    opts.systemPrompt = {
+      type: "preset",
+      preset: "claude_code",
+      append: appendPrompt,
+    };
+  }
+
+  const dirs = envList("CLAUDE_ADDITIONAL_DIRS");
+  if (dirs) opts.additionalDirectories = dirs;
+
+  const plugins = envList("CLAUDE_PLUGINS");
+  if (plugins) {
+    opts.plugins = plugins.map((p) => ({ type: "local" as const, path: p }));
+  }
+
+  const mcpServers = envJson<Record<string, unknown>>("CLAUDE_MCP_SERVERS");
+  if (mcpServers) {
+    opts.mcpServers = mcpServers as Options["mcpServers"];
+  }
+
+  const effort = envStr("CLAUDE_EFFORT");
+  if (effort) opts.effort = effort as Options["effort"];
+
+  const sources = envList("CLAUDE_SETTING_SOURCES");
+  if (sources) {
+    opts.settingSources = sources as Options["settingSources"];
+  }
+
+  const settings = envStr("CLAUDE_SETTINGS");
+  if (settings) {
+    if (settings.startsWith("{")) {
+      try {
+        opts.settings = JSON.parse(settings);
+      } catch {
+        opts.settings = settings;
+      }
+    } else {
+      opts.settings = settings;
+    }
+  }
+
+  const betas = envList("CLAUDE_BETAS");
+  if (betas) opts.betas = betas as Options["betas"];
+
+  return opts;
+}

package/src/constants.ts

@@ -0,0 +1,116 @@
+import type { OptionCatalogEntry } from "./types.js";
+
+export const OPTION_CATALOG: OptionCatalogEntry[] = [
+  {
+    key: "model",
+    envVar: "CLAUDE_MODEL",
+    label: "Model",
+    hint: "Which Claude model to use",
+    example: '"sonnet", "opus", "haiku", or full ID',
+  },
+  {
+    key: "appendPrompt",
+    envVar: "CLAUDE_APPEND_PROMPT",
+    label: "Behavior prompt",
+    hint: "Instructions appended to the default Claude Code system prompt",
+    example: '"Always explain your reasoning step by step."',
+  },
+  {
+    key: "systemPrompt",
+    envVar: "CLAUDE_SYSTEM_PROMPT",
+    label: "Full system prompt",
+    hint: "Completely replaces the default system prompt (use appendPrompt instead to keep defaults)",
+    example: '"You are a security auditor..."',
+  },
+  {
+    key: "allowedTools",
+    envVar: "CLAUDE_ALLOWED_TOOLS",
+    label: "Allowed tools",
+    hint: "Only these tools are available (comma-separated)",
+    example: '"Read,Grep,Glob" for read-only; "Bash,Read,Write,Edit,Grep,Glob" for full access',
+  },
+  {
+    key: "disallowedTools",
+    envVar: "CLAUDE_DISALLOWED_TOOLS",
+    label: "Blocked tools",
+    hint: "These tools are removed (comma-separated)",
+    example: '"WebFetch,WebSearch" to block network access',
+  },
+  {
+    key: "cwd",
+    envVar: "CLAUDE_CWD",
+    label: "Working directory",
+    hint: "Default directory the agent operates in",
+    example: '"/home/user/project"',
+  },
+  {
+    key: "additionalDirs",
+    envVar: "CLAUDE_ADDITIONAL_DIRS",
+    label: "Additional directories",
+    hint: "Extra directories the agent can access (comma-separated)",
+    example: '"/shared/libs,/data"',
+  },
+  {
+    key: "maxTurns",
+    envVar: "CLAUDE_MAX_TURNS",
+    label: "Max turns",
+    hint: "Maximum conversation turns per invocation",
+    example: '"10" for quick tasks, "50" for complex ones',
+  },
+  {
+    key: "maxBudgetUsd",
+    envVar: "CLAUDE_MAX_BUDGET_USD",
+    label: "Budget cap (USD)",
+    hint: "Maximum spend per invocation",
+    example: '"0.05" for cheap, "2.0" for complex tasks',
+  },
+  {
+    key: "effort",
+    envVar: "CLAUDE_EFFORT",
+    label: "Reasoning effort",
+    hint: "How hard the agent thinks",
+    example: '"low" (fast), "medium", "high" (thorough), "max" (deepest)',
+  },
+  {
+    key: "plugins",
+    envVar: "CLAUDE_PLUGINS",
+    label: "Plugins",
+    hint: "Local plugin paths (comma-separated)",
+    example: '"/path/to/my-plugin"',
+  },
+  {
+    key: "permissionMode",
+    envVar: "CLAUDE_PERMISSION_MODE",
+    label: "Permission mode",
+    hint: "How tool executions are authorized",
+    example: '"bypassPermissions" (auto-approve), "acceptEdits" (auto-approve edits only), "plan" (no execution)',
+  },
+  {
+    key: "persistSession",
+    envVar: "CLAUDE_PERSIST_SESSION",
+    label: "Persist sessions",
+    hint: "Save sessions for later resume via _reply tool",
+    example: '"true" (default) or "false"',
+  },
+  {
+    key: "settingSources",
+    envVar: "CLAUDE_SETTING_SOURCES",
+    label: "Setting sources",
+    hint: "Which settings files to load (comma-separated)",
+    example: '"user,project" to load CLAUDE.md and user settings',
+  },
+  {
+    key: "mcpServers",
+    envVar: "CLAUDE_MCP_SERVERS",
+    label: "Inner MCP servers",
+    hint: "MCP servers available to the inner agent (JSON)",
+    example: '\'{"db":{"command":"node","args":["db-server.js"]}}\'',
+  },
+  {
+    key: "betas",
+    envVar: "CLAUDE_BETAS",
+    label: "Beta features",
+    hint: "Enable beta capabilities (comma-separated)",
+    example: '"context-1m-2025-08-07" for 1M context window',
+  },
+];

package/src/index.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Octopus — one brain, many arms.
+ *
+ * Wraps the Claude Agent SDK as MCP servers, letting you spawn multiple
+ * specialized Claude Code agents — each with its own model, tools, prompt,
+ * and personality.
+ *
+ * See README or env var docs in config.ts for configuration.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { envStr, envBool, sanitizeToolName } from "./lib.js";
+import { buildBaseOptions } from "./config.js";
+import { registerQueryTools } from "./tools/query.js";
+import { registerFactoryTool } from "./tools/factory.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SERVER_ENTRY = resolve(__dirname, "index.js");
+
+// ── Configuration ──────────────────────────────────────────────────
+
+const BASE_OPTIONS = buildBaseOptions();
+
+const TOOL_NAME = sanitizeToolName(envStr("CLAUDE_TOOL_NAME") || "claude_code");
+const REPLY_TOOL_NAME = `${TOOL_NAME}_reply`;
+const SERVER_NAME = envStr("CLAUDE_SERVER_NAME") || "claude-octopus";
+const FACTORY_ONLY = envBool("CLAUDE_FACTORY_ONLY", false);
+
+const DEFAULT_DESCRIPTION = [
+  "Send a task to an autonomous Claude Code agent.",
+  "It reads/writes files, runs shell commands, searches codebases,",
+  "and handles complex software engineering tasks end-to-end.",
+  `Returns the result text plus a session_id for follow-ups via ${REPLY_TOOL_NAME}.`,
+].join(" ");
+
+const TOOL_DESCRIPTION = envStr("CLAUDE_DESCRIPTION") || DEFAULT_DESCRIPTION;
+
+// ── Server ─────────────────────────────────────────────────────────
+
+const server = new McpServer({ name: SERVER_NAME, version: "1.0.0" });
+
+if (!FACTORY_ONLY) {
+  registerQueryTools(server, BASE_OPTIONS, TOOL_NAME, TOOL_DESCRIPTION);
+}
+
+if (FACTORY_ONLY) {
+  registerFactoryTool(server, SERVER_ENTRY);
+}
+
+// ── Start ──────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const toolList = FACTORY_ONLY
+    ? ["create_claude_code_mcp"]
+    : BASE_OPTIONS.persistSession !== false
+      ? [TOOL_NAME, REPLY_TOOL_NAME]
+      : [TOOL_NAME];
+  console.error(`${SERVER_NAME}: running on stdio (tools: ${toolList.join(", ")})`);
+}
+
+main().catch((error) => {
+  console.error(`${SERVER_NAME}: fatal:`, error);
+  process.exit(1);
+});