# Code Context

## Top-Level Structure

```
.sproutclaw/
├── .claude/              # Claude configuration
├── .github/              # Issue templates, workflows (issue-gate, pr-gate, approve-contributor)
├── .husky/               # Git hooks
├── .pi/                  # pi/pi-mono agent configuration (AGENTS.md)
├── node_modules/
├── packages/             # 5 monorepo workspaces
│   ├── ai/               # @earendil-works/pi-ai       v0.74.0
│   ├── agent/            # @earendil-works/pi-agent-core v0.74.0
│   ├── coding-agent/     # @earendil-works/pi-coding-agent v0.74.0
│   ├── tui/              # @earendil-works/pi-tui      v0.74.0
│   └── web-ui/           # @earendil-works/pi-web-ui   v0.74.0
├── scripts/              # CI/release/utility scripts
├── tmp/                  # Temp files
├── pi-test.sh            # Interactive TUI test script
├── README.md
├── CONTRIBUTING.md
├── AGENTS.md
├── biome.json            # Linting/formatting config
├── tsconfig.base.json    # Shared TS config
├── tsconfig.json         # Root TS config
├── package.json          # Workspace root (npm workspaces)
└── bun.lock / package-lock.json
```

## Packages

### 1. `packages/ai` — `@earendil-works/pi-ai`
**Unified LLM API** — automatic model discovery, provider configuration, streaming.

- `src/index.ts` — package entry
- `src/types.ts` — core types (`Api`, `StreamOptions`, `Model`, `KnownProvider`)
- `src/stream.ts` — main streaming implementation
- `src/models.ts` / `src/models.generated.ts` — model registry + auto-generated
- `src/providers/` — individual provider implementations (Anthropic, Google, OpenAI, Mistral, etc.)
- `src/cli.ts` — CLI for model listing etc.
- `src/env-api-keys.ts` — credential detection from env vars
- `src/oauth.ts` — OAuth support
- `src/api-registry.ts` — API/stream provider registration
- `scripts/generate-models.ts` — model list generation script
- Subpath exports per provider (e.g. `./anthropic`, `./google`, etc.)

### 2. `packages/agent` — `@earendil-works/pi-agent-core`
**General-purpose agent** — transport abstraction, state management, attachment support.

- `src/index.ts` — package entry
- `src/types.ts` — core types (agent state, attachments, transports)
- `src/agent.ts` — agent implementation
- `src/agent-loop.ts` — agent main loop
- `src/proxy.ts` — proxy support
- `src/harness/` — test harness utilities

### 3. `packages/coding-agent` — `@earendil-works/pi-coding-agent`
**Coding agent CLI** — the `pi` CLI binary with read, bash, edit, write tools and session management.

- `src/cli.ts` / `src/cli/` — CLI argument parsing / entry point
- `src/main.ts` — main agent runner
- `src/index.ts` — package entry
- `src/config.ts` — configuration management
- `src/core/` — core logic (model resolution, hooks, tool execution, session management)
- `src/modes/` — operational modes
- `src/bun/` — Bun-specific support
- `src/migrations.ts` — data migration utilities
- `src/package-manager-cli.ts` — package manager interaction
- `docs/` — provider setup docs
- `examples/` — extension examples (custom provider, sandbox)
- Binary name: `pi`

### 4. `packages/tui` — `@earendil-works/pi-tui`
**Terminal UI library** — differential rendering for text-based terminal applications.

- `src/index.ts` — package entry
- `src/tui.ts` — core TUI rendering engine
- `src/terminal.ts` — low-level terminal I/O
- `src/keys.ts` / `src/keybindings.ts` — key input handling
- `src/components/` — reusable UI components
- `src/editor-component.ts` — text editor component
- `src/autocomplete.ts` — autocomplete support
- `src/fuzzy.ts` — fuzzy matching
- `src/terminal-image.ts` — image rendering in terminal
- `src/kill-ring.ts` / `src/undo-stack.ts` — editing helpers
- `src/stdin-buffer.ts` / `src/utils.ts` — utilities

### 5. `packages/web-ui` — `@earendil-works/pi-web-ui`
**Reusable web UI components** — AI chat interfaces powered by pi-ai.

- `src/index.ts` — package entry
- `src/app.css` — Tailwind CSS stylesheet
- `src/ChatPanel.ts` — main chat panel component
- `src/components/` — reusable React components
- `src/dialogs/` — dialog components
- `src/prompts/` — prompt templates/management
- `src/storage/` — client-side storage abstraction
- `src/tools/` — tool integration
- `src/utils/` — utilities
- Build: TypeScript + Tailwind CSS

## Root Scripts (`scripts/`)

- `release.mjs` — automated release workflow (version + changelog + publish)
- `sync-versions.js` — lockstep version sync across all packages
- `cost.ts` / `stats.ts` — analytics/telemetry stats
- `tool-stats.ts` / `edit-tool-stats.mjs` / `read-tool-stats.mjs` — tool usage statistics
- `profile-coding-agent-node.mjs` — Node.js profiling for coding agent
- `build-binaries.sh` — binary build script
- `browser-smoke-entry.ts` / `check-browser-smoke.mjs` — browser smoke tests
- `session-transcripts.ts` / `session-context-stats.mjs` — session logging

## Architecture Summary

```
pi-tui (terminal UI)  ─── pi-coding-agent (CLI + tools) ─── pi-agent-core (agent loop)
                                                                        │
                                         pi-web-ui (web UI) ────────────┤
                                                                        │
                                                        pi-ai (LLM provider abstraction)
```

- **pi-ai** is the foundation layer providing unified LLM API access (Anthropic, Google, OpenAI, Azure, Mistral, Bedrock, etc.)
- **pi-agent-core** builds on pi-ai with agent loop, transport abstraction, and state management
- **pi-coding-agent** is the main product: a coding agent CLI (`pi` command) with read/bash/edit/write tools and session management
- **pi-tui** is a standalone TUI rendering library used by pi-coding-agent
- **pi-web-ui** provides reusable chat UI components (React) powered by pi-ai

## Key Facts

- **Lockstep versioning**: all packages share the same version (currently 0.74.0)
- **Release automation**: `npm run release:patch` / `release:minor` via `scripts/release.mjs`
- **TypeScript with tsgo**: uses `tsgo` (TypeScript native preview) for fast builds; web-ui uses `tsc`
- **Linting**: Biome (v2.3.5) for formatting and linting (`npm run check`)
- **Testing**: vitest for ai/agent/coding-agent; node --test for tui
- **No `any` types allowed**, standard top-level imports only (no inline `import()`)
- **GitHub CI**: issue-gate, pr-gate, approve-contributor workflows for contributor management

## Start Here

Open `package.json` (root) for workspace structure and available scripts. For a specific package, start with its `package.json` then `src/index.ts` for the public API surface.