claude-code-remote-pilot 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.3 — 2026-05-06
+
+### Fixed
+- **Auto-resume respects clock reset time**: limit recovery now waits until the parsed `resets at HH:MM` timestamp (with next-day rollover) before sending the resume command.
+- **Web UI respawn completed**: offline session respawn now has loading/error feedback and immediately updates session detail state after success.
+
+---
+
+## 0.5.2 — 2026-05-06
+
+### Fixed
+- **Auto-resume now waits for reset time**: when Claude shows an explicit `resets at HH:MM` clock time, `Watcher` now resumes at that exact reset timestamp (including next-day rollover) instead of relying only on relative wait parsing.
+- **Web UI respawn flow completed**: offline session respawn now shows in-button loading, inline errors, and immediately updates the detail view to the newly active session after successful `POST /api/sessions/:name/respawn`.
+
+---
+
 ## 0.5.1 — 2026-05-06
 
 ### Fixed

package/README.md

@@ -1,10 +1,65 @@
 # Claude Code Remote Pilot
 
-Spawn and supervise multiple Claude Code sessions from a single interactive terminal.
+Keep Claude Code running while you're away from your desk.
 
-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.
+A small self-hosted helper tool for people who run long Claude Code sessions and are tired of manually resuming after token limits.
 
-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.
+Originally built just for personal use… then it slowly grew 😅
+
+![Dashboard screenshot](docs/screenshot-dashboard.png)
+
+---
+
+## Why?
+
+I kept hitting the same problem:
+
+- Claude Code stopped after hitting token limits
+- long-running tasks needed babysitting
+- sometimes I wanted to leave home while a task was still running
+- checking progress remotely was annoying
+
+At first I only wanted auto-resume. Then it slowly turned into a small remote workflow tool.
+
+---
+
+## What this is NOT
+
+- a hosted platform
+- an "AI agent framework"
+- a replacement for Claude Code
+- a polished enterprise product
+
+It's just a practical helper tool for people running Claude Code for long periods.
+
+---
+
+## Features
+
+- Auto-detect Claude Code limit states and resume automatically
+- Persistent tmux-based sessions that outlive the pilot process
+- Web UI for monitoring and control from phone or any browser — with full ANSI color terminal rendering
+- Telegram notifications when sessions need attention
+- Browser desktop notifications on status changes
+- Broadcast a message to all active sessions at once
+- Lightweight, self-hosted — just Node.js and tmux
+- Experimental but surprisingly useful 👀
+
+---
+
+## Current Status
+
+Very experimental. Built quickly to scratch a personal itch, so expect rough edges. If you try it and hit weird issues, feel free to open an issue or PR.
+
+---
+
+## Typical Workflow
+
+1. Start the pilot and spawn Claude Code sessions
+2. Leave it running — go touch grass
+3. Pilot detects limit hits and auto-resumes
+4. Get notified via Telegram or browser notification
+5. Check progress remotely from your phone
 
 ---
 
@@ -142,6 +197,91 @@ You can also bind to a specific interface IP: `web 3742 192.168.1.10`.
 
 ---
 
