@betrue/openclaw-claude-code-plugin 1.0.0

package/index.ts

@@ -0,0 +1,158 @@
+import { registerClaudeLaunchTool } from "./src/tools/claude-launch";
+import { registerClaudeSessionsTool } from "./src/tools/claude-sessions";
+import { registerClaudeKillTool } from "./src/tools/claude-kill";
+import { registerClaudeOutputTool } from "./src/tools/claude-output";
+import { registerClaudeFgTool } from "./src/tools/claude-fg";
+import { registerClaudeBgTool } from "./src/tools/claude-bg";
+import { registerClaudeRespondTool } from "./src/tools/claude-respond";
+import { registerClaudeStatsTool } from "./src/tools/claude-stats";
+import { registerClaudeCommand } from "./src/commands/claude";
+import { registerClaudeSessionsCommand } from "./src/commands/claude-sessions";
+import { registerClaudeKillCommand } from "./src/commands/claude-kill";
+import { registerClaudeFgCommand } from "./src/commands/claude-fg";
+import { registerClaudeBgCommand } from "./src/commands/claude-bg";
+import { registerClaudeResumeCommand } from "./src/commands/claude-resume";
+import { registerClaudeRespondCommand } from "./src/commands/claude-respond";
+import { registerClaudeStatsCommand } from "./src/commands/claude-stats";
+import { registerGatewayMethods } from "./src/gateway";
+import { SessionManager } from "./src/session-manager";
+import { NotificationRouter } from "./src/notifications";
+import { setSessionManager, setNotificationRouter, setPluginConfig, pluginConfig } from "./src/shared";
+import { execFile } from "child_process";
+
+// Plugin register function - called by OpenClaw when loading the plugin
+export function register(api: any) {
+  // Local references for service lifecycle
+  let sm: SessionManager | null = null;
+  let nr: NotificationRouter | null = null;
+  let cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  // Tools
+  registerClaudeLaunchTool(api);
+  registerClaudeSessionsTool(api);
+  registerClaudeKillTool(api);
+  registerClaudeOutputTool(api);
+  registerClaudeFgTool(api);
+  registerClaudeBgTool(api);
+  registerClaudeRespondTool(api);
+  registerClaudeStatsTool(api);
+
+  // Commands
+  registerClaudeCommand(api);
+  registerClaudeSessionsCommand(api);
+  registerClaudeKillCommand(api);
+  registerClaudeFgCommand(api);
+  registerClaudeBgCommand(api);
+  registerClaudeResumeCommand(api);
+  registerClaudeRespondCommand(api);
+  registerClaudeStatsCommand(api);
+
+  // Gateway RPC methods (Task 17)
+  registerGatewayMethods(api);
+
+  // Service
+  api.registerService({
+    id: "claude-code",
+    start: () => {
+      const config = api.getConfig?.() ?? {};
+
+      // Store config globally for all modules (Task 20)
+      setPluginConfig(config);
+
+      // Create SessionManager — uses config for maxSessions and maxPersistedSessions
+      sm = new SessionManager(
+        pluginConfig.maxSessions,
+        pluginConfig.maxPersistedSessions,
+      );
+      setSessionManager(sm);
+
+      // Create NotificationRouter with OpenClaw's outbound message pipeline.
+      // Uses `openclaw message send` CLI since the plugin API does not expose
+      // a runtime.sendMessage method for proactive outbound messages.
+      //
+      // channelId format: "telegram:<chatId>" or just a bare chat ID.
+      // Fallback channel comes from config.fallbackChannel (e.g. "telegram:123456789").
+
+      const sendMessage = (channelId: string, text: string) => {
+        // Resolve channel and target from channelId
+        // Expected formats:
+        //   "telegram:123456789" → channel=telegram, target=123456789
+        //   "discord:987654321" → channel=discord, target=987654321
+        //   "123456789"         → channel=telegram (fallback), target=123456789
+        //   "toolu_xxxx"        → not a real channel, use fallback
+
+        // Parse fallbackChannel from config (e.g. "telegram:123456789")
+        let fallbackChannel = "telegram";
+        let fallbackTarget = "";
+        if (pluginConfig.fallbackChannel?.includes(":")) {
+          const [fc, ft] = pluginConfig.fallbackChannel.split(":", 2);
+          if (fc && ft) { fallbackChannel = fc; fallbackTarget = ft; }
+        }
+
+        let channel = fallbackChannel;
+        let target = fallbackTarget;
+
+        if (channelId === "unknown" || !channelId) {
+          // Tool-launched sessions have originChannel="unknown" — always use fallback
+          if (fallbackTarget) {
+            console.log(`[claude-code] sendMessage: channelId="${channelId}", using fallback ${fallbackChannel}:${fallbackTarget}`);
+          } else {
+            console.warn(`[claude-code] sendMessage: channelId="${channelId}" and no fallbackChannel configured — message will not be sent`);
+            return;
+          }
+        } else if (channelId.includes(":")) {
+          const [ch, tgt] = channelId.split(":", 2);
+          if (ch && tgt) {
+            channel = ch;
+            target = tgt;
+          }
+        } else if (/^-?\d+$/.test(channelId)) {
+          // Bare numeric ID — assume Telegram chat ID
+          channel = "telegram";
+          target = channelId;
+        } else if (fallbackTarget) {
+          // Non-numeric, non-structured ID (e.g. "toolu_xxx", "command")
+          // Use fallback from config
+          console.log(`[claude-code] sendMessage: unrecognized channelId="${channelId}", using fallback ${fallbackChannel}:${fallbackTarget}`);
+        } else {
+          console.warn(`[claude-code] sendMessage: unrecognized channelId="${channelId}" and no fallbackChannel configured — message will not be sent`);
+          return;
+        }
+
+        console.log(`[claude-code] sendMessage -> channel=${channel}, target=${target}, textLen=${text.length}`);
+
+        execFile("openclaw", ["message", "send", "--channel", channel, "--target", target, "-m", text], { timeout: 15_000 }, (err, stdout, stderr) => {
+          if (err) {
+            console.error(`[claude-code] sendMessage CLI ERROR: ${err.message}`);
+            if (stderr) console.error(`[claude-code] sendMessage CLI STDERR: ${stderr}`);
+          } else {
+            console.log(`[claude-code] sendMessage CLI OK -> channel=${channel}, target=${target}`);
+            if (stdout.trim()) console.log(`[claude-code] sendMessage CLI STDOUT: ${stdout.trim()}`);
+          }
+        });
+      };
+
+      nr = new NotificationRouter(sendMessage);
+      setNotificationRouter(nr);
+
+      // Wire NotificationRouter into SessionManager
+      sm.notificationRouter = nr;
+
+      // Start the long-running session reminder check
+      nr.startReminderCheck(() => sm?.list("running") ?? []);
+
+      // GC interval
+      cleanupInterval = setInterval(() => sm!.cleanup(), 5 * 60 * 1000);
+    },
+    stop: () => {
+      if (nr) nr.stop();
+      if (sm) sm.killAll();
+      if (cleanupInterval) clearInterval(cleanupInterval);
+      cleanupInterval = null;
+      sm = null;
+      nr = null;
+      setSessionManager(null);
+      setNotificationRouter(null);
+    },
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "claude-code",
+  "name": "Claude Code Plugin",
+  "description": "Orchestrate Claude Code sessions from OpenClaw",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "maxSessions": { "type": "number", "default": 5 },
+      "defaultBudgetUsd": { "type": "number", "default": 5 },
+      "defaultModel": { "type": "string", "description": "Default model for new sessions (e.g. 'sonnet', 'opus')" },
+      "defaultWorkdir": { "type": "string", "description": "Default working directory for new sessions" },
+      "idleTimeoutMinutes": { "type": "number", "default": 30, "description": "Idle timeout in minutes for multi-turn sessions before auto-kill" },
+      "maxPersistedSessions": { "type": "number", "default": 50, "description": "Maximum number of completed sessions to keep in memory for resume" },
+      "fallbackChannel": { "type": "string", "description": "Fallback notification channel (e.g. 'telegram:123456789')" },
+      "permissionMode": { "type": "string", "default": "bypassPermissions", "enum": ["default", "plan", "acceptEdits", "bypassPermissions"], "description": "Default permission mode for Claude Code sessions" }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@betrue/openclaw-claude-code-plugin",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.2.37",
+    "@sinclair/typebox": "^0.34.48",
+    "nanoid": "^3.3.7"
+  },
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "claude",
+    "claude-code",
+    "coding-agent",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alizarion/openclaw-claude-code-plugin.git"
+  },
+  "homepage": "https://github.com/alizarion/openclaw-claude-code-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/alizarion/openclaw-claude-code-plugin/issues"
+  },
+  "license": "MIT",
+  "author": "Betrue <hello@betrue.fr>",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/claude-bg.ts

