claude-tmux 1.0.9 → 1.0.11

package/README.md

@@ -54,6 +54,14 @@ Send a follow-up message to a running Claude session.
 send("task-name", "do something else")
 ```
 
+### list
+
+List all active Claude tmux sessions. Useful for discovery across conversations.
+
+```
+list()
+```
+
 ### kill
 
 Terminate a Claude tmux session and clean up resources.
@@ -74,5 +82,5 @@ kill(name)                    → cleanup
 
 ## Tips
 
+- Verify output shows task completion before killing. Idle agents are fine to leave running.
 - Attach manually: `tmux attach -t claude-<name>`
-- Always kill sessions when done to avoid orphaned processes

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.9",
+    version: "1.1.0",
 }, {
     instructions: `# claude-tmux: Autonomous Claude Agents
 
@@ -93,23 +105,14 @@ 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(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
-\`\`\`
+- **read**: Wait for a session to finish and return output.
+- **send**: Send a follow-up message mid-task. Call read after.
+- **list**: List active sessions (useful for discovery across conversations).
+- **kill**: Terminate a session.
 
 ## Tips
-- 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')"),
@@ -122,25 +125,31 @@ server.tool("spawn", "Launch a new Claude Code instance in a tmux session. Creat
         runTmux(`new-session -d -s "${session}" -c "${workdir}"`);
     }
     catch (e) {
-        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        return response(`Error: ${errorMessage(e)}`);
     }
     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 { content: [{ type: "text", text: `Started ${session}` }] };
+    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, '\\\\')
@@ -149,23 +158,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.9",
+  "version": "1.0.11",
   "description": "MCP server for orchestrating multiple Claude Code instances via tmux",
   "type": "module",
   "main": "dist/index.js",