+## Remote access via Cloudflare Tunnel (recommended)
+
+Binding to `0.0.0.0` exposes the dashboard on your local network but not the internet. For secure remote access from anywhere — phone, another machine, a coffee shop — use a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
+
+This is the recommended setup for remote work: the dashboard stays on `127.0.0.1` (never directly exposed), and Cloudflare handles TLS, authentication, and routing.
+
+### Quick start (no domain required)
+
+Install `cloudflared`:
+
+```bash
+# macOS
+brew install cloudflare/cloudflare/cloudflared
+
+# Linux
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
+chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/
+```
+
+Start the pilot's web dashboard, then in a second terminal run:
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:3742
+```
+
+Cloudflare prints a random `https://*.trycloudflare.com` URL. Open it on any device. The tunnel closes when you stop `cloudflared`.
+
+### Persistent tunnel with a custom domain
+
+If you have a domain on Cloudflare, you can get a stable URL and add Cloudflare Access (zero-trust auth) in front of the dashboard.
+
+**1. Authenticate and create a tunnel:**
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create claude-pilot
+```
+
+**2. Create `~/.cloudflared/config.yml`:**
+
+```yaml
+tunnel: <your-tunnel-id>
+credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json
+
+ingress:
+  - hostname: pilot.yourdomain.com
+    service: http://127.0.0.1:3742
+  - service: http_status:404
+```
+
+**3. Add a DNS record:**
+
+```bash
+cloudflared tunnel route dns claude-pilot pilot.yourdomain.com
+```
+
+**4. Start the tunnel:**
+
+```bash
+cloudflared tunnel run claude-pilot
+```
+
+The dashboard is now reachable at `https://pilot.yourdomain.com`.
+
+### Adding authentication (Cloudflare Access)
+
+Cloudflare Access puts a login wall in front of the tunnel — no inbound ports, no VPN.
+
+1. Go to **Cloudflare Zero Trust → Access → Applications → Add an application**
+2. Choose **Self-hosted**, set the domain to `pilot.yourdomain.com`
+3. Add a policy: allow your email address (or Google/GitHub OAuth)
+
+After this, anyone reaching `pilot.yourdomain.com` must authenticate with Cloudflare before the dashboard loads.
+
+### Run the tunnel as a background service
+
+```bash
+# Install as a system service (runs on boot)
+sudo cloudflared service install
+sudo systemctl start cloudflared   # Linux
+sudo launchctl start cloudflared   # macOS
+```
+
+---
+
 ## Telegram setup
 
 Create a bot via `@BotFather` and get your token.
@@ -211,12 +351,19 @@ Start Claude without `--dangerously-skip-permissions` unless you know what you'r
 - [x] broadcast message to all sessions
 - [x] auto-discover untracked tmux sessions on startup
 - [ ] auto-yes rules — confirm prompts automatically by pattern
+- [ ] smarter retry logic
+- [ ] usage statistics and session timeline
+- [ ] remote command queue
 - [ ] pluggable notification providers
 
 ---
 
-## Philosophy
+## Contributing
+
+PRs, ideas, and weird experiments are welcome 😄
+
+---
 
-A human-supervised local runtime for Claude Code. Not a fully autonomous agent loop.
+## License
 
-Small tools first. Dashboard later.
+MIT

package/lib/SessionManager.js

@@ -26,7 +26,7 @@ class SessionManager {
     });
   }
 
