@petersr/claude-pty-web-harness-react

A headless React hook and REST client for a claude-pty-web-harness server. No UI and no styling: useHarnessSession owns the WebSocket, tracks the live transcript and status, and exposes sendPrompt / interrupt. Render the returned events however you like.

Install

npm i @petersr/claude-pty-web-harness-react

Requires Node >= 20 to build and React >= 18 at runtime (a peer dependency). It talks to a running harness server (the reference server or the Python backend).

Usage

import { useHarnessSession, createHarnessClient } from "@petersr/claude-pty-web-harness-react";

// REST client (create/list/kill sessions). baseUrl "" = same-origin.
const client = createHarnessClient(""); // or "http://localhost:4318"
const { id } = await client.createSession("/repo", "sonnet");

function Chat({ sessionId }: { sessionId: string }) {
  const { events, status, error, lastError, connected, sendPrompt, interrupt, blobUrl } =
    useHarnessSession(sessionId, { baseUrl: "" });
  // status "failed" -> `error` holds the reason (e.g. "auth_blocked")
  // lastError holds the most recent server-rejected sendPrompt (e.g. a
  // picker-open 409), or null; it clears on the next sendPrompt that succeeds
  // render `events` (ChatEvent[]) however you like; an event's optional
  // `parts` may include an `image` part - render it as <img src={blobUrl(part.blobId)} />
}

When a sendPrompt fails - most commonly a picker-open rejection - the hook surfaces the server's message as lastError and drops the oldest matching optimistic local- echo from events, since that prompt was never actually delivered.

Types come from @petersr/claude-pty-web-harness-protocol. A non-React UI can skip this package and speak the protocol JSON over the same WebSocket.

See the project README and USAGE.md.

License

MIT