claude-octopus 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Xiaolai Li
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { Options } from "./types.js";
+export declare function buildBaseOptions(): Options;

package/dist/config.js

@@ -0,0 +1,81 @@
+import { envStr, envList, envNum, envBool, envJson, validatePermissionMode, } from "./lib.js";
+export function buildBaseOptions() {
+    const opts = {
+        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;
+    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", path: p }));
+    }
+    const mcpServers = envJson("CLAUDE_MCP_SERVERS");
+    if (mcpServers) {
+        opts.mcpServers = mcpServers;
+    }
+    const effort = envStr("CLAUDE_EFFORT");
+    if (effort)
+        opts.effort = effort;
+    const sources = envList("CLAUDE_SETTING_SOURCES");
+    if (sources) {
+        opts.settingSources = sources;
+    }
+    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;
+    return opts;
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+import type { OptionCatalogEntry } from "./types.js";
+export declare const OPTION_CATALOG: OptionCatalogEntry[];

package/dist/constants.js

@@ -0,0 +1,114 @@
+export const OPTION_CATALOG = [
+    {
+        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/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/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.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/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);
+});

package/dist/lib.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure, testable logic extracted from index.ts.
+ */
+export declare function envStr(key: string, env?: Record<string, string | undefined>): string | undefined;
+export declare function envList(key: string, env?: Record<string, string | undefined>): string[] | undefined;
+export declare function envNum(key: string, env?: Record<string, string | undefined>): number | undefined;
+export declare function envBool(key: string, fallback: boolean, env?: Record<string, string | undefined>): boolean;
+export declare function envJson<T>(key: string, env?: Record<string, string | undefined>): T | undefined;
+export declare const MAX_TOOL_NAME_LEN: number;
+export declare function sanitizeToolName(raw: string): string;
+export declare function isDescendantPath(requested: string, baseCwd: string): boolean;
+export declare function mergeAllowedTools(serverList: string[] | undefined, callList: string[]): string[];
+export declare function mergeDisallowedTools(serverList: string[] | undefined, callList: string[]): string[];
+export declare const VALID_PERM_MODES: Set<string>;
+export declare function validatePermissionMode(mode: string): string;
+export declare function deriveServerName(description: string): string;
+export declare function deriveToolName(name: string): string;
+export declare function serializeArrayEnv(val: unknown[]): string;
+export interface ResultPayload {
+    session_id: string;
+    cost_usd: number;
+    duration_ms: number;
+    num_turns: number;
+    is_error: boolean;
+    result?: string;
+    errors?: string[];
+}
+export declare function buildResultPayload(result: {
+    session_id: string;
+    total_cost_usd: number;
+    duration_ms: number;
+    num_turns: number;
+    is_error: boolean;
+    subtype: string;
+    result?: string;
+    errors?: string[];
+}): ResultPayload;
+export declare function formatErrorMessage(error: unknown): string;

package/dist/lib.js

