clawp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

clawp is a subscription-billed drop-in for claude -p: clawp [flags] [prompt] (or echo prompt | clawp) takes a prompt from a positional arg or stdin, prints the answer to stdout, and sends status + the session-id to stderr with proper exit codes. Single file (clawp.py), Python standard library only.

Why it exists: scripted use of the interactive TUI bills against the Claude subscription, while claude -p draws from the Agent SDK credit pool. clawp must therefore never call claude -p. It runs the interactive TUI in an ephemeral tmux pane and reads the answer back from the transcript jsonl claude writes to disk.

Architecture

clawp "prompt"
  │  client = get_client(--client)  # claude (default) or kimi
  │  session-id = uuid (or --resume <id>; discovered for kimi fresh sessions)
  ├─ session_lock (flock /tmp/clawp-<name>.lock, one turn/pane)
  ├─ ensure_session ── tmux new-session "<client> <backend-specific launch args>"
  │                    clears trust prompt (Enter) + bypass warning (--full-auto) for claude;
  │                    for kimi, discovers the generated session-id from the welcome screen/index
  │                    waits for idle
  ├─ offset = len(read_records(transcript))   # before send; swallows prior turn's tail
  ├─ send_text ── prompt VERBATIM via bracketed paste
  ├─ capture loop (POLL=0.6s) — DUAL SIGNAL completion:
  │     transcript: terminal record per client adapter ─> capture answer text
  │     screen backstop: idle prompt + no spinner + stable    ─> done (unknown future stop_reason)
  │     blocked (permission/trust dialog)  ─> exit 3
  │     stall / MAX_TURN                    ─> exit 4
  └─ _log_turn → INSERT into responses (sqlite) ── kill pane (every exit path)

Transcript path is deterministic from the session-id: ~/.claude/projects/*/<session-id>.jsonl. Spinner = an ellipsis (…) on a non-box line in the bottom region (the launch "What's new" box also uses …, so boxed │ lines don't count); idle = any IDLE_MARKERS substring in the status bar (Model: / shift+tab / /effort — the bar text varies by version/plan) and no dialog markers. Schema-break fallback: settled but zero parsed answer → text mode falls back to lossy scrape_reply (flagged low_fidelity); json/stream-json loud-fail.