Files
pipelines/docs/notes/claude-chat-backend.md

2.7 KiB

Claude Code chat backend — 2026-10-22

Claude Code is now a third chat harness beside OpenCode and Codex. The adapter (internal/claude) owns one CLI process per active session and speaks the CLI's SDK stdio protocol: stream-json input/output, partial messages, and --permission-prompt-tool=stdio with the initialize handshake. The operator's existing Claude login and configuration are used unchanged.

Session identity is a generated UUID pinned with --session-id; after an idle release or server restart the next prompt resumes with --resume. Text and reasoning stream without duplicating the completed message. Tool calls, Bash command rows, approvals (once/always/reject with the CLI's own permission suggestions), AskUserQuestion forms, interrupts, live model switching, compaction and reported session usage/context all use the existing chat surfaces. History is read from Claude Code's own JSONL transcript, merged by message id with tool results attached, sidechains and local-command noise excluded, and paged with a 64 MiB bound.

The workflow skill now installs into both OpenCode and Claude Code skill roots. pipelines skill install refreshes detected roots; an existing user-modified skill is refused rather than overwritten. Claude Code's initialize response lists the installed skill as Pipelines.

Verification

  • go test ./..., go vet ./..., formatting and diff checks passed; 742 web unit tests passed.
  • Deterministic fake-CLI tests cover streaming/dedupe, approvals allow/reject, question forms, interrupt, model selection and resume, transcript merging and paging, image/text attachments, usage, and a signed-out actionable error.
  • A real scratch-server run used the signed-in CLI and Haiku: advertised backend, model switch, streamed turn, a real Write approval that created the file, a follow-up turn on the same process, transcript readback and reported usage.
  • A real browser on a scratch server selected Claude in the create pane and saw the Claude harness mark on the created chat.
  • Deployed clean build 0acd7346bbd870597f6b6346a15b194068fc967e after checking no pipeline run, Codex chat or other OpenCode chat was active; only the Pipelines server restarted, with a database/binary/plist backup at ~/.local/share/pipelines/backups/pre-0acd7346-20261022-182320. The authenticated live check then listed claude and showed the Claude choice without creating a live chat or model turn.
  • The same restart activates the earlier transactional notification web-link fix.
  • Not tested: Flutter tooling is not installed here (the one-line capability change was not run through flutter test); native OS-specific Claude behavior outside this adapter is outside this note.