docs(claude): rewrite for the TypeScript codebase

CLAUDE.md still described the Go-era implementation (BubbleTea, gofmt
conventions, a 7-phase migration plan that has since shipped). Replace
with the current TS reality on pi-mono, real env vars used in src/, and
pointers into the .settings/ folder for deeper context. Trim 50 lines
in the process — the deep content belongs in .settings/, not here.

Author: halfaipg

CLAUDE.md

@@ -1,232 +1,199 @@
-# CLAUDE.md — Codebase CLI
+# CLAUDE.md — codebase-cli
 
-## What This Is
+## What this is
 
-An AI coding agent CLI written in Go. Goal: build a **better Claude Code** — simpler
-architecture, any LLM provider, single binary, zero runtime dependencies.
+A TypeScript coding-agent CLI on top of the pi-mono runtime
+(`@earendil-works/pi-agent-core` + `@earendil-works/pi-ai`). We layer the
+TUI, tools, slash commands, permissions, OAuth, sessions, and the headless
+/ JSON-RPC entry points; pi-mono owns the agent loop and provider
+protocols.
 
-This is NOT a Claude Code clone. We study CC's source as a benchmark for feature coverage
-and learn from their architectural mistakes. Every feature we add should be a better
-implementation, not a copy-paste of their approach.
+Goal: a **better Claude Code** — simpler architecture, any LLM provider,
+single `npm i -g` install. Not a clone. We study CC's source as a feature-coverage
+benchmark and to learn from their architectural mistakes; we do not copy
+their code or prompt wording verbatim (open-source IP discipline).
 
-## Quick Reference
+For deep context, read [`.settings/`](.settings/) first — `tenets.md`,
+`architecture.md`, `extending.md`, `testing.md`. Those are the canonical
+docs; this file is the quick reference.
+
+## Quick reference
 
 ```
-Language:    Go 1.24
-TUI:         BubbleTea (Charm)
-Styling:     Lipgloss
-Highlighting: Chroma
+Language:    TypeScript (ESM), Node ≥ 20
+TUI:         ink (React for terminals)
+Schema:      typebox (runtime validation of tool args)
+Tests:       vitest 2.x
+Lint/format: biome 2.x
+Build:       tsc → dist/, no bundler
 Binary name: codebase
 Config dir:  ~/.codebase/
-Sessions:    ~/.codebase/sessions/
+Sessions:    ~/.codebase/sessions/<cwd-hash>/
 ```
 
-## Build & Run
+## Build & run
 
 ```sh
-go build -o codebase .
-./codebase                    # run in current dir
-./codebase -dir /some/path    # run in specific dir
-./codebase -model claude-sonnet-4-20250514  # override model
-./codebase -resume            # resume previous session
-CODEBASE_NOBOOT=1 ./codebase  # skip boot animation
+npm run build                       # tsc + chmod
+npm run check                       # typecheck + lint + tests (the pre-publish gate)
+node dist/cli.js                    # interactive TUI in current dir
+node dist/cli.js --new              # skip auto-resume of prior session
+node dist/cli.js run "<prompt>"     # one-shot headless
+node dist/cli.js run --output json "<prompt>"
+node dist/cli.js auth login         # OAuth via codebase.foundation
+node dist/cli.js app-server         # JSON-RPC over stdio (for IDE extensions)
 ```
 
-## Test
+## Test & bench
 
 ```sh
-go test ./...                 # all tests
-go test -run TestToolReadFile # specific test
-go test -v -count=1 ./...    # verbose, no cache
+npm test                            # all unit tests (576+)
+npm test -- -t "name fragment"     # filter
+npm run test:watch
+npm run bench:micro                 # vitest microbenchmarks (*.bench.ts)
+npm run bench                       # end-to-end LLM bench (needs API key)
 ```
 