@@ -0,0 +1,52 @@
+import { sessionManager, resolveOriginChannel } from "../shared";
+
+export function registerClaudeBgCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_bg",
+    description: "Send the current foreground session back to background",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const channelId = resolveOriginChannel(ctx);
+
+      // If a specific session is given, detach it
+      const ref = ctx.args?.trim();
+      if (ref) {
+        const session = sessionManager.resolve(ref);
+        if (!session) {
+          return { text: `Error: Session "${ref}" not found.` };
+        }
+        session.saveFgOutputOffset(channelId);
+        session.foregroundChannels.delete(channelId);
+        return {
+          text: `Session ${session.name} [${session.id}] moved to background.`,
+        };
+      }
+
+      // No argument — detach all foreground sessions for this channel
+      const allSessions = sessionManager.list("all");
+      const fgSessions = allSessions.filter((s) =>
+        s.foregroundChannels.has(channelId),
+      );
+
+      if (fgSessions.length === 0) {
+        return { text: "No session is currently in foreground." };
+      }
+
+      const names: string[] = [];
+      for (const s of fgSessions) {
+        s.saveFgOutputOffset(channelId);
+        s.foregroundChannels.delete(channelId);
+        names.push(`${s.name} [${s.id}]`);
+      }
+
+      return { text: `Moved to background: ${names.join(", ")}` };
+    },
+  });
+}

