pi: Instructions file for Codex

Overview

Personal Pi agent home directory, symlinked to ~/.pi/agent. Contains local extensions, custom skills, prompt templates, and agent profiles. Each extension is a self-contained Node.js package in extensions/ with its own AGENTS.md for detailed context.

Directory Layout

├── agents/          # Agent profile prompt overrides (planner, reviewer, scout, worker)
├── extensions/      # Local extensions (each has own package.json + AGENTS.md)
├── skills/          # Shared skills (changelog-generator, git-project-status, etc.)
├── .pi/
│   ├── skills/      # Project-specific skills (code-review, github, blog-post, etc.)
│   └── prompts/     # Prompt templates (implement, scout-and-plan, implement-and-review)
├── themes/          # Custom TUI themes
├── db/              # Runtime SQLite databases (gitignored)
├── cache/           # Runtime cache (gitignored)
├── sessions/        # Agent session state (gitignored)
└── telemetry/       # Local telemetry data (gitignored)

Extensions

22 local extensions in extensions/. Each has its own AGENTS.md with detailed architecture, entity models, and conventions — read those before modifying an extension.

Key extensions:

• pi-webserver — shared HTTP server with auth; other extensions mount on it
• pi-kysely — shared database registry with table-level RBAC
• pi-myfinance — personal finance (accounts, transactions, vendors, budgets, reports)
• pi-personal-crm — contacts, companies, interactions
• pi-channels — bidirectional messaging (Telegram, webhooks)
• pi-memory — persistent long-term memory and daily logs
• pi-vault — Obsidian vault integration

Extension Development Conventions

Structure

• Default export: export default function (pi: ExtensionAPI) { ... }
• Import types from @earendil-works/pi-coding-agent (ExtensionAPI, getAgentDir, SettingsManager)
• TypeScript with strict: true, target ES2022, module ESNext, allowImportingTsExtensions
• Use .ts extensions in imports (e.g. import { foo } from "./bar.ts")
• Tool parameter schemas use @sinclair/typebox (Type.Object, Type.String, etc.)
• Tool results return { content: [{ type: "text", text: "..." }], details: {} }