claude-code-remote-pilot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mekku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+# Claude Code Remote Pilot
+
+Interactive Claude Code supervisor using `tmux`, Node.js, and notifications.
+
+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.
+
+Longer term, this project is moving toward a local multi-session Claude Code dashboard.
+
+---
+
+## Current Status
+
+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
+```
+
+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
+
+macOS:
+
+```bash
+brew install tmux
+```
+
+Ubuntu/Debian:
+
+```bash
+sudo apt install tmux curl python3
+```
+
+---
+
+## Install
+
+### From GitHub
+
+```bash
+git clone https://github.com/mekku/claude-code-remote-pilot.git
+cd claude-code-remote-pilot
+yarn install
+```
+
+Run locally:
+
+```bash
+yarn pilot
+```
+
+or:
+
+```bash
+node bin/claude-pilot.js
+```
+
+### As npm package
+
+```bash
+npm install -g claude-code-remote-pilot
+claude-remote-pilot
+```
+
+or:
+
+```bash
+npx claude-code-remote-pilot
+```
+
+---
+
+## Telegram Setup
+
+Create a bot with `@BotFather` and get your bot token.
+
+Send a message to your bot, then get your chat ID:
+
+```bash
+curl "https://api.telegram.org/bot<BOT_TOKEN>/getUpdates"
+```
+
+Look for:
+
+```json
+"chat": {
+  "id": 123456789
+}
+```
+
+Run:
+
+```bash
+export TELEGRAM_BOT_TOKEN="xxx"
+export TELEGRAM_CHAT_ID="123456789"
+
+yarn pilot
+```
+
+Telegram is optional. If not configured, messages are printed locally.
+
+---
+
+## Basic Usage
+
+Start pilot:
+
+```bash
+yarn pilot
+```
+
+Attach to Claude:
+
+```bash
+tmux attach -t claude
+```
+
+Detach without killing Claude:
+
+```text
+Ctrl+B then D
+```
+
+The watcher keeps running and watches the tmux session.
+
+---
+
+## 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
+```
+
+---
+
+## Recommended Claude Workflow
+
+For long-running work, ask Claude to maintain 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.
+```
+
+This matters because LLM context can drift over long sessions. External state is the real resume brain.
+
+---
+
+## Safety Notes
+
+Avoid starting with:
+
+```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
+
+---
+
+## 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.
+
+---
+
+## 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
+
+Small tools first. Spaceship later.

package/bin/claude-pilot.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const { 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);
+}
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+Claude Code Remote Pilot
+
+Usage:
+  claude-remote-pilot
+
+Environment variables:
+  TELEGRAM_BOT_TOKEN
+  TELEGRAM_CHAT_ID
+  CLAUDE_SESSION
+  CLAUDE_COMMAND
+
+Example:
+  TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=123456 claude-remote-pilot
+
+Attach to tmux:
+  tmux attach -t claude
+`);
+  process.exit(0);
+}
+
+const child = spawn('bash', [scriptPath], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/claude-pilot.sh

@@ -0,0 +1,222 @@
+#!/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}"
+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" "$CLAUDE_COMMAND"
+  log "Started tmux session '$CLAUDE_SESSION' with command: $CLAUDE_COMMAND"
+  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 "$@"

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "claude-code-remote-pilot",
+  "version": "0.1.0",
+  "description": "Interactive Claude Code supervisor with tmux, Telegram notifications, and auto-resume after usage limits.",
+  "type": "commonjs",
+  "bin": {
+    "claude-remote-pilot": "bin/claude-pilot.js"
+  },
+  "files": [
+    "bin/",
+    "claude-pilot.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/claude-pilot.js",
+    "pilot": "node bin/claude-pilot.js",
+    "check": "node bin/claude-pilot.js --help"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "tmux",
+    "telegram",
+    "agent",
+    "auto-resume"
+  ],
+  "author": "mekku",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}