claude-code-remote-pilot 0.1.5 → 0.2.1

package/README.md

@@ -1,388 +1,184 @@
 # Claude Code Remote Pilot
 
-Interactive Claude Code supervisor using `tmux`, Node.js, and notifications.
+Spawn and supervise multiple Claude Code sessions from a single interactive terminal.
 
-The current MVP keeps Claude Code usable in the normal terminal while adding a small supervisor layer that can detect usage limits, notify you, wait, and send `continue` automatically.
+Run it once. Spawn Claude into as many project directories as you want. Walk away — it handles usage limits, waits for resets, sends `continue` automatically, and notifies you on Telegram. Come back to finished work.
 
-Longer term, this project is moving toward a local multi-session Claude Code dashboard.
+Each Claude session lives in its own named tmux session. You can `tmux attach -t <name>` from any terminal at any time, independently of the pilot.
 
 ---
 
-## Current Status
+## How it works
 
-This repository currently contains:
-
-- `claude-pilot.sh` — bash/tmux watcher MVP
-- `bin/claude-pilot.js` — npm CLI wrapper
-- `package.json` — npm package entry
-- `docs/ARCHITECTURE_UPDATE.md` — architecture direction
-- `TASKS.md` — implementation roadmap
-
-Current mode:
-
-```text
-Human → tmux terminal → Claude Code
-              ↑
-              │
-        Claude Code Remote Pilot
-        - watches output
-        - detects limits
-        - sends notifications
-        - resumes automatically
 ```
+npx claude-code-remote-pilot
+  │
+  ├── asks: mount current directory as a session?
+  ├── asks: set up Telegram? (optional)
+  └── starts interactive prompt
 
-Future mode:
-
-```text
-Browser Dashboard
-        ↓
-WebSocket / REST API
-        ↓
-Node.js Supervisor
-        ↓
-Session Manager
-        ↓
-tmux sessions
-        ↓
-Claude Code instances
-```
-
----
-
-## Why This Exists
-
-Claude Code is useful for long-running coding tasks, but usage/rate limits can interrupt the flow.
-
-This project aims to provide:
-
-- persistent Claude Code sessions
-- automatic resume after limit reset
-- human-supervised automation
-- local-first workflow
-- multi-session management
-- eventual web dashboard control
-
-It is intentionally **not** designed as an unsafe fully autonomous agent loop.
-
----
-
-## Features
-
-Current MVP:
-
-- tmux session persistence
-- auto-create Claude tmux session
-- terminal output capture
-- usage/rate limit detection
-- reset-time parsing
-- Telegram notification support
-- automatic `continue` after waiting
-- duplicate event protection
-- resume cooldown protection
-- npm CLI wrapper
-
-Planned:
-
-- Node.js runtime refactor
-- multiple Claude sessions
-- web dashboard
-- WebSocket live output
-- session registry
-- pluggable detectors
-- notification providers
-- persistent session state
-- policy/safety engine
-
----
-
-## Requirements
-
-- Node.js >= 18
-- bash
-- tmux
-- curl
-- python3 recommended for better reset-time parsing
-- Claude Code CLI installed and authenticated
-
----
-
-## Installing tmux
-
-**macOS (Homebrew):**
-
-```bash
-brew install tmux
+claude-pilot> spawn ~/projects/api-refactor
+claude-pilot> spawn ~/projects/mobile-app
+claude-pilot> watch
 ```
 
-**Ubuntu / Debian:**
-
-```bash
-sudo apt update && sudo apt install tmux curl python3
 ```
-
-**Fedora / RHEL / CentOS:**
-
-```bash
-sudo dnf install tmux curl python3
+  Claude Code Remote Pilot
+  ─────────────────────────────────────────────────────────────────
+  SESSION                STATUS          DIRECTORY
+  ─────────────────────────────────────────────────────────────────
+  api-refactor           running         ~/projects/api-refactor
+  mobile-app             limit 42m       ~/projects/mobile-app
+  ─────────────────────────────────────────────────────────────────
+  2 sessions   14:23:05   q to exit
 ```
 
-**Arch Linux:**
+From any other terminal, interact with a session directly:
 
 ```bash
-sudo pacman -S tmux curl python3
+tmux attach -t api-refactor
+# Ctrl+B then D to detach back to your terminal
 ```
 
-**Windows (WSL):**
+---
 
-Run inside your WSL terminal (Ubuntu recommended):
+## Install
 
 ```bash
-sudo apt update && sudo apt install tmux curl python3
+npx claude-code-remote-pilot
 ```
 
-Verify tmux is working:
+Or install globally:
 
 ```bash
-tmux -V
+npm install -g claude-code-remote-pilot
+claude-remote-pilot
 ```
 
 ---
 
-## Install
+## Requirements
 
-### From GitHub
+- Node.js >= 18
+- tmux
+- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
 
-```bash
-git clone https://github.com/mekku/claude-code-remote-pilot.git
-cd claude-code-remote-pilot
-yarn install
-```
+The pilot will prompt you to install missing dependencies on first run.
 
-Run locally:
+### Installing tmux manually
 
+**macOS:**
 ```bash
-yarn pilot
+brew install tmux
 ```
 
-or:
-
+**Ubuntu / Debian:**
 ```bash
-node bin/claude-pilot.js
+sudo apt update && sudo apt install tmux
 ```
 