package/src/commands/claude-fg.ts

@@ -0,0 +1,71 @@
+import { sessionManager, formatDuration, resolveOriginChannel } from "../shared";
+
+export function registerClaudeFgCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_fg",
+    description: "Bring a Claude Code session to foreground by name or ID",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const ref = ctx.args?.trim();
+      if (!ref) {
+        return { text: "Usage: /claude_fg <name-or-id>" };
+      }
+
+      const session = sessionManager.resolve(ref);
+      if (!session) {
+        return { text: `Error: Session "${ref}" not found.` };
+      }
+
+      // Mark as foreground using the resolved channel (e.g. "telegram:123456")
+      const channelId = resolveOriginChannel(ctx);
+
+      // Get catchup output (produced while this channel was backgrounded)
+      const catchupLines = session.getCatchupOutput(channelId);
+
+      session.foregroundChannels.add(channelId);
+
+      const duration = formatDuration(session.duration);
+
+      const header = [
+        `Session ${session.name} [${session.id}] now in foreground.`,
+        `Status: ${session.status.toUpperCase()} | Duration: ${duration}`,
+        `${"─".repeat(60)}`,
+      ].join("\n");
+
+      // Build catchup section if there's missed output
+      let catchupSection = "";
+      if (catchupLines.length > 0) {
+        catchupSection = [
+          `📋 Catchup (${catchupLines.length} missed output${catchupLines.length === 1 ? "" : "s"}):`,
+          catchupLines.join("\n"),
+          `${"─".repeat(60)}`,
+        ].join("\n");
+      }
+
+      // If no catchup, fall back to showing recent lines
+      const body =
+        catchupLines.length > 0
+          ? catchupSection
+          : (session.getOutput(30).length > 0
+              ? session.getOutput(30).join("\n")
+              : "(no output yet)");
+
+      const footer =
+        session.status === "running" || session.status === "starting"
+          ? `\n${"─".repeat(60)}\nStreaming... Use /claude_bg to detach.`
+          : `\n${"─".repeat(60)}\nSession is ${session.status}.`;
+
+      // Mark that this channel has now seen all output up to this point
+      session.markFgOutputSeen(channelId);
+
+      return { text: `${header}\n${body}${footer}` };
+    },
+  });
+}

