pi-mono CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Root-level commands (npm install, check, test, pack:dry-run, validate) and the git/PR workflow are in AGENTS.md — follow that.

Target a single workspace:

npm run check --workspace packages/pi-goal
npm test --workspace packages/pi-goal
npm run pack:dry-run --workspace packages/pi-web-kit

Run a single test file (from within the package directory or using tsx):

node --import tsx --test packages/pi-goal/tests/core.test.mjs

Local Pi testing without installing the package:

pi -e /path/to/pi-mono/packages/<package-name> --print "list your tools"

Architecture

This is an npm workspaces monorepo of Pi packages — extensions for @earendil-works/pi-coding-agent, a coding agent similar to Claude Code. Pi loads TypeScript source files directly at runtime via its built-in extension loader; there is no build step and no dist/ directory in any package.

Package layout

Every package follows the same structure:

packages/<name>/
  index.ts            # thin re-export: export { default } from "./extensions/index.js"
  extensions/index.ts # Pi extension wiring: registers tools, commands, event handlers
  src/                # business logic, kept separate from Pi API wiring
  src/install-telemetry.ts  # telemetry implementation (every publishable package)
  tests/              # node:test .test.mjs files (packages that have tests)

Extension API pattern

Extensions default-export a function that receives a pi: ExtensionAPI instance:

export default function myExtension(pi: ExtensionAPI) {
  pi.registerTool({ name, parameters, execute, ... });
  pi.registerCommand("cmd", { handler });
  pi.on("session_start", async () => { ... });
  pi.on("before_agent_start", async (event) => ({ systemPrompt: ... }));
}