-### As npm package
-
+**Fedora / RHEL:**
 ```bash
-npm install -g claude-code-remote-pilot
-claude-remote-pilot
+sudo dnf install tmux
 ```
 
-or:
-
+**Arch:**
 ```bash
-npx claude-code-remote-pilot
+sudo pacman -S tmux
 ```
 
----
-
-## Telegram Setup
-
-Create a bot with `@BotFather` and get your bot token.
-
-Send a message to your bot, then get your chat ID:
-
+**Windows (WSL):**
 ```bash
-curl "https://api.telegram.org/bot<BOT_TOKEN>/getUpdates"
-```
-
-Look for:
-
-```json
-"chat": {
-  "id": 123456789
-}
+sudo apt update && sudo apt install tmux
 ```
 
-Run:
-
-```bash
-export TELEGRAM_BOT_TOKEN="xxx"
-export TELEGRAM_CHAT_ID="123456789"
+---
 
-yarn pilot
-```
+## Commands
 
-Telegram is optional. If not configured, messages are printed locally.
+| Command | Description |
+|---|---|
+| `spawn <path> [name]` | Start Claude at a path. Name defaults to the directory name. |
+| `list` | One-shot status of all sessions. |
+| `watch` | Live-updating session monitor. Press `q` to exit. |
+| `attach <name>` | Open a tmux session in the current terminal. |
+| `kill <name>` | Stop a session. |
+| `help` | Show command reference. |
+| `exit` | Quit the pilot. Sessions keep running in tmux. |
 
 ---
 
-## Basic Usage
+## Telegram setup
 
-Start pilot:
+Create a bot via `@BotFather` and get your token.
 
-```bash
-yarn pilot
-```
-
-Attach to Claude:
+Get your chat ID:
 
 ```bash
-tmux attach -t claude
+curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
 ```
 
-Detach without killing Claude:
+Run the pilot — it will ask for these values interactively, or set them as environment variables:
 
-```text
-Ctrl+B then D
+```bash
+export TELEGRAM_BOT_TOKEN="your-token"
+export TELEGRAM_CHAT_ID="your-chat-id"
+npx claude-code-remote-pilot
 ```
 
-The watcher keeps running and watches the tmux session.
-
 ---
 
-## Environment Variables
+## Environment variables
 
 | Variable | Default | Description |
-|---|---:|---|
-| `TELEGRAM_BOT_TOKEN` | empty | Telegram bot token |
-| `TELEGRAM_CHAT_ID` | empty | Telegram chat ID |
-| `CLAUDE_SESSION` | `claude` | tmux session name |
-| `CLAUDE_COMMAND` | `claude` | command used to start Claude |
-| `CHECK_INTERVAL_SECONDS` | `30` | watcher interval |
-| `LIMIT_FALLBACK_WAIT_SECONDS` | `300` | fallback wait if reset time cannot be parsed |
-| `POST_RESUME_COOLDOWN_SECONDS` | `180` | avoid repeated resume spam |
-| `CAPTURE_LINES` | `500` | number of tmux output lines to inspect |
-| `RESUME_COMMAND` | `continue` | command sent after reset |
-| `START_IF_MISSING` | `1` | auto-create tmux session if missing |
-| `LIMIT_REGEX` | built-in | custom regex for limit detection |
-| `PERMISSION_REGEX` | built-in | custom regex for permission detection |
-
-Example:
-
-```bash
-CLAUDE_SESSION=claude-buildx-api \
-CLAUDE_COMMAND="claude" \
-TELEGRAM_BOT_TOKEN="xxx" \
-TELEGRAM_CHAT_ID="123456789" \
-yarn pilot
-```
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token |
+| `TELEGRAM_CHAT_ID` | — | Telegram chat ID |
+| `CLAUDE_COMMAND` | `claude` | Command used to start Claude |
 
 ---
 
-## Recommended Claude Workflow
+## Recommended Claude workflow
 
-For long-running work, ask Claude to maintain external state:
+For long-running tasks, ask Claude to keep external state:
 
-```text
+```
 Maintain TASK_STATE.md.
-After every meaningful step:
-- update completed work
-- update current status
-- update next exact action
-
-If interrupted:
-- read TASK_STATE.md
-- resume from the next unfinished step.
+After every meaningful step update: what's done, current status, next exact action.
+If interrupted, read TASK_STATE.md and resume from where you left off.
 ```
 
-This matters because LLM context can drift over long sessions. External state is the real resume brain.
+Context can drift over long sessions. External state is the real resume brain.
 
 ---
 
-## Safety Notes
+## Safety
 
-Avoid starting with:
+Start Claude without `--dangerously-skip-permissions` unless you know what you're doing. The pilot is designed for human-supervised workflows:
 
-```bash
-claude --dangerously-skip-permissions
-```
-
-That mode allows Claude to execute commands and modify files without asking.
-
-Claude Code Pilot should begin as a **human-supervised** tool:
-
-Allowed early:
-
-- watch output
-- notify
-- send `continue`
-- send user-provided input
-- show latest results
-
-Avoid early:
-
-- auto-approve permissions
-- arbitrary remote shell execution
-- autonomous destructive actions
+- watches output
+- sends notifications
+- sends `continue` after limit resets
+- does **not** auto-approve permissions or execute arbitrary commands
 
 ---
 
 ## Roadmap
 