-## Architecture Overview
-
-See `docs/ARCHITECTURE.md` for the full blueprint and migration plan.
-
-### Current Structure (pre-refactor)
+## Architecture in 60 seconds
 
 ```
-main.go           Entry point, config loading, flag parsing
-app.go            BubbleTea root model — routes between screens (boot/setup/chat)
-chat.go           Main chat TUI (1,603 LOC — god object, being refactored)
-agent.go          Agent loop — goroutine that drives LLM ↔ tool cycle
-tools.go          Tool definitions + execution dispatcher (switch statement)
-git_tools.go      Git-specific tools (status, diff, log, commit, branch)
-llm.go            OpenAI-compatible LLM client + SSE streaming
-llm_anthropic.go  Anthropic Messages API adapter + streaming
-permission.go     Permission system (ask/trust-tool/trust-all)
-compact.go        Conversation compaction via LLM summarization
-session.go        Session persistence to ~/.codebase/sessions/
-commands.go       Slash commands (/help, /clear, /compact, /status, etc.)
-glue.go           Sidecar LLM for intent routing, narration, titles
-plan.go           Planning mode (Q&A before building)
-render.go         Viewport rendering helpers, tool block formatters
-search.go         Web search (Tavily, Brave, SearXNG, DuckDuckGo)
-boot.go           Demoscene boot animation (plasma, 3D cube, pixel font)
-audio.go          Chiptune synthesizer (4-channel MOD tracker, pure Go)
-setup.go          First-run setup wizard
-diagnostics.go    Post-edit language checkers (Go, TypeScript, Python)
-notify.go         Notification manager (status bar messages)
-highlight.go      Syntax highlighting via Chroma
-theme.go          Color themes (dark, light, retro)
-dotenv.go         .env file loader
+User input → ChatApp (src/ui/App.tsx)
+  → /cmd     → CommandRegistry (src/commands/)
+  → !cmd     → runShellEscape (src/ui/shell-escape.ts)
+  → @path    → collectAttachments → augmented prompt
+  → router (src/agent/router.ts) → chat | plan | agent
+  → bundle.agent.prompt(text)         # pi-agent-core owns the loop
+  → AgentEvents stream over bundle.subscribe(...)
+  → useCoalescedAgentEvents flushes at 16ms (60fps cap)
+  → reducer (src/agent/events.ts) → ChatState → React render
 ```
 
-### Data Flow
-
-```
-User Input → chatModel.Update()
-  → slash command? → commands.go handler
-  → agent message? → agent.go goroutine
-    → LLM streaming via llm.go / llm_anthropic.go
-    → tool calls dispatched via tools.go
-    → permission checks via permission.go
-    → results sent back as AgentEvent on channel
-  → chatModel renders events via render.go
-```
+Full src layout, data flow, and component responsibilities live in
+[`.settings/architecture.md`](.settings/architecture.md).
 
-### Key Patterns
+## Environment variables
 
-- **Channel-based concurrency**: Agent runs in goroutine, sends events on `eventCh`,
-  TUI receives them in `Update()`. No shared mutable state.
-- **Segment-based rendering**: Conversation is `[]segment` (text/user/tool/divider/error).
-  Avoids fragile ANSI string manipulation.
-- **Debounced viewport**: Streaming rebuilds throttled to 50ms to prevent TUI thrashing.
-- **Read-only parallel execution**: Tools declaring `EffectReadsFS` run concurrently.
-- **Atomic writes**: Multi-edit uses write→rename for crash safety.
+### Provider credentials
+Provided per-provider via pi-ai's resolver. The first-run wizard
+detects what's set and offers it. Common ones:
 
-## Environment Variables
-
-### Required (one of)
 ```
-OPENAI_API_KEY          OpenAI or compatible provider API key
-ANTHROPIC_API_KEY       Anthropic API key (auto-detects protocol)
+OPENAI_API_KEY          OpenAI (also catches any OAI-compatible endpoint)
+OPENAI_BASE_URL         override endpoint for OAI-compatible providers
+ANTHROPIC_API_KEY       Anthropic
+GROQ_API_KEY            Groq
+OPENROUTER_API_KEY      OpenRouter
 ```
 
-### Optional — LLM
-```
-OPENAI_BASE_URL         Custom endpoint (Groq, Ollama, OpenRouter, etc.)
-OPENAI_MODEL            Override default model
-```
+OAuth users sign in via `codebase auth login`; tokens land in
+`~/.codebase/credentials.json` and `process.env` is not required.
 
-### Optional — Glue sidecar
+### Web search (only if `web_search` tool is invoked)
 ```
-GLUE_API_KEY            Separate key for cheap/fast model
-GLUE_BASE_URL           Separate endpoint for glue
-GLUE_FAST_MODEL         Fast model for intent/titles (default: same as main)
-GLUE_SMART_MODEL        Smart model for planning/narration
+TAVILY_API_KEY          Tavily (recommended)
+BRAVE_API_KEY           Brave Search
+SEARXNG_URL             self-hosted SearXNG instance
 ```
 
-### Optional — Web Search
+### Behavior toggles
 ```
-TAVILY_API_KEY          Tavily search (recommended)
-BRAVE_API_KEY           Brave Search
-SEARXNG_URL             Self-hosted SearXNG instance
-SEARCH_API_KEY          Alias for TAVILY_API_KEY
+CODEBASE_FRESH=1        skip auto-resume of prior session (same as --new)
+CODEBASE_NO_SUGGESTIONS=1   disable ghost-text prompt suggestions
+CODEBASE_DEBUG=1        verbose stderr logging
+CODEBASE_DEBUG_INPUT=1  log every keystroke to ~/.codebase/logs/input.log
+NO_HYPERLINK=1          disable OSC 8 clickable file paths
 ```
 