@@ -0,0 +1,134 @@
+/**
+ * Pure, testable logic extracted from index.ts.
+ */
+import { normalize, resolve, sep } from "node:path";
+// ── Env helpers ────────────────────────────────────────────────────
+export function envStr(key, env = process.env) {
+    return env[key] || undefined;
+}
+export function envList(key, env = process.env) {
+    const val = env[key];
+    if (!val)
+        return undefined;
+    if (val.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(val);
+            if (Array.isArray(parsed))
+                return parsed.map(String).filter(Boolean);
+        }
+        catch {
+            // fall through to comma-split
+        }
+    }
+    return val
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function envNum(key, env = process.env) {
+    const val = env[key];
+    if (!val)
+        return undefined;
+    const n = Number(val);
+    return Number.isNaN(n) ? undefined : n;
+}
+export function envBool(key, fallback, env = process.env) {
+    const val = env[key];
+    if (val === undefined)
+        return fallback;
+    return val === "true" || val === "1";
+}
+export function envJson(key, env = process.env) {
+    const val = env[key];
+    if (!val)
+        return undefined;
+    try {
+        return JSON.parse(val);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Tool name sanitization ─────────────────────────────────────────
+export const MAX_TOOL_NAME_LEN = 64 - "_reply".length;
+export function sanitizeToolName(raw) {
+    const sanitized = raw
+        .replace(/[^a-zA-Z0-9_]/g, "_")
+        .slice(0, MAX_TOOL_NAME_LEN);
+    return sanitized || "claude_code";
+}
+// ── cwd security check ────────────────────────────────────────────
+export function isDescendantPath(requested, baseCwd) {
+    const normalBase = normalize(baseCwd);
+    const normalReq = normalize(resolve(normalBase, requested));
+    if (normalReq === normalBase)
+        return true;
+    const baseWithSep = normalBase.endsWith(sep)
+        ? normalBase
+        : normalBase + sep;
+    return normalReq.startsWith(baseWithSep);
+}
+// ── Tool restriction merging ───────────────────────────────────────
+export function mergeAllowedTools(serverList, callList) {
+    if (serverList?.length) {
+        const serverSet = new Set(serverList);
+        return callList.filter((t) => serverSet.has(t));
+    }
+    return callList;
+}
+export function mergeDisallowedTools(serverList, callList) {
+    const merged = new Set([...(serverList || []), ...callList]);
+    return [...merged];
+}
+// ── Permission mode validation ─────────────────────────────────────
+export const VALID_PERM_MODES = new Set([
+    "default",
+    "acceptEdits",
+    "bypassPermissions",
+    "plan",
+    "dontAsk",
+    "auto",
+]);
+export function validatePermissionMode(mode) {
+    return VALID_PERM_MODES.has(mode) ? mode : "default";
+}
+// ── Factory name derivation ────────────────────────────────────────
+export function deriveServerName(description) {
+    const slug = description
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 30);
+    return slug || `agent-${Date.now()}`;
+}
+export function deriveToolName(name) {
+    const slug = name
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/^_|_$/g, "")
+        .slice(0, MAX_TOOL_NAME_LEN);
+    return slug || "agent";
+}
+// ── Factory env serialization ──────────────────────────────────────
+export function serializeArrayEnv(val) {
+    const hasComma = val.some((v) => String(v).includes(","));
+    return hasComma ? JSON.stringify(val) : val.join(",");
+}
+export function buildResultPayload(result) {
+    const payload = {
+        session_id: result.session_id,
+        cost_usd: result.total_cost_usd,
+        duration_ms: result.duration_ms,
+        num_turns: result.num_turns,
+        is_error: result.is_error,
+    };
+    if (result.subtype === "success") {
+        payload.result = result.result;
+    }
+    else {
+        payload.errors = result.errors;
+    }
+    return payload;
+}
+export function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/tools/factory.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFactoryTool(server: McpServer, serverEntry: string): void;

package/dist/tools/factory.js