-  spawn(dirPath, name) {
+  spawn(dirPath, name, command = 'claude') {
     const resolved = path.resolve(dirPath.replace(/^~/, process.env.HOME || ''));
     if (!fs.existsSync(resolved)) throw new Error(`Path not found: ${resolved}`);
 
@@ -39,16 +39,22 @@ class SessionManager {
       execSync(`tmux kill-session -t "${sessionName}"`, { stdio: 'ignore' });
     } catch {}
 
-    execSync(`tmux new-session -d -s "${sessionName}" -c "${resolved}" "claude"`, { stdio: 'ignore' });
+    execSync(`tmux new-session -d -s "${sessionName}" -c "${resolved}" "${command}"`, { stdio: 'ignore' });
 
-    const session = { name: sessionName, path: resolved, status: 'running', startedAt: new Date(), resumeAt: null };
+    const session = { name: sessionName, path: resolved, command, status: 'running', startedAt: new Date(), resumeAt: null };
     const watcher = this._makeWatcher(session);
     watcher.start();
     this.sessions.set(sessionName, { session, watcher });
-    config.addToHistory(sessionName, resolved);
+    config.addToHistory(sessionName, resolved, command);
     return session;
   }
 
+  respawn(name) {
+    const h = config.getHistory().find(e => e.name === name);
+    if (!h) throw new Error(`No history for session "${name}"`);
+    return this.spawn(h.path, name, h.command || 'claude');
+  }
+
   adopt(name, dirPath) {
     try { execSync(`tmux has-session -t "${name}"`, { stdio: 'ignore' }); }
     catch { throw new Error(`tmux session "${name}" not found.`); }

package/lib/Watcher.js

@@ -80,6 +80,35 @@ class Watcher {
     return null;
   }
 
+  _parseResetAtMs(text) {
+    const atMatch = text.match(RESET_AT_RE);
+    if (atMatch) {
+      const raw = atMatch[1].trim().toLowerCase();
+      const m = raw.match(/^(\d{1,2}):(\d{2})\s*(am|pm)?$/);
+      if (m) {
+        let hour = parseInt(m[1], 10);
+        const minute = parseInt(m[2], 10);
+        const suffix = m[3];
+        if (suffix === 'pm' && hour !== 12) hour += 12;
+        if (suffix === 'am' && hour === 12) hour = 0;
+
+        const now = new Date();
+        const resetAt = new Date(now);
+        resetAt.setHours(hour, minute, 0, 0);
+        if (resetAt.getTime() <= now.getTime()) {
+          resetAt.setDate(resetAt.getDate() + 1);
+        }
+        return resetAt.getTime();
+      }
+    }
+
+    const inMatch = text.match(/(?:try again|retry|wait).*?in\s+(\d+)\s*(second|minute|hour)/i);
+    if (!inMatch) return null;
+    const v = parseInt(inMatch[1], 10);
+    const mult = inMatch[2].startsWith('second') ? 1 : inMatch[2].startsWith('minute') ? 60 : 3600;
+    return Date.now() + (v * mult * 1000);
+  }
+
   async _check() {
     if (this._busy) return;
     this._busy = true;
@@ -137,16 +166,19 @@ class Watcher {
 
     this.lastHash = hash;
     const wait = this._parseWait(text);
+    const resetAtMs = this._parseResetAtMs(text);
     const resetTime = this._parseResetTime(text);
+    const effectiveResumeAtMs = resetAtMs || (Date.now() + wait * 1000);
+    const effectiveWaitSeconds = Math.max(1, Math.ceil((effectiveResumeAtMs - Date.now()) / 1000));
 
     this.session.status = 'limit';
-    this.session.resumeAt = Date.now() + wait * 1000;
+    this.session.resumeAt = effectiveResumeAtMs;
     this.session.resetTime = resetTime;
 
     notifier.send(this.telegram.token, this.telegram.chatId,
-      `Pilot: limit in "${this.session.name}". Resets ${resetTime || `in ${Math.ceil(wait / 60)}m`}.`);
+      `Pilot: limit in "${this.session.name}". Resets ${resetTime || `in ${Math.ceil(effectiveWaitSeconds / 60)}m`}.`);
 
-    await new Promise(r => setTimeout(r, wait * 1000));
+    await new Promise(r => setTimeout(r, effectiveWaitSeconds * 1000));
 
     try { spawnSync('tmux', ['send-keys', '-t', this.session.name, this.resumeCommand, 'Enter'], { stdio: 'ignore' }); }
     catch {}

package/lib/WebServer.js

@@ -93,9 +93,9 @@ class WebServer {
     if (req.method === 'POST' && pathname === '/api/sessions') {
       return this._readBody(req, (err, body) => {
         if (err) return this._json(res, 400, { error: err.message });
-        const { name, path: dirPath, prompt: initialPrompt } = body;
+        const { name, path: dirPath, prompt: initialPrompt, command } = body;
         try {
-          const session = this.manager.spawn(dirPath, name);
+          const session = this.manager.spawn(dirPath, name, command || 'claude');
           if (initialPrompt) {
             setTimeout(() => {
               spawnSync('tmux', ['send-keys', '-t', session.name, initialPrompt, 'Enter']);
@@ -108,6 +108,18 @@ class WebServer {
       });
     }
 
+    // POST /api/sessions/:name/respawn
+    const respawnMatch = pathname.match(/^\/api\/sessions\/([^/]+)\/respawn$/);
+    if (req.method === 'POST' && respawnMatch) {
+      const name = decodeURIComponent(respawnMatch[1]);
+      try {
+        const session = this.manager.respawn(name);
+        return this._json(res, 200, { ...session, id: session.name });
+      } catch (e) {
+        return this._json(res, 400, { error: e.message });
+      }
+    }
+
     // GET /api/sessions/:name/output
     const outputMatch = pathname.match(/^\/api\/sessions\/([^/]+)\/output$/);
     if (req.method === 'GET' && outputMatch) {

package/lib/config.js

@@ -34,10 +34,10 @@ function saveResumeCommand(cmd) {
   save({ resumeCommand: cmd });
 }
 
-function addToHistory(name, path) {
+function addToHistory(name, path, command = 'claude') {
   const cfg = load();
   const history = (cfg.sessionHistory || []).filter(s => s.name !== name);
-  history.unshift({ name, path, lastSeen: new Date().toISOString() });
+  history.unshift({ name, path, command, lastSeen: new Date().toISOString() });
   save({ sessionHistory: history.slice(0, 30) }); // cap at 30
 }
 

package/lib/ui.html

@@ -574,11 +574,13 @@ function DashboardScreen({ onNavigate, sessions, activity, serverStatus }) {
 }
 
 /* --- Session Detail --- */
-function SessionDetailScreen({ session, onBack, onKilled }) {
+function SessionDetailScreen({ session, onBack, onKilled, onRespawned }) {
   const [output, setOutput] = useState('');
   const [msg, setMsg] = useState('');
   const [sending, setSending] = useState(false);
   const [killing, setKilling] = useState(false);
+  const [respawning, setRespawning] = useState(false);
+  const [respawnError, setRespawnError] = useState('');
   const [copyOk, setCopyOk] = useState(false);
   const terminalRef = useRef(null);
   const inputRef = useRef(null);
@@ -660,6 +662,25 @@ function SessionDetailScreen({ session, onBack, onKilled }) {
     }
   };
 
+  const handleRespawn = async () => {
+    if (respawning) return;
+    setRespawning(true);
+    setRespawnError('');
+    try {
+      const res = await apiFetch(`/api/sessions/${encodeURIComponent(session.name)}/respawn`, { method: 'POST' });
+      const data = await res.json();
+      if (!res.ok) {
+        setRespawnError(data.error || 'Failed to respawn');
+        return;
+      }
+      onRespawned(data);
+    } catch (e) {
+      if (e.message !== 'Unauthorized') setRespawnError('Network error');
+    } finally {
+      setRespawning(false);
+    }
+  };
+
   // Render terminal HTML (ANSI → HTML, with plain-text fallback)
   let _termHtml = '';
   if (output) {
@@ -687,6 +708,18 @@ function SessionDetailScreen({ session, onBack, onKilled }) {
           <div className="detail-meta" style={{ maxWidth: 480, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{session.path}</div>
         </div>
         <div className="detail-actions">
+          {isOffline && (
+            <>
+              <button className="btn btn-sm btn-primary" onClick={handleRespawn} disabled={respawning}>
+                {respawning ? 'Respawning…' : '↺ Respawn'}
+              </button>
+              {respawnError && (
+                <span style={{ color: 'var(--error)', fontSize: 12, alignSelf: 'center' }}>
+                  {respawnError}
+                </span>
+              )}
+            </>
+          )}
           {!isOffline && (
             <button className="btn btn-sm" onClick={copyAttachCmd} title={`tmux attach -t ${session.name}`}>
               {copyOk ? '✓ Copied' : '⊞ New Terminal'}
@@ -752,6 +785,7 @@ function SessionDetailScreen({ session, onBack, onKilled }) {
           <div className="card">
             <h3>Session Info</h3>
             <div className="info-row"><span className="info-label">Status</span><StatusPill status={session.status} /></div>
+            <div className="info-row"><span className="info-label">Agent</span><span className="info-value" style={{ fontSize: 11 }}>{session.command || 'claude'}</span></div>
             <div className="info-row"><span className="info-label">Started</span><span className="info-value" style={{ fontSize: 11 }}>{relativeTime(session.startedAt)}</span></div>
             <div className="info-row"><span className="info-label">Tokens</span><span className="info-value" style={{ fontSize: 11 }}>{formatTokens(session.tokens)}</span></div>
             {session.status === 'limit' && session.resumeAt && (
@@ -770,18 +804,23 @@ function CreateSessionScreen({ onBack, onCreated }) {
   const [name, setName] = useState('');
   const [path, setPath] = useState('');
   const [prompt, setPrompt] = useState('');
+  const [command, setCommand] = useState('claude');
+  const [customCommand, setCustomCommand] = useState('');
   const [error, setError] = useState('');
   const [loading, setLoading] = useState(false);
 
+  const resolvedCommand = command === 'custom' ? customCommand.trim() : command;
+
   const handleCreate = async () => {
     if (!name.trim() || !path.trim()) { setError('Session name and working directory are required.'); return; }
+    if (command === 'custom' && !customCommand.trim()) { setError('Enter a custom command.'); return; }
     setError('');
     setLoading(true);
     try {
       const res = await apiFetch('/api/sessions', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ name: name.trim(), path: path.trim(), prompt: prompt.trim() || undefined }),
+        body: JSON.stringify({ name: name.trim(), path: path.trim(), prompt: prompt.trim() || undefined, command: resolvedCommand }),
       });
       const data = await res.json();
       if (!res.ok) { setError(data.error || 'Failed to create session.'); return; }
@@ -807,10 +846,24 @@ function CreateSessionScreen({ onBack, onCreated }) {
         <label className="form-label">Working directory</label>
         <input className="form-input" placeholder="~/projects/app" value={path} onChange={e => setPath(e.target.value)} />
       </div>
+      <div className="form-group">
+        <label className="form-label">Agent</label>
+        <select className="form-select" value={command} onChange={e => setCommand(e.target.value)}>
+          <option value="claude">claude (Claude Code)</option>
+          <option value="opencode">opencode</option>
+          <option value="custom">custom…</option>
+        </select>
+        {command === 'custom' && (
+          <input className="form-input" style={{ marginTop: 8 }} placeholder="e.g. aider" value={customCommand} onChange={e => setCustomCommand(e.target.value)} />
+        )}
+        {command === 'opencode' && (
+          <div className="form-hint">Status indicators (running/idle) are claude-only — opencode sessions will show as idle but are fully controllable.</div>
+        )}
+      </div>
       <div className="form-group">
         <label className="form-label">Initial prompt <span style={{ fontWeight: 400, color: 'var(--muted)' }}>(optional)</span></label>
-        <textarea className="form-textarea" placeholder="What should Claude work on?" value={prompt} onChange={e => setPrompt(e.target.value)} rows={4} />
-        <div className="form-hint">Sent to Claude 2 seconds after the session starts.</div>
+        <textarea className="form-textarea" placeholder="What should the agent work on?" value={prompt} onChange={e => setPrompt(e.target.value)} rows={4} />
+        <div className="form-hint">Sent 2 seconds after the session starts.</div>
       </div>
       {error && <div style={{ marginBottom: 16, padding: '10px 14px', background: 'var(--error-soft)', color: 'var(--error)', borderRadius: 'var(--radius-sm)', fontSize: 13 }}>{error}</div>}
       <div className="form-actions">
@@ -1010,7 +1063,13 @@ function App() {
       case 'dashboard': return <DashboardScreen onNavigate={navigate} sessions={sessions} activity={activity} serverStatus={serverStatus} />;
       case 'sessions':  return <SessionsScreen sessions={sessions} onNavigate={navigate} />;
       case 'create':    return <CreateSessionScreen onBack={() => navigate('dashboard')} onCreated={s => navigate('detail', s)} />;
-      case 'detail':    return <SessionDetailScreen session={selectedSession} onBack={() => navigate('dashboard')} onKilled={() => navigate('sessions')} />;
+      case 'detail':    return <SessionDetailScreen session={selectedSession} onBack={() => navigate('dashboard')} onKilled={() => navigate('sessions')} onRespawned={(respawned) => {
+        setSessions(prev => {
+          const next = prev.filter(s => s.name !== respawned.name);
+          return [{ ...respawned, id: respawned.name }, ...next];
+        });
+        setSelectedSession({ ...respawned, id: respawned.name });
+      }} />;
       default:          return <DashboardScreen onNavigate={navigate} sessions={sessions} activity={activity} serverStatus={serverStatus} />;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-remote-pilot",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Interactive Claude Code supervisor — spawn and monitor multiple Claude sessions from a single terminal.",
   "type": "commonjs",
   "repository": {
@@ -38,4 +38,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}