-See:
-
-- [`docs/ARCHITECTURE_UPDATE.md`](docs/ARCHITECTURE_UPDATE.md)
-- [`TASKS.md`](TASKS.md)
-
-High-level phases:
-
-1. tmux watcher MVP
-2. Node.js runtime refactor
-3. multi-session support
-4. detection engine
-5. notification providers
-6. web dashboard
-7. persistent state
-8. safety/policy engine
-9. optional node-pty backend
-
----
-
-## Target Dashboard Concept
-
-Planned local dashboard:
-
-```text
-Sidebar
-├── claude-buildx-api
-├── claude-pos-mobile
-├── claude-auth-refactor
-└── claude-research
-
-Main Panel
-├── live output
-├── status badge
-├── input box
-├── continue button
-└── auto-resume toggle
-```
-
-This allows normal local terminal interaction when at the machine, plus remote-lite control when away.
+- [x] tmux session management
+- [x] usage limit detection and auto-resume
+- [x] Telegram notifications
+- [x] interactive REPL — spawn, watch, attach, kill
+- [x] multi-session support
+- [ ] web dashboard (sessions connect to pilot server)
+- [ ] persistent session state
+- [ ] pluggable notification providers
+- [ ] safety / policy engine
 
 ---
 
 ## Philosophy
 
-Claude Code Pilot is intended to become:
-
-```text
-human-supervised local AI runtime
-```
-
-not:
-
-```text
-fully autonomous AI operator
-```
-
-The system prioritizes:
-
-- persistence
-- observability
-- recoverability
-- resumability
-- multi-session control
-- human intervention
-- practical workflows
+A human-supervised local runtime for Claude Code. Not a fully autonomous agent loop.
 
-Small tools first. Spaceship later.
+Small tools first. Dashboard later.

package/bin/claude-pilot.js

@@ -1,31 +1,24 @@
 #!/usr/bin/env node
+'use strict';
 