package/src/commands/claude-kill.ts

@@ -0,0 +1,42 @@
+import { sessionManager } from "../shared";
+
+export function registerClaudeKillCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_kill",
+    description: "Kill a Claude Code session by name or ID",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const ref = ctx.args?.trim();
+      if (!ref) {
+        return { text: "Usage: /claude_kill <name-or-id>" };
+      }
+
+      const session = sessionManager.resolve(ref);
+
+      if (!session) {
+        return { text: `Error: Session "${ref}" not found.` };
+      }
+
+      if (
+        session.status === "completed" ||
+        session.status === "failed" ||
+        session.status === "killed"
+      ) {
+        return {
+          text: `Session ${session.name} [${session.id}] is already ${session.status}. No action needed.`,
+        };
+      }
+
+      sessionManager.kill(session.id);
+
+      return { text: `Session ${session.name} [${session.id}] has been terminated.` };
+    },
+  });
+}

package/src/commands/claude-respond.ts

@@ -0,0 +1,92 @@
+import { sessionManager, notificationRouter } from "../shared";
+
+export function registerClaudeRespondCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_respond",
+    description:
+      "Send a follow-up message to a running Claude Code session. Usage: /claude_respond <id-or-name> <message>",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const args = (ctx.args ?? "").trim();
+      if (!args) {
+        return {
+          text: "Usage: /claude_respond <id-or-name> <message>\n       /claude_respond --interrupt <id-or-name> <message>",
+        };
+      }
+
+      // Parse optional --interrupt flag
+      let interrupt = false;
+      let remaining = args;
+      if (remaining.startsWith("--interrupt ")) {
+        interrupt = true;
+        remaining = remaining.slice("--interrupt ".length).trim();
+      }
+
+      // Parse: first word is the session ref, rest is the message
+      const spaceIdx = remaining.indexOf(" ");
+      if (spaceIdx === -1) {
+        return {
+          text: "Error: Missing message. Usage: /claude_respond <id-or-name> <message>",
+        };
+      }
+
+      const ref = remaining.slice(0, spaceIdx);
+      const message = remaining.slice(spaceIdx + 1).trim();
+
+      if (!message) {
+        return {
+          text: "Error: Empty message. Usage: /claude_respond <id-or-name> <message>",
+        };
+      }
+
+      const session = sessionManager.resolve(ref);
+      if (!session) {
+        return { text: `Error: Session "${ref}" not found.` };
+      }
+
+      if (session.status !== "running") {
+        return {
+          text: `Error: Session ${session.name} [${session.id}] is not running (status: ${session.status}).`,
+        };
+      }
+
+      try {
+        if (interrupt) {
+          await session.interrupt();
+        }
+        await session.sendMessage(message);
+
+        // Display the response in the origin channel so the conversation is visible
+        if (notificationRouter && session.originChannel) {
+          const respondMsg = [
+            `↩️ [${session.name}] Responded:`,
+            message,
+          ].join("\n");
+          notificationRouter.emitToChannel(session.originChannel, respondMsg);
+        }
+
+        const msgSummary =
+          message.length > 80 ? message.slice(0, 80) + "..." : message;
+
+        return {
+          text: [
+            `Message sent to ${session.name} [${session.id}].`,
+            interrupt ? `  (interrupted current turn)` : "",
+            `  "${msgSummary}"`,
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        };
+      } catch (err: any) {
+        return { text: `Error: ${err.message}` };
+      }
+    },
+  });
+}

package/src/commands/claude-resume.ts

