@halfwhey/claudraband-core 0.2.0 → 0.4.0

package/README.md

@@ -1,149 +1,161 @@
 <div align="center">
 
-# claudraband
+# 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.
+> Experimental: this project is still evolving as Claude Code and ACP clients change.
 
-[Quick start](#quick-start) •
 [CLI](docs/cli.md) •
 [Library](docs/library.md) •
-[Examples](#examples) •
-[Troubleshooting](#troubleshooting)
+[Daemon API](docs/daemon-api.md) •
+[Examples](examples/)
 
 </div>
 
-`claudraband` wraps a Claude Code TUI in a controlled terminal to enable extended workflows. This project provides:
+`claudraband` wraps the official Claude Code TUI in a controlled terminal so you can keep sessions alive, resume them later, answer pending prompts, expose them through a daemon, or drive them through ACP.
 
-- 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.
+It provides:
 
-## Caveats
+- Resumable non-interactive workflows. Essentially claude -p with session support: cband continue <session-id> 'what was the result of the research?'
+- An http daemon for remote or headless session control
+- An ACP server for editor and alternate frontend integration
+- A TypeScript library for building these workflows into your own tools
+
+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
+
+## Setup
+
+Requirements:
 
 - Node.js or Bun
 - An already authenticated Claude Code
-- `tmux` if you want visible persistent local sessions
+- `tmux` for the first-class local and daemon-backed workflow
 
-## Install
+Install or run:
 
 ```sh
-# run without installing globally
+# one-off
 npx @halfwhey/claudraband "review the staged diff"
+bunx @halfwhey/claudraband "review the staged diff"
 
-# or install it once
+# install 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`.
+The package installs both `claudraband` and `cband`. `cband` is the recommended shorthand. The package bundles Claude Code `@anthropic-ai/claude-code@2.1.96`; set `CLAUDRABAND_CLAUDE_PATH` if you need to override the binary.
 
+## Quick Start
 
-## Quick start
+The two first-class paths are local `tmux` sessions and daemon-backed sessions.
 
-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`
+### Local persistent sessions
 
 ```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`
+### Daemon-backed sessions
 
 ```sh
-cband serve --host 127.0.0.1 --backend xterm --port 7842
+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
 ```
 
-Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically. `attach` is especially useful here because it gives you a simple REPL for a headless xterm.js session.
-
-### Using the CLI without tmux or server
-
-If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. That mode 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. It only works properly when Claude itself can proceed without an interactive permission prompt. Use one of:
+The daemon defaults to using `tmux` as the terminal runtime, just like the local path. Use `--connect` only when creating a new daemon-backed session; after that, tracked `continue`, `attach`, and `sessions` route through the recorded live owner automatically.
 
-- `-c "--dangerously-skip-permissions"`
-- `--permission-mode bypassPermissions`
+## Experimental Xterm Backend
 
-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.
+`--backend xterm` exists for local or daemon use, but it is experimental and slower than `tmux`. Use it when you need a headless fallback, not as the default path for long-lived interactive work. See [docs/cli.md](docs/cli.md) for current caveats and backend behavior.
 
-### ACP and editor integration
+## ACP
 
 Use ACP when another tool wants to drive Claude through `claudraband`.
 
 ```sh
 cband acp --model opus
 
-# for example with toad
+# example: 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.
+Editor and ACP client support varies by frontend, but `claudraband` itself supports session follow and resume through ACP.
 
-## Session model
+## Session Model
 
 Live sessions are tracked in `~/.claudraband/`.
 
-- `cband sessions` shows only live tracked sessions, either hosted by tmux or the xterm.js 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 or the xterm.js daemon
-- `sessions close --all` will close all live sessions controlled by Claudraband
+- `cband sessions` lists live tracked sessions
+- `continue` can resume an existing Claude Code session even when it is no longer live
+- `attach` only works on live sessions
+- `sessions close ...` closes live tracked sessions, either local or daemon-backed
 
 ## 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 can interrogate an older Claude 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 can use `claudraband acp` as 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.
+That UI is still 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 can also use `claudraband acp` as an alternative frontend.
 
 ![Zed using claudraband ACP as an alternative frontend](assets/zed-acp.png)
 
-## Library use
+## Library
 
-Runnable TypeScript examples live in [`examples/`](examples):
+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
+- [`examples/code-review.ts`](examples/code-review.ts)
+- [`examples/multi-session.ts`](examples/multi-session.ts)
+- [`examples/session-journal.ts`](examples/session-journal.ts)
 
-For the full TypeScript API, see [docs/library.md](docs/library.md).
+For the full API, see [docs/library.md](docs/library.md). For CLI details, see [docs/cli.md](docs/cli.md). For raw daemon endpoints, see [docs/daemon-api.md](docs/daemon-api.md).
+
+## Cheat Sheet
+
+```sh
+# install or run once
+npx @halfwhey/claudraband "review the staged diff"
+bunx @halfwhey/claudraband "review the staged diff"
+npm install -g @halfwhey/claudraband
+
+# local persistent sessions
+cband "audit the last commit"
+cband sessions 
+cband sessions close --all # close all claudraband controlled sessions
+cband continue <session-id> "keep going"
+
+# answer pending prompts
+cband continue <session-id> --select 2
+cband continue <session-id> --select 3 "xyz"
+
+# daemon mode
+cband serve --host 127.0.0.1 --port 7842
+cband --connect localhost:7842 "start a migration plan"
+cband attach <session-id>
+
+# ACP
+cband acp --model opus
+```

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,30 @@ 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";
+      }
+      if (this.lastNativePermissionOutcome !== "deferred") {
+        return this.lastNativePermissionOutcome;
+      }
+    }
     const decision = await this.resolvePermission({
       source: "native_prompt",
       sessionId: this.sessionId,
@@ -1971,19 +2066,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.2.0",
+  "version": "0.4.0",
   "description": "TypeScript runtime for controlling local Claude Code sessions through a real terminal.",
   "type": "module",
   "main": "./dist/index.js",