-const { spawn, execSync } = require('child_process');
+const { execSync, spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
-
-const scriptPath = path.resolve(__dirname, '..', 'claude-pilot.sh');
-
-if (!fs.existsSync(scriptPath)) {
-  console.error('claude-pilot.sh not found');
-  process.exit(1);
-}
-
 const readline = require('readline');
+const SessionManager = require('../lib/SessionManager');
+
+// ─── dependency checks ────────────────────────────────────────────────────────
 
-function checkDep(cmd) {
-  try { execSync(`command -v ${cmd}`, { stdio: 'ignore' }); return true; }
-  catch { return false; }
+function has(cmd) {
+  try { execSync(`command -v ${cmd}`, { stdio: 'ignore' }); return true; } catch { return false; }
 }
 
 function detectPlatform() {
-  const platform = process.platform;
-  if (platform === 'darwin') return 'macos';
-  if (platform === 'win32') return 'windows';
+  if (process.platform === 'darwin') return 'macos';
   try {
-    const release = fs.readFileSync('/etc/os-release', 'utf8');
-    if (/ID=arch/i.test(release)) return 'arch';
-    if (/ID=(fedora|rhel|centos)/i.test(release)) return 'fedora';
+    const r = fs.readFileSync('/etc/os-release', 'utf8');
+    if (/ID=arch/i.test(r)) return 'arch';
+    if (/ID=(fedora|rhel|centos)/i.test(r)) return 'fedora';
   } catch {}
   return 'debian';
 }
@@ -38,126 +31,241 @@ function tmuxInstallCmd() {
   return 'sudo apt-get install -y tmux';
 }
 
-function prompt(question) {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(question, (answer) => { rl.close(); resolve(answer.trim().toLowerCase()); });
-  });
-}
-
-async function ensureDep(cmd, label, installCmd) {
-  if (checkDep(cmd)) return;
+async function ensureDep(rl, cmd, label, installCmd) {
+  if (has(cmd)) return;
   console.log(`\n${label} is not installed.`);
-  const answer = await prompt(`Install it now? (y/n) `);
+  const answer = await question(rl, 'Install it now? (y/n) ');
   if (answer !== 'y' && answer !== 'yes') {
-    console.log(`Skipping. Run manually: ${installCmd}`);
+    console.log(`Run manually: ${installCmd}`);
     process.exit(1);
   }
   console.log(`Running: ${installCmd}\n`);
-  try {
-    execSync(installCmd, { stdio: 'inherit' });
-    console.log(`\n${label} installed successfully.\n`);
-  } catch {
-    console.error(`\nInstall failed. Try running manually: ${installCmd}`);
-    process.exit(1);
+  try { execSync(installCmd, { stdio: 'inherit' }); console.log(`\n${label} installed.\n`); }
+  catch { console.error(`Install failed. Run manually: ${installCmd}`); process.exit(1); }
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function question(rl, q) {
+  return new Promise(r => rl.question(q, a => r(a.trim().toLowerCase())));
+}
+
+function questionRaw(rl, q) {
+  return new Promise(r => rl.question(q, a => r(a.trim())));
+}
+
+// ─── telegram setup ───────────────────────────────────────────────────────────
+
+async function setupTelegram(rl) {
+  if (process.env.TELEGRAM_BOT_TOKEN && process.env.TELEGRAM_CHAT_ID) {
+    return { token: process.env.TELEGRAM_BOT_TOKEN, chatId: process.env.TELEGRAM_CHAT_ID };
   }
+  console.log('\nTelegram notifications (optional).');
+  const answer = await question(rl, 'Set up Telegram now? (y/n) ');
+  if (answer !== 'y' && answer !== 'yes') { console.log('Skipping.\n'); return {}; }
+  const token = await questionRaw(rl, 'Bot token: ');
+  const chatId = await questionRaw(rl, 'Chat ID: ');
+  console.log('Telegram configured.\n');
+  return { token, chatId };
 }
 
-async function setupTelegram() {
-  if (process.env.TELEGRAM_BOT_TOKEN && process.env.TELEGRAM_CHAT_ID) return;
-  console.log('\nTelegram notifications are not configured (optional).');
-  const answer = await prompt('Set up Telegram now? (y/n) ');
-  if (answer !== 'y' && answer !== 'yes') {
-    console.log('Skipping. You can set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID later.\n');
-    return;
+// ─── table rendering ──────────────────────────────────────────────────────────
+
+const C = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  dim: '\x1b[2m',
+};
+
+function formatStatus(session) {
+  if (session.status === 'running') return { plain: 'running', colored: `${C.green}running${C.reset}` };
+  if (session.status === 'limit') {
+    const secs = session.resumeAt ? Math.max(0, Math.round((session.resumeAt - Date.now()) / 1000)) : 0;
+    const label = `limit ${Math.ceil(secs / 60)}m`;
+    return { plain: label, colored: `${C.yellow}${label}${C.reset}` };
   }
-  const token = await prompt('Enter your Telegram bot token: ');
-  const chatId = await prompt('Enter your Telegram chat ID: ');
-  if (token) process.env.TELEGRAM_BOT_TOKEN = token.trim();
-  if (chatId) process.env.TELEGRAM_CHAT_ID = chatId.trim();
-  console.log('Telegram configured for this session.\n');
+  if (session.status === 'needs-input') return { plain: 'needs input', colored: `${C.yellow}needs input${C.reset}` };
+  if (session.status === 'ended') return { plain: 'ended', colored: `${C.dim}ended${C.reset}` };
+  return { plain: session.status, colored: session.status };
 }
 
-function printGuide() {
-  const session = process.env.CLAUDE_SESSION;
-  const workdir = process.env.CLAUDE_WORKDIR;
-  console.log(`
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Claude Code Remote Pilot — Ready
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+function trunc(str, len) {
+  return str.length <= len ? str.padEnd(len) : str.slice(0, len - 1) + '…';
+}
 
-  Session : ${session}
-  Dir     : ${workdir}
+function renderTable(sessions) {
+  const NW = 20, SW = 14;
+  const bar = '  ' + '─'.repeat(NW + SW + 42);
+  const header = `  ${'SESSION'.padEnd(NW)}  ${'STATUS'.padEnd(SW)}  DIRECTORY`;
+  const rows = sessions.map(s => {
+    const { plain, colored } = formatStatus(s);
+    const pad = ' '.repeat(Math.max(0, SW - plain.length));
+    return `  ${trunc(s.name, NW)}  ${colored}${pad}  ${trunc(s.path, 40)}`;
+  });
+  const footer = `  ${sessions.length} session${sessions.length !== 1 ? 's' : ''}   ${new Date().toLocaleTimeString()}   q to exit`;
+  return ['\n', '  Claude Code Remote Pilot', bar, header, bar, ...rows, bar, footer, ''].join('\n');
+}
+
+// ─── watch mode ───────────────────────────────────────────────────────────────
+
+function startWatch(manager, rl) {
+  rl.removeAllListeners('close');
+  rl.close();
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdin.resume();
 
-  To talk to Claude:
-    tmux attach -t ${session}
+  function draw() {
+    process.stdout.write('\x1B[2J\x1B[0f');
+    process.stdout.write(renderTable(manager.list()));
+  }
 
-  To detach without stopping Claude:
-    Press  Ctrl+B  then  D
+  draw();
+  const interval = setInterval(draw, 2000);
 
-  The pilot will:
-    • detect usage/rate limits
-    • wait for the reset
-    • send "continue" automatically
-    • notify you via Telegram (if configured)
+  function onData(buf) {
+    const key = buf.toString();
+    if (key === 'q' || key === 'Q' || buf[0] === 3) {
+      clearInterval(interval);
+      process.stdin.removeListener('data', onData);
+      if (process.stdin.isTTY) process.stdin.setRawMode(false);
+      process.stdout.write('\x1B[2J\x1B[0f');
+      startREPL(manager);
+    }
+  }
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-`);
+  process.stdin.on('data', onData);
 }
 
-async function main() {
-  await ensureDep('tmux', 'tmux', tmuxInstallCmd());
-  await ensureDep('claude', 'Claude Code CLI', 'npm install -g @anthropic-ai/claude-code');
-  await setupTelegram();
-  printGuide();
-
-  const child = spawn('bash', [scriptPath], {
-    stdio: 'inherit',
-    env: process.env,
+// ─── REPL ─────────────────────────────────────────────────────────────────────
+
+const HELP = `
+  spawn <path> [name]   Start Claude at path (name defaults to dir name)
+  list                  Show all sessions
+  watch                 Live session monitor  (q to exit)
+  attach <name>         Open tmux session in this terminal
+  kill <name>           Stop a session
+  help                  Show this help
+  exit                  Quit pilot  (sessions keep running in tmux)
+`;
+
+function startREPL(manager) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: 'claude-pilot> ',
+  });
+
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const parts = line.trim().split(/\s+/).filter(Boolean);
+    const [cmd, ...args] = parts;
+
+    if (!cmd) { rl.prompt(); return; }
+
+    try {
+      switch (cmd) {
+        case 'spawn': {
+          if (!args[0]) { console.log('  Usage: spawn <path> [name]'); break; }
+          const session = manager.spawn(args[0], args[1]);
+          console.log(`  ✓ "${session.name}" started at ${session.path}`);
+          console.log(`    tmux attach -t ${session.name}`);
+          break;
+        }
+        case 'list': {
+          const sessions = manager.list();
+          if (!sessions.length) { console.log('  No sessions.'); break; }
+          console.log('');
+          sessions.forEach(s => {
+            const { plain } = formatStatus(s);
+            console.log(`  ${s.name.padEnd(22)} ${plain.padEnd(14)} ${s.path}`);
+          });
+          console.log('');
+          break;
+        }
+        case 'watch': {
+          const sessions = manager.list();
+          if (!sessions.length) { console.log('  No sessions.'); break; }
+          startWatch(manager, rl);
+          return;
+        }
+        case 'attach': {
+          if (!args[0]) { console.log('  Usage: attach <name>'); break; }
+          rl.pause();
+          const child = spawn('tmux', ['attach-session', '-t', args[0]], { stdio: 'inherit' });
+          child.on('exit', () => { process.stdout.write('\n'); rl.resume(); rl.prompt(); });
+          return;
+        }
+        case 'kill': {
+          if (!args[0]) { console.log('  Usage: kill <name>'); break; }
+          manager.kill(args[0]);
+          console.log(`  ✓ "${args[0]}" killed.`);
+          break;
+        }
+        case 'help': {
+          console.log(HELP);
+          break;
+        }
+        case 'exit':
+        case 'quit': {
+          console.log('\n  Sessions keep running. Use tmux to attach.\n');
+          process.exit(0);
+        }
+        default:
+          console.log(`  Unknown command: ${cmd}. Type help.`);
+      }
+    } catch (err) {
+      console.error(`  Error: ${err.message}`);
+    }
+
+    rl.prompt();
   });
 
-  child.on('exit', (code) => {
-    process.exit(code || 0);
+  rl.on('close', () => {
+    console.log('\n  Sessions keep running. Use tmux to attach.\n');
+    process.exit(0);
   });
 }
 
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
-  console.log(`
+// ─── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(`
 Claude Code Remote Pilot
 
 Usage:
-  claude-remote-pilot [--session <name>]
+  claude-remote-pilot
 
-Options:
-  --session <name>   Name for this Claude session (defaults to current directory name)
+Interactive commands:
+${HELP}`);
+    process.exit(0);
+  }
 
-Environment variables:
-  TELEGRAM_BOT_TOKEN
-  TELEGRAM_CHAT_ID
-  CLAUDE_COMMAND
+  const setupRl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
-Example:
-  claude-remote-pilot --session my-project
-  TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=123456 claude-remote-pilot --session api
+  await ensureDep(setupRl, 'tmux', 'tmux', tmuxInstallCmd());
+  await ensureDep(setupRl, 'claude', 'Claude Code CLI', 'npm install -g @anthropic-ai/claude-code');
+  const telegram = await setupTelegram(setupRl);
 
-Attach to session:
-  tmux attach -t <name>
-`);
-  process.exit(0);
-}
+  const manager = new SessionManager({ telegram });
 
-// Parse --session flag, fall back to current directory name
-const sessionFlagIndex = process.argv.indexOf('--session');
-const sessionName = sessionFlagIndex !== -1
-  ? process.argv[sessionFlagIndex + 1]
-  : path.basename(process.cwd());
+  const cwd = process.cwd();
+  const defaultName = path.basename(cwd);
+  const mount = await question(setupRl, `Mount current directory as a session? (${defaultName}) [y/n] `);
 
-if (!sessionName || sessionName.startsWith('--')) {
-  console.error('Error: --session requires a name, e.g. --session my-project');
-  process.exit(1);
-}
+  if (mount === 'y' || mount === 'yes') {
+    const rawName = await questionRaw(setupRl, `Session name [${defaultName}]: `);
+    const session = manager.spawn(cwd, rawName || defaultName);
+    console.log(`  ✓ "${session.name}" started at ${session.path}`);
+    console.log(`    tmux attach -t ${session.name}\n`);
+  }
 
-process.env.CLAUDE_SESSION = sessionName;
-process.env.CLAUDE_WORKDIR = process.cwd();
+  setupRl.close();
+
+  console.log('  Type help for commands.\n');
+  startREPL(manager);
+}
 
-main();
+main().catch(err => { console.error(err.message); process.exit(1); });

package/lib/SessionManager.js

@@ -0,0 +1,56 @@
+'use strict';
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const Watcher = require('./Watcher');
+
+function sanitizeName(name) {
+  return name.replace(/[.:\s]/g, '-');
+}
+
+class SessionManager {
+  constructor({ telegram = {} } = {}) {
+    this.sessions = new Map();
+    this.telegram = telegram;
+  }
+
+  spawn(dirPath, name) {
+    const resolved = path.resolve(dirPath.replace(/^~/, process.env.HOME || ''));
+    if (!fs.existsSync(resolved)) throw new Error(`Path not found: ${resolved}`);
+
+    const sessionName = sanitizeName(name || path.basename(resolved));
+    if (this.sessions.has(sessionName)) throw new Error(`Session "${sessionName}" already exists.`);
+
+    // Kill stale tmux session from a previous crashed run
+    try { execSync(`tmux has-session -t "${sessionName}"`, { stdio: 'ignore' });
+      execSync(`tmux kill-session -t "${sessionName}"`, { stdio: 'ignore' });
+    } catch {}
+
+    execSync(`tmux new-session -d -s "${sessionName}" -c "${resolved}" "claude"`, { stdio: 'ignore' });
+
+    const session = { name: sessionName, path: resolved, status: 'running', startedAt: new Date(), resumeAt: null };
+
+    const watcher = new Watcher(session, {
+      telegram: this.telegram,
+      onEnded: (s) => this.sessions.delete(s.name),
+    });
+    watcher.start();
+
+    this.sessions.set(sessionName, { session, watcher });
+    return session;
+  }
+
+  kill(name) {
+    const entry = this.sessions.get(name);
+    if (!entry) throw new Error(`Session "${name}" not found.`);
+    entry.watcher.stop();
+    try { execSync(`tmux kill-session -t "${name}"`, { stdio: 'ignore' }); } catch {}
+    this.sessions.delete(name);
+  }
+
+  list() {
+    return [...this.sessions.values()].map(e => e.session);
+  }
+}
+
+module.exports = SessionManager;

package/lib/Watcher.js

@@ -0,0 +1,116 @@
+'use strict';
+const { execSync } = require('child_process');
+const crypto = require('crypto');
+const notifier = require('./notifier');
+
+const LIMIT_RE = /hit your limit|usage limit|rate limit|limit reached|try again|resets/i;
+const PERM_RE = /permission|do you want to proceed|approve/i;
+
+class Watcher {
+  constructor(session, opts = {}) {
+    this.session = session;
+    this.telegram = opts.telegram || {};
+    this.onEnded = opts.onEnded || (() => {});
+    this.checkInterval = opts.checkInterval || 30000;
+    this.fallbackWait = opts.fallbackWait || 300;
+    this.cooldown = opts.cooldown || 180;
+    this.captureLines = opts.captureLines || 500;
+    this.lastHash = '';
+    this.lastResumeAt = 0;
+    this._timer = null;
+    this._busy = false;
+  }
+
+  start() {
+    this._timer = setInterval(() => this._check(), this.checkInterval);
+  }
+
+  stop() {
+    if (this._timer) clearInterval(this._timer);
+    this._timer = null;
+  }
+
+  _capture() {
+    try {
+      return execSync(
+        `tmux capture-pane -pt "${this.session.name}" -S "-${this.captureLines}"`,
+        { encoding: 'utf8' }
+      );
+    } catch { return ''; }
+  }
+
+  _hash(text) {
+    return crypto.createHash('sha256').update(text.slice(-2000)).digest('hex');
+  }
+
+  _parseWait(text) {
+    const m = text.match(/(?:try again|retry|wait).*?in\s+(\d+)\s*(second|minute|hour)/i);
+    if (m) {
+      const v = parseInt(m[1]);
+      if (m[2].startsWith('second')) return Math.max(10, v);
+      if (m[2].startsWith('minute')) return Math.max(10, v * 60);
+      return Math.max(10, v * 3600);
+    }
+    return this.fallbackWait;
+  }
+
+  async _check() {
+    if (this._busy) return;
+    this._busy = true;
+    try {
+      try { execSync(`tmux has-session -t "${this.session.name}"`, { stdio: 'ignore' }); }
+      catch {
+        this.stop();
+        this.onEnded(this.session);
+        notifier.send(this.telegram.token, this.telegram.chatId,
+          `Pilot: session "${this.session.name}" ended.`);
+        return;
+      }
+
+      const text = this._capture();
+
+      if (LIMIT_RE.test(text)) {
+        await this._handleLimit(text);
+      } else if (PERM_RE.test(text)) {
+        if (this.session.status !== 'needs-input') {
+          this.session.status = 'needs-input';
+          notifier.send(this.telegram.token, this.telegram.chatId,
+            `Pilot: "${this.session.name}" needs input.`);
+        }
+      } else if (this.session.status !== 'running') {
+        this.session.status = 'running';
+        this.session.resumeAt = null;
+      }
+    } finally {
+      this._busy = false;
+    }
+  }
+
+  async _handleLimit(text) {
+    const hash = this._hash(text);
+    if (hash === this.lastHash) return;
+    if ((Date.now() / 1000) - this.lastResumeAt < this.cooldown) return;
+
+    this.lastHash = hash;
+    const wait = this._parseWait(text);
+    this.session.status = 'limit';
+    this.session.resumeAt = Date.now() + wait * 1000;
+
+    notifier.send(this.telegram.token, this.telegram.chatId,
+      `Pilot: limit in "${this.session.name}". Waiting ${wait}s before resume.`);
+
+    await new Promise(r => setTimeout(r, wait * 1000));
+
+    try { execSync(`tmux send-keys -t "${this.session.name}" "continue" Enter`, { stdio: 'ignore' }); }
+    catch {}
+
+    this.lastResumeAt = Date.now() / 1000;
+    this.session.status = 'running';
+    this.session.resumeAt = null;
+
+    notifier.send(this.telegram.token, this.telegram.chatId,
+      `Pilot: resumed "${this.session.name}".`);
+  }
+}
+
+module.exports = Watcher;

package/lib/notifier.js

@@ -0,0 +1,16 @@
+'use strict';
+const { execSync } = require('child_process');
+
+function send(token, chatId, message) {
+  if (!token || !chatId) return;
+  try {
+    execSync(
+      `curl -sS -X POST "https://api.telegram.org/bot${token}/sendMessage"` +
+      ` --data-urlencode "chat_id=${chatId}"` +
+      ` --data-urlencode "text=${message}"`,
+      { stdio: 'ignore', timeout: 5000 }
+    );
+  } catch {}
+}
+
+module.exports = { send };

package/package.json

@@ -1,21 +1,19 @@
 {
   "name": "claude-code-remote-pilot",
-  "version": "0.1.5",
-  "description": "Interactive Claude Code supervisor with tmux, Telegram notifications, and auto-resume after usage limits.",
+  "version": "0.2.1",
+  "description": "Interactive Claude Code supervisor — spawn and monitor multiple Claude sessions from a single terminal.",
   "type": "commonjs",
   "bin": {
     "claude-remote-pilot": "bin/claude-pilot.js"
   },
   "files": [
     "bin/",
-    "claude-pilot.sh",
+    "lib/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "start": "node bin/claude-pilot.js",
-    "pilot": "node bin/claude-pilot.js",
-    "check": "node bin/claude-pilot.js --help"
+    "start": "node bin/claude-pilot.js"
   },
   "keywords": [
     "claude-code",
@@ -23,7 +21,8 @@
     "tmux",
     "telegram",
     "agent",
-    "auto-resume"
+    "auto-resume",
+    "multi-session"
   ],
   "author": "mekku",
   "license": "MIT",

package/claude-pilot.sh

@@ -1,223 +0,0 @@
-#!/usr/bin/env bash
-set -u
-
-# Claude Code Pilot
-# Interactive Claude Code supervisor using tmux + Telegram notifications.
-#
-# Required env:
-#   TELEGRAM_BOT_TOKEN
-#   TELEGRAM_CHAT_ID
-#
-# Optional env:
-#   CLAUDE_SESSION=claude
-#   CLAUDE_COMMAND=claude
-#   CHECK_INTERVAL_SECONDS=30
-#   LIMIT_FALLBACK_WAIT_SECONDS=300
-#   POST_RESUME_COOLDOWN_SECONDS=180
-#   CAPTURE_LINES=500
-#   RESUME_COMMAND=continue
-#   START_IF_MISSING=1
-#
-# Example:
-#   TELEGRAM_BOT_TOKEN="123:abc" TELEGRAM_CHAT_ID="123456" ./claude-pilot.sh
-
-CLAUDE_SESSION="${CLAUDE_SESSION:-claude}"
-CLAUDE_COMMAND="${CLAUDE_COMMAND:-claude}"
-CLAUDE_WORKDIR="${CLAUDE_WORKDIR:-$PWD}"
-CHECK_INTERVAL_SECONDS="${CHECK_INTERVAL_SECONDS:-30}"
-LIMIT_FALLBACK_WAIT_SECONDS="${LIMIT_FALLBACK_WAIT_SECONDS:-300}"
-POST_RESUME_COOLDOWN_SECONDS="${POST_RESUME_COOLDOWN_SECONDS:-180}"
-CAPTURE_LINES="${CAPTURE_LINES:-500}"
-RESUME_COMMAND="${RESUME_COMMAND:-continue}"
-START_IF_MISSING="${START_IF_MISSING:-1}"
-
-TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN:-}"
-TELEGRAM_CHAT_ID="${TELEGRAM_CHAT_ID:-}"
-
-LIMIT_REGEX="${LIMIT_REGEX:-hit your limit|usage limit|rate limit|limit reached|try again|resets}"
-PERMISSION_REGEX="${PERMISSION_REGEX:-permission|do you want to proceed|approve}"
-
-last_limit_hash=""
-last_resume_epoch=0
-
-log() {
-  printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*"
-}
-
-require_command() {
-  if ! command -v "$1" >/dev/null 2>&1; then
-    echo "Missing required command: $1" >&2
-    exit 1
-  fi
-}
-
-send_telegram() {
-  local message="$1"
-
-  if [ -z "$TELEGRAM_BOT_TOKEN" ] || [ -z "$TELEGRAM_CHAT_ID" ]; then
-    log "Telegram not configured: $message"
-    return 0
-  fi
-
-  curl -sS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
-    --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \
-    --data-urlencode "text=${message}" >/dev/null || true
-}
-
-capture_pane() {
-  tmux capture-pane -pt "$CLAUDE_SESSION" -S "-${CAPTURE_LINES}" 2>/dev/null || true
-}
-
-hash_text() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  else
-    shasum -a 256 | awk '{print $1}'
-  fi
-}
-
-parse_wait_seconds() {
-  local text="$1"
-
-  if command -v python3 >/dev/null 2>&1; then
-    TEXT="$text" FALLBACK="$LIMIT_FALLBACK_WAIT_SECONDS" python3 - <<'PY'
-import os
-import re
-from datetime import datetime, timedelta
-
-text = os.environ.get("TEXT", "")
-fallback = int(os.environ.get("FALLBACK", "300"))
-now = datetime.now()
-lower = text.lower()
-
-# Examples:
-#   try again in 12 minutes
-#   retry after 1 hour
-m = re.search(r"(?:try again|retry|wait).*?in\s+(\d+)\s*(second|seconds|minute|minutes|hour|hours)", lower, re.I | re.S)
-if m:
-    value = int(m.group(1))
-    unit = m.group(2)
-    if unit.startswith("second"):
-        print(max(10, value))
-    elif unit.startswith("minute"):
-        print(max(10, value * 60))
-    else:
-        print(max(10, value * 3600))
-    raise SystemExit
-
-# Examples:
-#   resets 2am
-#   resets at 14:30
-#   limit resets at 3:05 pm
-m = re.search(r"resets?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?", lower, re.I)
-if m:
-    hour = int(m.group(1))
-    minute = int(m.group(2) or 0)
-    ampm = m.group(3)
-
-    if ampm:
-        if ampm == "pm" and hour != 12:
-            hour += 12
-        if ampm == "am" and hour == 12:
-            hour = 0
-
-    if 0 <= hour <= 23 and 0 <= minute <= 59:
-        reset = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
-        if reset <= now:
-            reset += timedelta(days=1)
-        # Add small safety buffer so we do not resume one second too early.
-        print(max(10, int((reset - now).total_seconds()) + 30))
-        raise SystemExit
-
-print(fallback)
-PY
-    return 0
-  fi
-
-  echo "$LIMIT_FALLBACK_WAIT_SECONDS"
-}
-
-ensure_tmux_session() {
-  if tmux has-session -t "$CLAUDE_SESSION" 2>/dev/null; then
-    return 0
-  fi
-
-  if [ "$START_IF_MISSING" != "1" ]; then
-    echo "tmux session '$CLAUDE_SESSION' not found." >&2
-    exit 1
-  fi
-
-  tmux new-session -d -s "$CLAUDE_SESSION" -c "$CLAUDE_WORKDIR" "$CLAUDE_COMMAND"
-  log "Started tmux session '$CLAUDE_SESSION' in $CLAUDE_WORKDIR"
-  send_telegram "Claude Pilot: started tmux session '$CLAUDE_SESSION'."
-}
-
-within_resume_cooldown() {
-  local now
-  now=$(date +%s)
-  [ $((now - last_resume_epoch)) -lt "$POST_RESUME_COOLDOWN_SECONDS" ]
-}
-
-handle_limit() {
-  local text="$1"
-  local fingerprint
-  fingerprint=$(printf '%s' "$text" | tail -n 40 | hash_text)
-
-  if [ "$fingerprint" = "$last_limit_hash" ]; then
-    return 0
-  fi
-
-  if within_resume_cooldown; then
-    return 0
-  fi
-
-  last_limit_hash="$fingerprint"
-
-  local wait_seconds
-  wait_seconds=$(parse_wait_seconds "$text")
-
-  log "Limit detected. Waiting ${wait_seconds}s before resume."
-  send_telegram "Claude Pilot: usage/rate limit detected. Waiting ${wait_seconds}s before sending '${RESUME_COMMAND}'."
-
-  sleep "$wait_seconds"
-
-  tmux send-keys -t "$CLAUDE_SESSION" "$RESUME_COMMAND" Enter
-  last_resume_epoch=$(date +%s)
-
-  log "Resume command sent."
-  send_telegram "Claude Pilot: resume command sent to tmux session '$CLAUDE_SESSION'."
-}
-
-main() {
-  require_command tmux
-  require_command curl
-
-  ensure_tmux_session
-
-  log "Watching tmux session '$CLAUDE_SESSION'. Attach with: tmux attach -t $CLAUDE_SESSION"
-  send_telegram "Claude Pilot: watching tmux session '$CLAUDE_SESSION'."
-
-  while true; do
-    if ! tmux has-session -t "$CLAUDE_SESSION" 2>/dev/null; then
-      log "tmux session '$CLAUDE_SESSION' ended."
-      send_telegram "Claude Pilot: tmux session '$CLAUDE_SESSION' ended."
-      exit 0
-    fi
-
-    text=$(capture_pane)
-
-    if printf '%s' "$text" | grep -Eiq "$LIMIT_REGEX"; then
-      handle_limit "$text"
-    fi
-
-    if printf '%s' "$text" | grep -Eiq "$PERMISSION_REGEX"; then
-      # Notification only. Do not auto-approve permissions.
-      send_telegram "Claude Pilot: Claude may need permission/input in session '$CLAUDE_SESSION'."
-      sleep 60
-    fi
-
-    sleep "$CHECK_INTERVAL_SECONDS"
-  done
-}
-
-main "$@"