-### Optional — Behavior
+### OAuth (only override if you know why)
 ```
-CODEBASE_NOBOOT         Skip boot animation
-CODEBASE_NOSOUND        Skip boot audio
+CODEBASE_CLIENT_ID      override OAuth client id
+CODEBASE_SCOPES         override requested scopes
 ```
 
-## Coding Conventions
+`.env` and `.env.local` in the cwd are auto-loaded at startup
+(`src/dotenv/loader.ts`).
 
-### Go style
-- Standard `gofmt` formatting, no exceptions
-- Error wrapping with context: `fmt.Errorf("toolReadFile: %w", err)`
-- Unexported by default. Only export what's needed cross-package (currently single package)
-- Table-driven tests with `t.Run()` subtests
-- Channel direction on parameters: `ch chan<- AgentEvent`, `stop <-chan struct{}`
+## Coding conventions
 
-### File organization
-- One responsibility per file (aspiration — chat.go violates this, fix in progress)
-- Tests in `*_test.go` alongside source
-- Constants and types at top of file, functions below
-- Section headers with `// ──────────` dividers
+### TS style
+- ESM imports with `.js` extensions (TS NodeNext convention).
+- `import type { ... }` for type-only — biome enforces this.
+- Tabs for indentation (biome config). Single quotes off (double quotes).
+- Errors thrown as `Error` subclasses with descriptive names
+  (`ConfigError`, `PermissionDeniedError`, `UserQueryCancelled`, etc.).
+- Default to no comments. Add one only when *why* is non-obvious.
+- No multi-paragraph JSDoc blocks. One short line max.
 
-### Naming
-- Tool functions: `toolReadFile()`, `toolWriteFile()`, etc.
-- Event types: `EventTextDelta`, `EventToolStart`, etc.
-- States: `chatIdle`, `chatStreaming`, `chatPermission`, etc.
-- Messages (BubbleTea): `agentEventMsg`, `flashTickMsg`, etc.
+### Files
+- One responsibility per file. If a file passes ~400 lines, look for
+  a seam — see how `Message.tsx` and `App.tsx` were split.
+- Tests colocated as `*.test.ts` / `*.test.tsx` next to source.
+- Benchmarks colocated as `*.bench.ts` next to source.
+- Component files use PascalCase (`Message.tsx`); modules use kebab-case
+  (`tool-call-line.tsx`, `diff-summary.tsx`).
 
 ### What to avoid
