5f7a53ed21
Some checks failed
CI / build-check-test (push) Has been cancelled
- Remove unused .pi extensions and prompts - Update generated model files - Add context.md - Update pi-test.sh and package-lock.json
143 lines
6.8 KiB
Markdown
143 lines
6.8 KiB
Markdown
# 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.
|