Personal pi extensions

This repository is an opinionated personal Pi toolkit developed in public: independent extensions, package experiments, project maintenance skills, launch profiles, and supporting documentation.

This is a monorepo of independent pi packages. Package versions are independent; see docs/release-policy.md for version and tag conventions.

Packages and project resources

Generated from package-owned manifests and committed project resources. See the detailed catalog; update with npm run docs:generate.

Code Intelligence

• Code Intelligence experimental — Provides one read-only code_intel tool for bounded TypeScript/JavaScript status, diagnostics, references, definition, symbols, and hover over a lazy local LSP profile.

Code Search

• AST Search experimental — Provides one bounded read-only structural pattern search tool over explicit trusted-project paths through user-installed ast-grep.

Delegation

• Agent Workers release-ready — Supervises bounded external CLI and Pi SDK workers with profiles, workspace preflight, private logs, status, wait, and cancellation.
• Agent Workflows release-ready — Validates and runs typed finite DAG workflows over the public Subagents and Agent Workers protocols.
• Subagents release-ready — Runs one to four bounded foreground read-only Pi child sessions with isolated context, compact results, progress metadata, and private artifacts.

Editing

• Parse Guard experimental — Provides one confirmed TypeScript-family exact-edit tool that vetoes newly introduced syntax failures without overriding Pi's built-in edit tool.

Integration

• Jira Board release-ready — Exposes bounded self-hosted Jira project, board, sprint, issue, and focused-context workflows to Pi users and agents.

Interoperability

• Resource Bridge release-ready — Discovers bounded metadata and provenance for Claude Code, Gemini CLI, and Codex CLI prompts, skills, and agents without importing their bodies.

Maintenance

• Safe Cleanup experimental — Guides one bounded behavior-preserving source cleanup with baseline tests, complete call-site migration, and exact final evidence.

Observability

• Agent Lens release-ready — Captures redacted Pi lifecycle traces and renders local reports, indexes, comparisons, and a metadata-only replay overlay.

Planning and Autonomy

• Goal Mode release-ready — Runs bounded main-agent objective loops with lifecycle control, explicit limits, verification evidence, and optional user-approved worker delegation policy.
• Plan Mode release-ready — Provides read-only plan creation, durable finite plan artifacts, explicit approved execution handoff, and ordered verified progress.

Project Memory

• Project Memory experimental — Provides confirmed project-scoped retention and exact governance/recovery plus explicit bounded lexical recall, without transcripts, automation, embeddings, global memory, or remote storage.

Research

• Web Search release-ready — Provides compact public web search, source fetching, chunk retrieval, and combined search-and-read research with SSRF protections.

Safety

• Safety Policy release-ready — Applies an opt-in generic main-session policy floor to commands, structured paths, writes, and declared or unknown custom tools.

Project resources

• Maintenance skills: 2
• Trusted project subagent templates: 0
• Named profiles are composition recipes, not package discovery or authority grants.

Extension profiles

Finite, tested package combinations for planning, safe autonomous work, research/observability, and worker orchestration are documented in docs/extension-profiles.md. Profiles are launch recipes, not a runtime dependency resolver, and do not weaken package-owned safety boundaries. Cross-runtime authority, child environment/tool scope, confirmation, abort, timeout, and cleanup ownership are defined in docs/execution-safety-boundaries.md. The adoption program's package ownership, rollback units, and verification evidence are summarized in docs/pi-vs-claude-code-adoption-integration.md.

npm run profiles:list
npm run profiles:check
node tools/extension-profiles.mjs command planning

Launch a tested profile or an ad hoc stack without repeating -e:

npm run pi:profile -- planning
npm run pi:profile -- worker-orchestration
npm run pi:with -- plan-mode subagents web-search safety-policy

Pass additional Pi arguments after a second --, for example:

npm run pi:profile -- planning -- --model openai-codex/gpt-5.6-sol

For a command that works from any project directory, link this private workspace once:

npm link
pi-ext run              # show recommended profiles
pi-ext run plan         # planning-first workflow with explicit execution handoff
pi-ext run auto         # bounded Plan + Goal execution
pi-ext run research     # web research, reviewers, traces, and metadata
pi-ext run workers      # confirmed external worker orchestration
pi-ext run-with plan-mode subagents web-search safety-policy

The short names map to the canonical planning, safe-autonomous, research, and worker-orchestration profile IDs; both forms remain supported. The launcher preserves the current working directory, so Pi opens against the project where pi-ext is invoked. For persistent autoload instead, install package paths once with pi install /absolute/path/to/packages/<name> and use pi config to enable or disable installed resources globally or per project.

Development

npm install
npm run catalog:list   # read-only discovered owner/resource summary
npm run docs:check     # read-only owner audit and generated-doc freshness check
npm run docs:generate  # explicit write-mode update for generated catalog views
npm run typecheck
npm run verify:release # full offline release gate; does not publish or tag
npm run smoke:agent-modes-lifecycle
npm run smoke:plan-mode-compaction # actual-host threshold-compaction smoke; requires model authentication
npm run smoke:subagents-v030 # actual-host public-tool outcome smoke; requires model authentication
npm run smoke:agent-workflows-v010 # actual-host finite workflow outcome smoke; requires model authentication
npm run smoke:resource-bridge-v010 # actual-host trusted/untrusted metadata-only resource smoke
npm run smoke:tui-contracts        # bounded non-TUI host co-load; TUI behavior is covered by package/root tests

During development, load a package directly with pi:

pi -e ./packages/pi-extension-web-search
pi -e ./packages/pi-extension-jira-board
pi -e ./packages/pi-extension-agent-workers

For persistent local use, install the package path:

pi install ./packages/pi-extension-web-search
pi install ./packages/pi-extension-jira-board
pi install ./packages/pi-extension-agent-workers

For Web Search setup, capabilities, limitations, and troubleshooting, start with packages/pi-extension-web-search/README.md.