claude-tmux 1.0.8 → 1.0.10

package/README.md

@@ -31,13 +31,12 @@ Add to your Claude Code MCP settings:
 Launch a new Claude Code instance in a tmux session.
 
 ```
-spawn("task-name", workdir, prompt)
+spawn(name, prompt, workdir)
 ```
 
 - `name`: Unique session name (e.g., 'refactor-auth', 'debug-api')
+- `prompt`: Initial prompt to send to Claude
 - `workdir`: Working directory for Claude to operate in
-- `prompt`: Initial prompt to send to Claude on startup
-- `dangerouslySkipPermissions`: Skip permission prompts for fully autonomous operation
 
 ### read
 
@@ -66,20 +65,14 @@ kill("task-name")
 ## Usage Pattern
 
 ```
-spawn("task-name", workdir, prompt) → starts session
-read("task-name") → waits for completion, returns output
-kill("task-name") → cleanup
-```
-
-For steering mid-task:
-
-```
-send("task-name", "do something else")
-read("task-name") → waits for completion, returns output
+spawn(name, prompt, workdir)  → start session
+read(name)                    → wait for completion, get output
+send(name, text)              → steer with follow-up
+read(name)                    → wait for completion, get output
+kill(name)                    → cleanup
 ```
 
 ## Tips
 
-- Use `dangerouslySkipPermissions: true` for fully autonomous operation
-- User can attach manually: `tmux attach -t claude-<name>`
-- Always kill sessions when done to avoid orphaned processes
+- Verify output shows task completion before killing. Idle agents are fine to leave running.
+- Attach manually: `tmux attach -t claude-<name>`

package/dist/index.js

@@ -4,7 +4,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { execSync } from "child_process";
 import { writeFileSync } from "fs";
+// Constants
 const SESSION_PREFIX = "claude-";
+const TIMEOUT_MS = 900000; // 15 minutes
+const POLL_INTERVAL_MS = 2000; // 2 seconds
+const INITIAL_DELAY_MS = 5000; // 5 seconds
+const CAPTURE_LINES = 100;
+const IDLE_THRESHOLD = 5; // consecutive idle polls
 function runTmux(args) {
     return execSync(`tmux ${args}`, { encoding: "utf-8", timeout: 10000 }).trim();
 }
@@ -16,6 +22,15 @@ function runTmuxSafe(args) {
         return null;
     }
 }
