@halfwhey/claudraband-core 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,153 @@
+<div align="center">
+
+# claudraband
+
+Claude Code for the power user
+
+> Experimental: this project is still evolving and parts of it may break as Claude Code and ACP clients change.
+
+[Quick start](#quick-start) •
+[CLI](docs/cli.md) •
+[Library](docs/library.md) •
+[Examples](#examples) •
+[Troubleshooting](#troubleshooting)
+
+</div>
+
+`claudraband` wraps a Claude Code TUI in a controlled terminal to enable extended workflows. This project provides:
+
+- Resumable non-interactive workflows. Essentially `claude -p` with session support: `cband continue <session-id> 'what was the result of the research?'`
+- HTTP server to remotely control a Claude Code session: `cband serve --port 1234`
+- ACP server to use with alternative frontends such as Zed or Toad (https://github.com/batrachianai/toad): `cband acp --model haiku`
+- TypeScript library so you can integrate these workflows into your own application.
+
+## Caveats
+
+- This is not a replacement for the Claude SDK. It is geared toward personal, ad-hoc usage.
+- We do not touch OAuth and we do not bypass the Claude Code TUI. You must authenticate through Claude Code, and every interaction runs through a real Claude Code session.
+
+## Requirements
+
+- Node.js or Bun
+- An already authenticated Claude Code
+- `tmux` if you want visible persistent local sessions
+
+## Install
+
+```sh
+# run without installing globally
+npx @halfwhey/claudraband "review the staged diff"
+
+# or install it once
+npm install -g @halfwhey/claudraband
+```
+
+If you prefer Bun:
+
+```sh
+bunx @halfwhey/claudraband "review the staged diff"
+```
+
+`claudraband` installs a pinned Claude Code version, `@anthropic-ai/claude-code@2.1.96`, as a dependency for compatibility. It will be bumped over time. If you need to point at a different Claude binary for debugging or compatibility work, set `CLAUDRABAND_CLAUDE_PATH`.
+
+
+## Quick start
+
+The package installs both `cband` and `claudraband`. The shorter `cband` binary is the recommended CLI. The two first-class ways to use `cband` are:
+
+- local persistent sessions with `tmux`
+- headless persistent sessions with `serve`
+
+### Visible persistent sessions with `tmux`
+
+```sh
+cband "audit the last commit and tell me what looks risky"
+
+cband sessions
+
+cband continue <session-id> "keep going"
+
+# if Claude is waiting on a choice
+cband continue <session-id> --select 2
+cband continue <session-id> --select 3 "xyz"
+```
+
+### Headless persistent sessions with `serve`
+
+```sh
+cband serve --host 127.0.0.1 --port 7842
+cband --connect localhost:7842 "start a migration plan"
+cband attach <session-id>
+cband continue <session-id> --select 2
+```
+
+The daemon now defaults to `tmux`, just like the local first-class path. Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically.
+
+`--backend xterm` still exists, but it is experimental while we improve it.
+
+### Using the CLI without tmux or server (experimental)
+
+If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. This backend is **experimental** and slower than tmux. It is useful for one-off runs, but it is not a good default for interactive follow-up because the session is not kept alive between commands.
+
+The xterm backend cannot handle Claude Code's initial startup prompts (trust folder, bypass permissions confirmation). You must disable these before using it:
+
+- `-c "--dangerously-skip-permissions"`
+- `--permission-mode bypassPermissions`
+
+Without `tmux` or server mode, `cband` shuts down Claude Code after each command finishes and starts it again on the next one. If the last output was a question for the user, that question will not survive well across the next resume. Interactive question flows work best with persistent sessions.
+
+### ACP and editor integration
+
+Use ACP when another tool wants to drive Claude through `claudraband`.
+
+```sh
+cband acp --model opus
+
+# for example with toad
+uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'
+```
+
+Some ACP clients still have limitations around resuming existing sessions. `claudraband` itself supports session follow and resume as part of the ACP protocol, but the frontend you put on top may not expose all of that yet.
+
+## Session model
+
+Live sessions are tracked in `~/.claudraband/`.
+
+- `cband sessions` shows only live tracked sessions, either hosted by tmux directly or by the daemon.
+- `continue` can resume an existing Claude Code session even when it is no longer live, but `attach` only works on live sessions.
+- `sessions close ...` closes live sessions hosted by tmux directly or by the daemon
+- `sessions close --all` will close all live sessions controlled by Claudraband
+
+## Examples
+
+### Self-interrogation
+
+I have a Claude Code hook that saves the session id that was involved in a commit so I can ask it questions about the commit later. In this workflow, Claude can use `claudraband` to interrogate that older session and justify the choices it made.
+
+![Claude interrogating an older Claude session through claudraband](assets/self-interrogate.png)
+
+### Toad via ACP
+
+Toad can use `claudraband acp` to be an alternative frontend for Claude Code.
+
+![Toad using claudraband ACP as an alternative frontend](assets/toad-acp.png)
+
+That UI is backed by a real Claude Code pane underneath.
+
+![Backing Claude Code pane for the Toad ACP session](assets/toad-claude-pane.png)
+
+### Zed via ACP
+
+Zed can also use `claudraband acp` to be an alternative frontend.
+
+![Zed using claudraband ACP as an alternative frontend](assets/zed-acp.png)
+
+## Library use
+
+Runnable TypeScript examples live in [`examples/`](examples):
+
+- [`examples/code-review.ts`](examples/code-review.ts) starts a session, asks for a review, and prints the result
+- [`examples/multi-session.ts`](examples/multi-session.ts) runs multiple Claude sessions in parallel
+- [`examples/session-journal.ts`](examples/session-journal.ts) resumes a session and writes a simple journal
+
+For the full TypeScript API, see [docs/library.md](docs/library.md).

package/dist/claude/claude.d.ts

@@ -41,6 +41,9 @@ export declare class ClaudeWrapper implements Wrapper {
     /**
      * Poll the terminal until Claude Code is ready to accept input.
      * Looks for "INSERT" in the status bar, which indicates the TUI has loaded.
+     *
+     * Also handles the "trust this folder" prompt that appears before any JSONL
+     * is written when Claude Code runs in a directory for the first time.
      */
     private waitForReady;
     stop(): Promise<void>;

package/dist/index.js

@@ -1096,6 +1096,9 @@ class ClaudeWrapper {
         if (pane.includes("INSERT") || pane.includes("NORMAL")) {
           return;
         }
+        if (pane.includes("Yes, I trust this folder") && pane.includes("No, exit") || pane.includes("Bypass Permissions mode") && pane.includes("Yes, I accept")) {
+          return;
+        }
       } catch {}
       await new Promise((r) => setTimeout(r, POLL_MS));
     }
@@ -1178,6 +1181,9 @@ function parseClaudeArgs(args) {
 }
 // src/claude/inspect.ts
 import { readFile } from "node:fs/promises";
+function normalizeCapturedPane(paneText) {
+  return paneText.replace(/\r/g, "").replace(/\x1b\[(\d+)C/g, (_match, count) => " ".repeat(Number.parseInt(count, 10) || 0)).replace(/\x1b\[[0-9;]*[ABDHJKf]/g, "").replace(/\x1b\[\?[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
 async function hasPendingQuestion(jsonlPath) {
   let data;
   try {
@@ -1211,10 +1217,20 @@ async function hasPendingQuestion(jsonlPath) {
   return pendingIds.size > 0;
 }
 function parseNativePermissionPrompt(paneText) {
-  const questionMatch = paneText.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  const normalizedPane = normalizeCapturedPane(paneText);
+  const isTrustPrompt = normalizedPane.includes("Yes, I trust this folder") && normalizedPane.includes("No, exit");
+  const isBypassPrompt = normalizedPane.includes("Bypass Permissions mode") && normalizedPane.includes("Yes, I accept");
+  let questionMatch;
+  if (isTrustPrompt) {
+    questionMatch = normalizedPane.match(/(Is this a project you created[^\n]*)/);
+  } else if (isBypassPrompt) {
+    questionMatch = normalizedPane.match(/(you accept all responsibility[^\n]*)/);
+  } else {
+    questionMatch = normalizedPane.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  }
   if (!questionMatch)
     return null;
-  const afterQuestion = paneText.slice(paneText.indexOf(questionMatch[1]) + questionMatch[1].length);
+  const afterQuestion = normalizedPane.slice(normalizedPane.indexOf(questionMatch[1]) + questionMatch[1].length);
   const optionRegex = /(?:❯\s*)?(\d+)\.\s+(.+)/g;
   const options = [];
   let match;
@@ -1389,6 +1405,10 @@ var TERMINAL_BACKENDS = [
     description: "Run Claude Code in a headless xterm-backed PTY"
   }
 ];
+function isRejectingNativeOption(label) {
+  const normalized = label.trim().toLowerCase();
+  return normalized.startsWith("no") || normalized.startsWith("reject");
+}
 function makeDefaultLogger() {
   const noop = () => {};
   return {
@@ -1510,6 +1530,8 @@ class ClaudrabandSessionImpl {
   _permissionMode;
   allowTextResponses;
   sessionOwner;
+  lastNativePermissionFingerprint = null;
+  lastNativePermissionOutcome = "none";
   constructor(wrapper, sessionId, cwd, backend, model, permissionMode, allowTextResponses, logger, onPermissionRequest, lifetime, sessionOwner) {
     this.sessionId = sessionId;
     this.cwd = cwd;
@@ -1544,7 +1566,20 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter(text);
     this.activePrompt = prompt;
     this.logger.info("prompt received", "sid", this.sessionId, "length", text.length);
-    await this.wrapper.send(text);
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState !== "consumed") {
+      await this.wrapper.send(text);
+    }
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
       this.logger.info("prompt completed", "sid", this.sessionId, "stop_reason", stopReason);
@@ -1567,6 +1602,17 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(null);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
     this.logger.info("awaitTurn", "sid", this.sessionId);
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
@@ -1590,6 +1636,26 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState === "consumed") {
+      if (this.activePrompt === prompt) {
+        this.activePrompt = null;
+      }
+      if (this.promptAbortController === controller) {
+        this.promptAbortController = null;
+      }
+      return { stopReason: "end_turn" };
+    }
     this.logger.info("sendAndAwaitTurn", "sid", this.sessionId, "length", text.length);
     await this.wrapper.send(text);
     try {
@@ -1608,6 +1674,21 @@ class ClaudrabandSessionImpl {
   send(text) {
     return this.wrapper.send(text);
   }
+  async prepareForInput(intendedText) {
+    const handled = await this.pollNativePermission(null, intendedText);
+    if (handled === "handled" || handled === "consumed" || handled === "pending_clear") {
+      const ready = await this.waitForInsertMode();
+      if (!ready) {
+        return this.wrapper.isProcessAlive() ? "blocked" : "cancelled";
+      }
+      return handled === "consumed" ? "consumed" : "ready";
+    }
+    const stillBlocking = hasPendingNativePrompt(await this.wrapper.capturePane().catch(() => ""));
+    if (stillBlocking) {
+      return "blocked";
+    }
+    return "ready";
+  }
   async interrupt() {
     this.promptAbortController?.abort();
     await this.wrapper.interrupt();
@@ -1927,7 +2008,7 @@ class ClaudrabandSessionImpl {
         }
         if (prompt.pendingTools > 0) {
           const handled = await this.pollNativePermission(prompt.lastPendingTool);
-          if (handled) {
+          if (handled === "handled" || handled === "consumed") {
             prompt.pendingTools = Math.max(0, prompt.pendingTools - 1);
             prompt.gotResponse = true;
             prompt.lastPendingTool = null;
@@ -1942,16 +2023,28 @@ class ClaudrabandSessionImpl {
       }
     }
   }
-  async pollNativePermission(pendingTool) {
+  async pollNativePermission(pendingTool, intendedText = null) {
     let paneText;
     try {
       paneText = await this.wrapper.capturePane();
     } catch {
-      return false;
+      return "none";
     }
     const prompt = parseNativePermissionPrompt(paneText);
-    if (!prompt)
-      return false;
+    if (!prompt) {
+      this.lastNativePermissionFingerprint = null;
+      this.lastNativePermissionOutcome = "none";
+      return "none";
+    }
+    const fingerprint = `${prompt.question}
+${prompt.options.map((option) => `${option.number}:${option.label}`).join(`
+`)}`;
+    if (this.lastNativePermissionFingerprint === fingerprint) {
+      if (this.lastNativePermissionOutcome === "handled" || this.lastNativePermissionOutcome === "consumed") {
+        return "pending_clear";
+      }
+      return this.lastNativePermissionOutcome;
+    }
     const decision = await this.resolvePermission({
       source: "native_prompt",
       sessionId: this.sessionId,
@@ -1971,19 +2064,62 @@ class ClaudrabandSessionImpl {
         name: opt.label
       }))
     });
+    let outcome;
     if (decision.outcome === "deferred") {
-      return false;
+      outcome = "deferred";
+    } else if (decision.outcome === "cancelled") {
+      await this.safeInterruptNativePermission();
+      outcome = "handled";
+    } else if (decision.outcome === "text") {
+      await this.safeSendNativePermission(decision.text, false);
+      outcome = decision.text === intendedText ? "consumed" : "handled";
+    } else {
+      const selected = prompt.options.find((option) => option.number === decision.optionId);
+      const tolerateExit = selected ? isRejectingNativeOption(selected.label) : false;
+      await this.safeSendNativePermission(decision.optionId, tolerateExit);
+      outcome = decision.optionId === intendedText ? "consumed" : "handled";
+    }
+    this.lastNativePermissionFingerprint = fingerprint;
+    this.lastNativePermissionOutcome = outcome;
+    return outcome;
+  }
+  async safeSendNativePermission(input, tolerateExit) {
+    try {
+      await this.wrapper.send(input);
+    } catch (error) {
+      if (tolerateExit && !this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission send ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "cancelled") {
+  }
+  async safeInterruptNativePermission() {
+    try {
       await this.wrapper.interrupt();
-      return true;
+    } catch (error) {
+      if (!this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission interrupt ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "text") {
-      await this.wrapper.send(decision.text);
-      return true;
+  }
+  async waitForInsertMode(timeoutMs = 15000) {
+    const POLL_MS = 300;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (!this.wrapper.isProcessAlive()) {
+        return false;
+      }
+      try {
+        const pane = await this.wrapper.capturePane();
+        if (pane.includes("INSERT") || pane.includes("NORMAL"))
+          return true;
+      } catch {}
+      await new Promise((r) => setTimeout(r, POLL_MS));
     }
-    await this.wrapper.send(decision.optionId);
-    return true;
+    return false;
   }
   async handleUserQuestion(ev) {
     const parsed = parseAskUserQuestion(ev.toolInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halfwhey/claudraband-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript runtime for controlling local Claude Code sessions through a real terminal.",
   "type": "module",
   "main": "./dist/index.js",