-- Don't use `panic()` except for true programmer errors
-- Don't use `init()` except for command registration (commands.go)
-- Don't add dependencies without justification — stdlib first
-- Don't add features without updating `docs/ARCHITECTURE.md`
-
-## Refactoring in Progress
-
-The codebase is undergoing a major architectural refactoring. See `docs/ARCHITECTURE.md`
-sections 7-12 for the migration plan. The phases are:
-
-1. **Tool Interface** — Replace switch dispatch with `Tool` interface + `Registry`
-2. **Permission Engine** — Effect-based policies instead of tool-name checks
-3. **LLM Provider Interface** — Adapter pattern instead of protocol branching
-4. **Agent State Machine** — Explicit FSM instead of implicit state in chatModel
-5. **Token Budget Manager** — Proactive budget instead of heuristic compaction
-6. **MCP Support** — External tool servers via mcp-go
-7. **Slash Commands** — Command interface with auto-discovery
-
-When working on this codebase, check which phase is current and follow that plan.
-
-## Competitive Context: Claude Code Benchmark
-
-We have Claude Code's source code for reference. Key things to know:
-
-### What CC does well (learn from)
-- Tools as self-contained modules with schema validation
-- Streaming tool executor with concurrency control
-- Slash command system (50+ commands)
-- MCP integration for extensibility
-- Git worktree isolation for parallel agents
-- Persistent cross-session memory
-
-### What CC got wrong (do better)
-- **React/Ink for TUI**: 512K LOC for a terminal app. BubbleTea is right-sized.
-- **No clean tool interface**: BashTool is 160K bytes. Each tool is a snowflake.
-  We use a `Tool` interface — adding a tool is mechanical.
-- **Permission monster**: 300K+ lines of AST parsing, ML classifiers, hooks cascade.
-  We use effect-based policies — tools declare effects, policies match on effects.
-- **God object state**: 30+ field AppState. We use an explicit state machine (FSM).
-- **Three compaction strategies**: They don't coordinate. We use one strategy,
-  proactive, with a calibrated token budget.
-- **Retrofitted MCP**: 119K lines because tool system wasn't designed for it.
-  Our `Tool` interface treats local and MCP tools identically.
-- **Bun lock-in**: No real benefit for a CLI. We ship a single Go binary.
-
-### Design philosophy difference
-CC optimizes for Anthropic-only with maximum features. We optimize for any-LLM-provider
-with maximum simplicity. Our thesis: 80% of CC's value in 5% of the code, by making
-better foundational choices.
-
-When adding features, always ask: "How did CC do this, and what's a simpler way that
-avoids their pain points?" Check `docs/ARCHITECTURE.md` for the specific analysis.
-
-## Project Files Recognized
-
-The CLI reads these files from the project root for context:
-- `AGENTS.md` — agent instructions (OpenAI Codex convention)
-- `CLAUDE.md` — project instructions (Claude Code convention)
-- `CODEX.md` — project instructions (Codex convention)
-- `.cursorrules` — project instructions (Cursor convention)
-
-All are injected into the system prompt at session start.
-
-## Dependencies (keep minimal)
-
-Direct dependencies only:
-- `charmbracelet/bubbletea` — TUI framework
-- `charmbracelet/bubbles` — TUI components (spinner, textinput, viewport)
-- `charmbracelet/lipgloss` — styling
-- `alecthomas/chroma/v2` — syntax highlighting
-- `lucasb-eyer/go-colorful` — color space conversions (boot animation)
-
-Planned additions:
-- `mark3labs/mcp-go` — MCP client (Phase 6)
-
-Do NOT add dependencies for things the stdlib can do (HTTP, JSON, crypto, etc.).
+- Don't `as unknown as` to smuggle a field through an interface. Fix the
+  interface.
+- Don't add a feature flag for backwards-compat of code you're rewriting
+  in the same PR. Just change it.
+- Don't add a runtime dependency for something stdlib + the existing deps
+  can do.
+- Don't reach into pi-agent-core / pi-ai internals. Public API only; if
+  it's not enough, fix it upstream.
+- Don't commit aspirational documentation. The code is the spec; docs
+  follow the code.
+
+## Competitive context: Claude Code
+
+We have CC's source as a benchmark. The tenets we hold differently:
+
+| Aspect | CC | codebase-cli |
+|---|---|---|
+| TUI framework | ink + 512K LOC | ink + ~22K LOC |
+| Tool interface | Each tool a snowflake; BashTool ~160K bytes | One `Tool` interface, ~45 implementations |
+| Permissions | AST parsers + ML classifiers + hook cascade | Effect-based policies, ~600 LOC |
+| State | 30+ field god object | Single immutable `ChatState`, reducer-driven |
+| Compaction | Three uncoordinated strategies | One proactive strategy with calibrated budget |
+| Distribution | Bun lock-in, custom bundler | Plain `npm i -g`, `tsc` only |
+| Providers | Anthropic-first | Any provider via pi-ai |
+
+The Ink-LOC contrast is the headline number: ink is fine; CC's *use* of
+it is the problem. Our thesis: 80% of CC's value in 5% of the code, by
+making better foundational choices.
+
+When you add a feature, ask: "how did CC do this, and what's a simpler
+way that avoids their pain points?"
+
+## Recognized project files
+
+The CLI auto-loads these from the project root and injects them into
+the system prompt:
+
+- `AGENTS.md` (OpenAI Codex)
+- `CLAUDE.md` (Claude Code / this convention)
+- `CODEX.md`
+- `.cursorrules` (Cursor)
+
+## Direct dependencies
+
+Runtime:
+- `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai` — agent loop + protocol adapters
+- `ink` + `react` — TUI
+- `typebox` — runtime schema validation for tool args
+- `diff` — LCS-paired diffs for the `edit_file` / `multi_edit` summary
+- `glob`, `ignore` — file matching for tools
+
+Dev:
+- `vitest`, `@biomejs/biome`, `typescript`, `tsx`, `shx`, `@types/*`
+
+Don't add a dep without a real second use case in mind. The stdlib +
+the deps above can do almost everything.
+
+## In-flight features
+
+- **MCP**: there's a `/mcp` placeholder slash command but real MCP
+  client support hasn't shipped. The pi-mono roadmap calls it Phase 9.
+- **Hooks**: scaffold under `src/hooks/`; user-configurable pre/post-turn
+  and pre/post-tool hooks. Check current state before relying on them.
+- **Skills**: scaffold under `src/skills/` for per-skill SYSTEM.md additions.