references/development.md
Development
Source: https://github.com/earendil-works/pi/tree/v0.99.2 (README.md, CONTRIBUTING.md, AGENTS.md, package.json and pi-test.sh; development is no longer a current docs page)
Reviewed against Pi 0.99.2 and the package versions listed in ../SKILL.md on 2026-09-30.
Use this when working on Pi itself.
Setup
git clone https://github.com/earendil-works/pi
cd pi
npm install
npm run build
Run from source:
/path/to/pi/pi-test.sh
The script can be run from any directory and preserves the caller's cwd.
Forking and Rebranding
Configure package.json:
{
"piConfig": {
"name": "pi",
"configDir": ".pi"
}
}
Change name, configDir, and bin for a fork. This affects CLI banner, config paths, and environment variable names.
Path Resolution
Pi has npm install, standalone binary, and Node type-stripping source execution modes. Always use src/config.ts helpers such as getPackageDir and getThemeDir for package assets. Do not use __dirname directly for assets.
Debugging and Tests
/debug writes rendered TUI lines and last LLM messages to ~/.pi/agent/pi-debug.log.
npm run check
./test.sh
npm test
npm --prefix packages/coding-agent test -- test/specific.test.ts
These are upstream developer commands, not commands executed by this review. npm run check includes formatting writes, and the full test/build workflows can use native tools or network services. For a targeted test, run from the owning package.
Project Structure
packages/
ai/ # LLM provider abstraction
agent/ # Agent loop and message types
tui/ # Terminal UI components
coding-agent/ # CLI and interactive mode
codemode/ # QuickJS tool composition
mcp/ # Native MCP clients
protocol/ # Shared wire definitions
client/ # Client integration
server/ # Server integration