sproutclaw/context.md

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.