@@ -0,0 +1,108 @@
+import { z } from "zod/v4";
+import { OPTION_CATALOG } from "../constants.js";
+import { sanitizeToolName, deriveServerName, deriveToolName, serializeArrayEnv, } from "../lib.js";
+function buildEnvFromParams(params) {
+    const env = {};
+    for (const opt of OPTION_CATALOG) {
+        const val = params[opt.key];
+        if (val === undefined || val === null)
+            continue;
+        if (Array.isArray(val)) {
+            if (val.length > 0)
+                env[opt.envVar] = serializeArrayEnv(val);
+        }
+        else if (typeof val === "object") {
+            env[opt.envVar] = JSON.stringify(val);
+        }
+        else if (typeof val === "boolean") {
+            env[opt.envVar] = String(val);
+        }
+        else if (val !== "") {
+            env[opt.envVar] = String(val);
+        }
+    }
+    return env;
+}
+export function registerFactoryTool(server, serverEntry) {
+    server.registerTool("create_claude_code_mcp", {
+        description: [
+            "Create a new specialized Claude Code agent as an MCP server.",
+            "WHEN TO USE: user says 'create agent', 'new agent', 'set up agent',",
+            "'configure agent', 'add a reviewer', 'add a test writer',",
+            "'make me a code reviewer', 'I need a specialized agent', etc.",
+            "DO NOT USE when user just wants to run a task — use the main tool for that.",
+            "This is a wizard: only a description is required.",
+            "Returns a ready-to-use .mcp.json config and lists all customization options.",
+            "Call again with more parameters to refine.",
+        ].join(" "),
+        inputSchema: z.object({
+            description: z.string().describe("What this agent should do, in plain language. Example: 'a strict code reviewer that only reads files'"),
+            name: z.string().optional().describe("Server name / alias (derived from description if omitted)"),
+            toolName: z.string().optional().describe("Custom tool name prefix"),
+            model: z.string().optional(),
+            systemPrompt: z.string().optional(),
+            appendPrompt: z.string().optional(),
+            allowedTools: z.array(z.string()).optional(),
+            disallowedTools: z.array(z.string()).optional(),
+            cwd: z.string().optional(),
+            additionalDirs: z.array(z.string()).optional(),
+            plugins: z.array(z.string()).optional(),
+            maxTurns: z.number().optional(),
+            maxBudgetUsd: z.number().optional(),
+            effort: z.enum(["low", "medium", "high", "max"]).optional(),
+            persistSession: z.boolean().optional(),
+            permissionMode: z.enum(["bypassPermissions", "acceptEdits", "default", "plan"]).optional(),
+            settingSources: z.array(z.string()).optional(),
+            mcpServers: z.record(z.string(), z.unknown()).optional(),
+            betas: z.array(z.string()).optional(),
+        }),
+    }, async (params) => {
+        const { description, name: nameParam, toolName: toolNameParam } = params;
+        const name = nameParam || deriveServerName(description);
+        const derivedToolName = toolNameParam
+            ? sanitizeToolName(toolNameParam)
+            : deriveToolName(name);
+        const env = {
+            CLAUDE_TOOL_NAME: derivedToolName,
+            CLAUDE_SERVER_NAME: name,
+            CLAUDE_DESCRIPTION: description,
+        };
+        const optionEnv = buildEnvFromParams(params);
+        Object.assign(env, optionEnv);
+        const configured = Object.keys(optionEnv);
+        const notConfigured = OPTION_CATALOG.filter((o) => !configured.includes(o.envVar));
+        const mcpEntry = {
+            [name]: {
+                command: "node",
+                args: [serverEntry],
+                env,
+            },
+        };
+        const sections = [];
+        sections.push("## Generated config", "", "Add to `mcpServers` in your `.mcp.json`:", "", "```json", JSON.stringify(mcpEntry, null, 2), "```");
+        sections.push("", "## What's configured");
+        sections.push("", `| Setting | Value |`, `|---|---|`);
+        sections.push(`| Name | \`${name}\` |`);
+        sections.push(`| Tool names | \`${derivedToolName}\`, \`${derivedToolName}_reply\` |`);
+        for (const key of configured) {
+            const opt = OPTION_CATALOG.find((o) => o.envVar === key);
+            if (opt) {
+                sections.push(`| ${opt.label} | \`${env[key]}\` |`);
+            }
+        }
+        if (configured.length === 0) {
+            sections.push(`| _(all defaults)_ | — |`);
+        }
+        if (notConfigured.length > 0) {
+            sections.push("", "## Available customizations", "", "These options are not yet set. Ask the user if they'd like to configure any:", "");
+            for (const opt of notConfigured) {
+                sections.push(`- **${opt.label}** — ${opt.hint}`);
+                sections.push(`  Example: ${opt.example}`);
+            }
+            sections.push("", "_Call this tool again with additional parameters to refine the config._");
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") }],
+        };
+    });
+}

package/dist/tools/query.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Options } from "../types.js";
+export declare function registerQueryTools(server: McpServer, baseOptions: Options, toolName: string, toolDescription: string): void;