# claude-thinking

TUI that displays Claude Code's API streams token-by-token (thinking, text, tool
calls) by acting as a pass-through proxy: Claude Code points `ANTHROPIC_BASE_URL`
at `127.0.0.1:8484`, we forward everything verbatim to `api.anthropic.com` and
tee SSE responses into the UI. **Never issue API requests of our own** — zero
extra usage is the core constraint of this project.

## Architecture

```
src/main.rs    entry; tokio runtime for proxy task, TUI on main thread; --headless mode
src/proxy.rs   axum fallback handler: buffers request body (for session metadata),
               forwards via reqwest, streams response back unbuffered, tees SSE
src/sse.rs     incremental SSE parser; tolerant of chunk splits mid-event/mid-UTF-8
src/app.rs     Arc<Mutex<App>> shared state; Tap = one in-flight tapped request,
               translates SSE events → session Entries (Drop closes it out)
src/ui.rs      ratatui rendering @ ~30fps; session list + scrollable feed
```

Data flow: proxy task parses SSE chunks → `Tap::handle()` mutates shared state →
UI thread redraws on its own tick (no channel; just the mutex).

## Key invariants

- **Latency-neutral pass-through**: response bytes are forwarded as-is, never
  buffered or rewritten. Auth headers pass through untouched. If the tap code
  panics or misparses, the proxy must still relay bytes (tee is best-effort).
- **`accept-encoding` is stripped** from forwarded requests so the upstream
  sends identity encoding we can parse in transit. Don't "fix" that.
- Hop-by-hop headers (`content-length`, `transfer-encoding`, etc.) are stripped
  both directions; hyper re-frames.
- Sessions are keyed by the UUID after `session_` in request `metadata.user_id`.
  Concurrent requests (subagents) share a session but each `Tap` tracks its own
  current entry index — entries/sessions are append-only, so indices stay stable.
- Tool input streams as raw JSON fragments; pretty-printed only on
  `content_block_stop`. Text re-renders markdown every frame, so partial
  markdown self-heals.

## Gotchas

- `tui-markdown` is pinned `=0.3.5`: later versions use `ratatui-core` (0.30
  alpha types), incompatible with ratatui 0.29.
- ratatui needs feature `unstable-rendered-line-info` for `Paragraph::line_count`
  (used for follow/auto-scroll).
- reqwest is `default-features = false` + `rustls-tls,stream` — don't enable
  compression features (would re-add accept-encoding).
- Bind failures (port in use) only surface in the TUI status bar; check for a
  stale `claude-thinking` process holding 8484.
- Testing: SSE parser has unit tests (`cargo test`). For a live pass-through
  check: `--headless`, then POST to `127.0.0.1:8484/v1/messages` without auth —
  a relayed 401 from Anthropic proves the round-trip. The TUI can't run in a
  non-tty.

## Not yet handled (known MVP limits)

- Non-streaming requests pass through untapped (e.g. `count_tokens`).
- Sessions are never pruned; long sessions re-render fully each frame.
- Tool results only appear once the *next* request fires; if the session ends
  right after a tool call, that result is never seen. Output is what Claude
  Code sends the model (i.e. post-truncation).