@@ -0,0 +1,114 @@
+import { sessionManager, resolveOriginChannel, formatDuration } from "../shared";
+
+export function registerClaudeResumeCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_resume",
+    description:
+      "Resume a previous Claude Code session. Usage: /claude_resume <id-or-name> [prompt] or /claude_resume --list to see resumable sessions.",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx: any) => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      let args = (ctx.args ?? "").trim();
+      if (!args) {
+        return {
+          text: "Usage: /claude_resume <id-or-name> [prompt]\n       /claude_resume --list — list resumable sessions\n       /claude_resume --fork <id-or-name> [prompt] — fork instead of continuing",
+        };
+      }
+
+      // Handle --list flag
+      if (args === "--list") {
+        const persisted = sessionManager.listPersistedSessions();
+        if (persisted.length === 0) {
+          return { text: "No resumable sessions found. Sessions are persisted after completion." };
+        }
+
+        const lines = persisted.map((info) => {
+          const promptSummary =
+            info.prompt.length > 60
+              ? info.prompt.slice(0, 60) + "..."
+              : info.prompt;
+          const completedStr = info.completedAt
+            ? `completed ${formatDuration(Date.now() - info.completedAt)} ago`
+            : info.status;
+          return [
+            `  ${info.name} — ${completedStr}`,
+            `    Claude ID: ${info.claudeSessionId}`,
+            `    📁 ${info.workdir}`,
+            `    📝 "${promptSummary}"`,
+          ].join("\n");
+        });
+
+        return {
+          text: `Resumable sessions:\n\n${lines.join("\n\n")}`,
+        };
+      }
+
+      // Parse --fork flag
+      let fork = false;
+      if (args.startsWith("--fork ")) {
+        fork = true;
+        args = args.slice("--fork ".length).trim();
+      }
+
+      // Parse: first word is the session ref, rest is the prompt
+      const spaceIdx = args.indexOf(" ");
+      let ref: string;
+      let prompt: string;
+      if (spaceIdx === -1) {
+        ref = args;
+        prompt = "Continue where you left off.";
+      } else {
+        ref = args.slice(0, spaceIdx);
+        prompt = args.slice(spaceIdx + 1).trim() || "Continue where you left off.";
+      }
+
+      // Resolve the Claude session ID
+      const claudeSessionId = sessionManager.resolveClaudeSessionId(ref);
+      if (!claudeSessionId) {
+        return {
+          text: `Error: Could not find a Claude session ID for "${ref}".\nUse /claude_resume --list to see available sessions.`,
+        };
+      }
+
+      const config = ctx.config ?? {};
+
+      // Look up persisted info for workdir
+      const persisted = sessionManager.getPersistedSession(ref);
+      const workdir = persisted?.workdir ?? process.cwd();
+
+      try {
+        const session = sessionManager.spawn({
+          prompt,
+          workdir,
+          model: persisted?.model ?? config.defaultModel,
+          maxBudgetUsd: config.defaultBudgetUsd ?? 5,
+          resumeSessionId: claudeSessionId,
+          forkSession: fork,
+          originChannel: resolveOriginChannel(ctx),
+        });
+
+        const promptSummary =
+          prompt.length > 80 ? prompt.slice(0, 80) + "..." : prompt;
+
+        return {
+          text: [
+            `Session resumed${fork ? " (forked)" : ""}.`,
+            `  Name: ${session.name}`,
+            `  ID: ${session.id}`,
+            `  Resume from: ${claudeSessionId}`,
+            `  Dir: ${workdir}`,
+            `  Prompt: "${promptSummary}"`,
+          ].join("\n"),
+        };
+      } catch (err: any) {
+        return { text: `Error: ${err.message}` };
+      }
+    },
+  });
+}

package/src/commands/claude-sessions.ts

@@ -0,0 +1,27 @@
+import { sessionManager, formatSessionListing } from "../shared";
+
+export function registerClaudeSessionsCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_sessions",
+    description: "List all Claude Code sessions",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: () => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const sessions = sessionManager.list("all");
+
+      if (sessions.length === 0) {
+        return { text: "No sessions found." };
+      }
+
+      const lines = sessions.map(formatSessionListing);
+
+      return { text: lines.join("\n\n") };
+    },
+  });
+}

package/src/commands/claude-stats.ts

@@ -0,0 +1,20 @@
+import { sessionManager, formatStats } from "../shared";
+
+export function registerClaudeStatsCommand(api: any): void {
+  api.registerCommand({
+    name: "claude_stats",
+    description: "Show Claude Code Plugin usage metrics",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: () => {
+      if (!sessionManager) {
+        return {
+          text: "Error: SessionManager not initialized. The claude-code service must be running.",
+        };
+      }
+
+      const metrics = sessionManager.getMetrics();
+      return { text: formatStats(metrics) };
+    },
+  });
+}