+function response(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function sessionExists(session) {
+    return runTmuxSafe(`has-session -t "${session}"`) !== null;
+}
 function sessionName(name) {
     return `${SESSION_PREFIX}${name.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
 }
@@ -50,17 +65,15 @@ function filterUIChrome(output) {
     return filtered.join('\n').trim();
 }
 async function waitForIdle(session) {
-    const timeout = 600000; // 10 minutes
-    const lines = 100; // Capture more lines to catch done signal
     const startTime = Date.now();
     let idleCount = 0;
     let output = "";
     // Initial delay to let Claude start working
-    await sleep(5000);
-    while (Date.now() - startTime < timeout) {
-        await sleep(2000);
+    await sleep(INITIAL_DELAY_MS);
+    while (Date.now() - startTime < TIMEOUT_MS) {
+        await sleep(POLL_INTERVAL_MS);
         try {
-            output = runTmux(`capture-pane -t "${session}" -p -S -${lines}`);
+            output = runTmux(`capture-pane -t "${session}" -p -S -${CAPTURE_LINES}`);
             // If busy, reset idle count and continue polling
             if (isBusy(output)) {
                 idleCount = 0;
@@ -71,21 +84,20 @@ async function waitForIdle(session) {
                 return filterUIChrome(output);
             }
             // Not busy - count consecutive idle polls
-            // After 2 consecutive non-busy polls, consider done
             idleCount++;
-            if (idleCount >= 2) {
+            if (idleCount >= IDLE_THRESHOLD) {
                 return filterUIChrome(output);
             }
         }
         catch (e) {
-            return `Error: ${e.message}`;
+            return `Error: ${errorMessage(e)}`;
         }
     }
-    return `Timeout after 10 minutes. Session still running.\n\n${filterUIChrome(output)}`;
+    return `Timeout after 15 minutes. Session still running.\n\n${filterUIChrome(output)}`;
 }
 const server = new McpServer({
     name: "claude-tmux",
-    version: "1.0.8",
+    version: "1.1.0",
 }, {
     instructions: `# claude-tmux: Autonomous Claude Agents
 
@@ -93,66 +105,50 @@ Spawn Claude Code instances in tmux sessions for long-running, independent tasks
 
 ## Tools
 - **spawn**: Start a new Claude session with a prompt.
-- **read**: Wait for a session to finish and return the output. You can continue other work while waiting.
-- **send**: Send a follow-up message to steer a running session mid-task.
-- **kill**: Terminate a session and clean up resources.
-
-## Pattern
-
-\`\`\`
-spawn("task-name", workdir, prompt) → starts session
-read("task-name") → waits for completion, returns output
-kill("task-name") → cleanup
-\`\`\`
-
-For steering mid-task:
-\`\`\`
-send("task-name", "do something else")
-read("task-name") → waits for completion, returns output
-\`\`\`
+- **read**: Wait for a session to finish and return output.
+- **send**: Send a follow-up message mid-task. Call read after.
+- **kill**: Terminate a session.
 
 ## Tips
-- Use \`dangerouslySkipPermissions: true\` for fully autonomous operation
-- User can attach manually: \`tmux attach -t claude-<name>\`
-- Always kill sessions when done`,
+- Verify output shows task completion before killing. Idle agents are fine to leave running.
+- User can attach manually: \`tmux attach -t claude-<name>\``,
 });
 server.tool("spawn", "Launch a new Claude Code instance in a tmux session. Creates an interactive session you can communicate with via send/read. The session runs until killed. Use for multi-turn conversations or tasks requiring steering.", {
     name: z.string().min(1).max(50).describe("Unique session name (e.g., 'refactor-auth', 'debug-api')"),
+    prompt: z.string().describe("Initial prompt to send to Claude on startup"),
     workdir: z.string().describe("Working directory for Claude to operate in"),
-    prompt: z.string().optional().describe("Initial prompt to send to Claude on startup"),
-    dangerouslySkipPermissions: z.boolean().optional().default(false).describe("Skip permission prompts for fully autonomous operation"),
-}, async ({ name, workdir, prompt, dangerouslySkipPermissions }) => {
+}, async ({ name, prompt, workdir }) => {
     const session = sessionName(name);
     runTmuxSafe(`kill-session -t "${session}"`);
     try {
         runTmux(`new-session -d -s "${session}" -c "${workdir}"`);
     }
     catch (e) {
-        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-    const flags = dangerouslySkipPermissions ? "--dangerously-skip-permissions " : "";
-    if (prompt) {
-        const tempFile = `/tmp/claude-prompt-${session}.txt`;
-        writeFileSync(tempFile, prompt);
-        runTmux(`send-keys -t "${session}" 'claude ${flags}"$(cat ${tempFile})" && rm ${tempFile}' Enter`);
+        return response(`Error: ${errorMessage(e)}`);
     }
-    else {
-        runTmux(`send-keys -t "${session}" 'claude ${flags}' Enter`);
-    }
-    return { content: [{ type: "text", text: `Started ${session}` }] };
+    const tempFile = `/tmp/claude-prompt-${session}.txt`;
+    writeFileSync(tempFile, prompt);
+    runTmux(`send-keys -t "${session}" 'claude --dangerously-skip-permissions "$(cat ${tempFile})" && rm ${tempFile}' Enter`);
+    return response(`Started ${session}`);
 });
 server.tool("read", "Wait for a Claude session to finish working and return the terminal output. You can continue other work while waiting.", {
     name: z.string().describe("Session name (as provided to spawn)"),
 }, async ({ name }) => {
     const session = sessionName(name);
+    if (!sessionExists(session)) {
+        return response(`Session '${name}' does not exist`);
+    }
     const output = await waitForIdle(session);
-    return { content: [{ type: "text", text: output }] };
+    return response(output);
 });
 server.tool("send", "Send a follow-up message to a running Claude session. Use to steer the session mid-task or provide additional instructions. Call read afterwards to get the result.", {
     name: z.string().describe("Session name (as provided to spawn)"),
     text: z.string().describe("Message to send to Claude"),
 }, async ({ name, text }) => {
     const session = sessionName(name);
+    if (!sessionExists(session)) {
+        return response(`Session '${name}' does not exist`);
+    }
     try {
         const escaped = text
             .replace(/\\/g, '\\\\')
@@ -161,23 +157,36 @@ server.tool("send", "Send a follow-up message to a running Claude session. Use t
             .replace(/`/g, '\\`');
         runTmux(`send-keys -t "${session}" -l "${escaped}"`);
         runTmux(`send-keys -t "${session}" Enter`);
-        return { content: [{ type: "text", text: `Sent to ${session}` }] };
+        return response(`Sent to ${session}`);
     }
     catch (e) {
-        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        return response(`Error: ${errorMessage(e)}`);
     }
 });
-server.tool("kill", "Terminate a Claude tmux session and clean up resources. Always kill sessions when done to avoid orphaned processes.", {
+server.tool("kill", "Terminate a Claude tmux session and clean up resources.", {
     name: z.string().describe("Session name (as provided to spawn)"),
 }, async ({ name }) => {
     const session = sessionName(name);
+    if (!sessionExists(session)) {
+        return response(`Session '${name}' does not exist`);
+    }
     try {
         runTmux(`kill-session -t "${session}"`);
-        return { content: [{ type: "text", text: `Killed ${session}` }] };
+        return response(`Killed ${session}`);
     }
     catch (e) {
-        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        return response(`Error: ${errorMessage(e)}`);
+    }
+});
+server.tool("list", "List all active Claude tmux sessions.", {}, async () => {
+    const output = runTmuxSafe(`list-sessions -F "#{session_name}"`) ?? "";
+    const sessions = output.split('\n')
+        .filter(s => s.startsWith(SESSION_PREFIX))
+        .map(s => s.slice(SESSION_PREFIX.length));
+    if (sessions.length === 0) {
+        return response("No active sessions");
     }
+    return response(sessions.join('\n'));
 });
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-tmux",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "MCP server for orchestrating multiple Claude Code instances via tmux",
   "type": "module",
   "main": "dist/index.js",