my-pi

Composable pi coding agent for humans and agents.

Built on the @mariozechner/pi-coding-agent SDK. Adds MCP server support, extension stacking, LSP tools, prompt presets, local SQLite telemetry for evals, and a programmatic API.

Extension stacking patterns inspired by pi-vs-claude-code.

Not a Pi package

Do not install this with pi install npm:my-pi.

my-pi is Scott's custom Pi distribution/CLI. Install the individual @spences10/pi-* packages as Pi packages instead, or run my-pi directly as its own CLI.

Features

• Pi-native CLI + SDK wrapper — interactive TUI, print mode, JSON mode, and programmatic runtime creation.
• MCP integration — stdio and HTTP/streamable-HTTP servers from mcp.json, auto-registered as Pi tools.
• Built-in LSP tools — diagnostics, hover, definitions, references, and document symbols via language servers.
• Managed skills — discover, enable, disable, import, and sync Pi-native skills.
• Prompt presets — base presets plus additive prompt layers with per-project persistence.
• Secret redaction — redact API keys and other sensitive output before the model sees tool results.
• Recall — teach the model to use pirecall for prior-session context.
• Local telemetry — optional SQLite telemetry for evals, tool analysis, and operational debugging.
• Bundled themes + extension stacking — ship defaults, then layer extra project or ad-hoc extensions on top.

Get Started

pnpx my-pi@latest
# or: npx my-pi@latest / bunx my-pi@latest

API Keys

Pi handles authentication natively via AuthStorage. Options (in priority order):

1. pi auth — interactive login, stores credentials in ~/.pi/agent/auth.json
2. Environment variables — ANTHROPIC_API_KEY, MISTRAL_API_KEY, CLOUDFLARE_API_KEY + CLOUDFLARE_ACCOUNT_ID, etc.
3. OAuth — supported for providers that offer it

Cloudflare Workers AI model IDs contain slashes. Pass the provider and model together when needed:

CLOUDFLARE_API_KEY=... CLOUDFLARE_ACCOUNT_ID=... \
  pnpx my-pi@latest -m cloudflare-workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast "summarize this repo"

Usage

Interactive mode (full TUI)

pnpx my-pi@latest

Pi's full terminal UI with editor, /commands, model switching (Ctrl+L), session tree (/tree), and message queuing.

Print mode (one-shot)

pnpx my-pi@latest "your prompt here"
pnpx my-pi@latest -P "explicit print mode"
# or: npx my-pi@latest ... / bunx my-pi@latest ...

JSON output (for agents)

pnpx my-pi@latest --json "list all TODO comments"
echo "plan a login page" | pnpx my-pi@latest --json

Outputs NDJSON events — one JSON object per line — for programmatic consumption by other agents or scripts.

In non-interactive modes ("prompt", -P, --json), my-pi keeps headless-capable built-ins like MCP, LSP, prompt presets, recall, hooks, and secret filtering enabled, while skipping UI-only built-ins like session auto-naming.

RPC and team mode

pnpx my-pi@latest --mode rpc

RPC mode speaks Pi's JSONL protocol over stdin/stdout. The built-in team mode extension adds /team for local orchestration:

/team create demo
/team spawn alice "claim one task and report back"
/team task add alice: inspect the failing test
/team dm alice status?
/team status

Team state is stored under ~/.pi/agent/teams-local by default, or MY_PI_TEAM_MODE_ROOT when set.

Local telemetry (SQLite)

Telemetry is disabled by default. When enabled, my-pi records operational telemetry for each run in a local SQLite database. This is intended for eval harnesses, latency analysis, tool failure analysis, and local debugging.

pnpx my-pi@latest --telemetry --json "solve this task"
pnpx my-pi@latest --telemetry --telemetry-db ./tmp/evals.db --json "run case"

By default the database lives at:

~/.pi/agent/telemetry.db

You can relocate the whole Pi auth/config/session directory for sandboxed or CI runs with either:

pnpx my-pi@latest --agent-dir /work/pi-agent --telemetry --json "run case"

or:

PI_CODING_AGENT_DIR=/work/pi-agent pnpx my-pi@latest --telemetry --json "run case"

Use the interactive command to inspect or persist the setting:

/telemetry status
/telemetry stats
/telemetry query run=<eval-run-id> success=true limit=10
/telemetry export ./tmp/eval-runs.json suite=smoke
/telemetry on
/telemetry off
/telemetry path

Recommended eval env vars for correlation:

• MY_PI_EVAL_RUN_ID
• MY_PI_EVAL_CASE_ID
• MY_PI_EVAL_ATTEMPT
• MY_PI_EVAL_SUITE

Recorded tables:

• runs
• turns
• tool_calls
• provider_requests

Query and export helpers:

• /telemetry query ... shows recent run summaries
• /telemetry export [path] ... writes matching runs as JSON
• supported filters: run= / eval_run_id=, case= / eval_case_id=, suite= / eval_suite=, success=true|false|null, limit=<n>
• /telemetry query defaults to limit=20
• /telemetry export auto-generates a timestamped JSON file when no path is provided

Schema notes:

• source of truth: packages/pi-telemetry/src/schema.sql
• current telemetry schema version: 1
• schema version is tracked with PRAGMA user_version
• unversioned local telemetry databases are initialized/upgraded to v1 on open
• newer unsupported schema versions fail fast instead of silently downgrading
• opens the database in WAL mode: PRAGMA journal_mode = WAL
• waits up to 5s on lock contention: PRAGMA busy_timeout = 5000

CLI flags --telemetry and --no-telemetry override only the current process. /telemetry on and /telemetry off update the saved default for future sessions.

Sandbox / CI auth and config isolation

If you run my-pi in containers, CI, or ephemeral sandboxes, changing HOME often hides the usual ~/.pi/agent/auth.json credentials. Use a stable agent directory instead of relying on HOME alone.

Recommended options:

1. Pass provider API keys directly via environment variables.
2. Set --agent-dir /path/to/pi-agent for the process.
3. Or set PI_CODING_AGENT_DIR=/path/to/pi-agent in the environment.

The agent directory holds Pi-managed state such as:

• auth.json
• settings.json
• sessions/
• telemetry.db
• telemetry.json

A practical sandbox command looks like:

PI_CODING_AGENT_DIR=/work/pi-agent \
ANTHROPIC_API_KEY=... \
pnpx my-pi@latest --untrusted --telemetry --json "run eval case"

# Cloudflare Workers AI needs both values:
CLOUDFLARE_API_KEY=... CLOUDFLARE_ACCOUNT_ID=... \
pnpx my-pi@latest -m cloudflare-workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast --json "run eval case"

Untrusted repo safe mode

Use --untrusted in unknown repositories, evals, or sandboxes. It keeps built-ins available but starts with conservative project-resource defaults:

• skips project-local MCP config (MY_PI_MCP_PROJECT_CONFIG=skip)
• skips Claude-style project hooks (MY_PI_HOOKS_CONFIG=skip)
• uses global LSP binaries instead of project-local binaries (MY_PI_LSP_PROJECT_BINARY=global)
• skips project prompt presets (MY_PI_PROMPT_PRESETS_PROJECT=skip)
• skips project-local .pi/skills and .claude/skills (MY_PI_PROJECT_SKILLS=skip)
• clears optional child-process env allowlists unless they were set explicitly

Set the listed environment variables to allow or trust where supported to re-enable one feature intentionally while staying in safe mode.

Extension stacking

pnpx my-pi@latest -e ./ext/damage-control.ts -e ./ext/tool-counter.ts
pnpx my-pi@latest --no-builtin -e ./ext/custom.ts "do something"

Stack arbitrary Pi extensions via -e. Use --no-builtin to skip all built-in extensions.

Built-in extension choices can also be saved interactively with /extensions. Startup flags like --no-recall and --no-skills still force-disable those extensions for the current process only.

Themes

my-pi bundles @spences10/pi-themes and loads that theme pack into the runtime automatically. Vanilla Pi users can install it separately with pi install npm:@spences10/pi-themes. Pick a theme in /settings, or persist one via Pi settings JSON:

{
	"theme": "tokyo-night"
}

Stdin piping

echo "review this code" | pnpx my-pi@latest
cat plan.md | pnpx my-pi@latest --json

When stdin is piped, it's read as the prompt and print mode runs automatically.

Programmatic API

import { create_my_pi, runPrintMode } from 'my-pi';

const runtime = await create_my_pi({
	agent_dir: './tmp/pi-agent',
	extensions: ['./my-ext.ts'],
	runtime_mode: 'json',
	telemetry: true,
	telemetry_db_path: './tmp/evals.db',
});
await runPrintMode(runtime, {
	mode: 'json',
	initialMessage: 'hello',
	initialImages: [],
	messages: [],
});

MCP Servers

MCP servers are configured via mcp.json files and managed as a pi extension. Stdio servers are spawned on startup, HTTP servers are connected remotely, and their tools are registered via pi.registerTool().

Global config

~/.pi/agent/mcp.json — available to all projects:

{
	"mcpServers": {
		"mcp-sqlite-tools": {
			"command": "npx",
			"args": ["-y", "mcp-sqlite-tools"]
		}
	}
}

Project config

./mcp.json in the project root — overrides global servers by name:

{
	"mcpServers": {
		"my-search": {
			"command": "npx",
			"args": ["-y", "some-mcp-server"],
			"env": {
				"API_KEY": "..."
			}
		}
	}
}

HTTP MCP servers are supported too:

{
	"mcpServers": {
		"my-http-mcp": {
			"type": "http",
			"url": "https://myproject.com/api/mcp",
			"headers": {
				"Authorization": "Bearer ..."
			}
		}
	}
}

Use "type": "http" or "type": "streamable-http" for remote MCP servers. If url is present, my-pi treats the entry as HTTP.

Global MCP config is loaded automatically. Project-local mcp.json is untrusted by default; interactive sessions prompt before loading it and headless sessions skip it unless MY_PI_MCP_PROJECT_CONFIG=allow or MY_PI_MCP_PROJECT_CONFIG=trust is set. If both configs define the same server name, the trusted project config wins.

Use /mcp in interactive mode to open the searchable MCP server modal. Enter/Space toggles servers on or off, updates the active tool set, and persists the choice as disabled/enabled in mcp.json. Use /mcp backup, /mcp restore, and /mcp profile ... to back up, restore, save, and load reusable MCP server sets.

Hooks

Claude-style hooks are discovered from .claude/settings.json, .rulesync/hooks.json, and .pi/hooks.json. Because hook commands run through bash -lc, project hook config is untrusted by default. Interactive sessions show the hook source files and commands before allowing execution; headless sessions skip hooks unless MY_PI_HOOKS_CONFIG=allow or MY_PI_HOOKS_CONFIG=trust is set. Trusted hook approvals are remembered per project directory and hook-config hash.

Hook commands receive a restricted child-process environment by default: baseline shell variables plus CLAUDE_PROJECT_DIR. Use MY_PI_HOOKS_ENV_ALLOWLIST=NAME,OTHER_NAME or the shared MY_PI_CHILD_ENV_ALLOWLIST to pass selected ambient variables through.

Commands

In interactive mode:

• /mcp list — show connected servers and tool counts
• /mcp enable <server> — enable a disabled server's tools
• /mcp disable <server> — disable a server's tools
• /extensions — open the built-in extensions manager
• /extensions list — print built-in extensions with saved/effective state
• /extensions enable|disable|toggle — without a key, open the interactive toggle list
• /extensions enable <key> / /extensions disable <key> — toggle a built-in extension
• /skills — open the interactive skills manager (unified list with managed and importable sections, checkbox batch-import)
• /skills import <key|name> — import an external skill from the command line
• /skills sync <key|name> — sync an imported skill to its upstream
• /skills refresh — rescan skill directories
• /skills defaults <all-enabled|all-disabled> — set default policy
• /prompt-preset — open the prompt preset manager (base presets + layers); /preset is a short alias
• /prompt-preset help — show examples and common prompt preset commands
• /prompt-preset <name> — activate a base preset or toggle a layer
• /prompt-preset base <name> — activate a base preset directly
• /prompt-preset enable <layer> / /prompt-preset disable <layer> — toggle a prompt layer directly
• /prompt-preset edit <name> — edit or create a project preset in .pi/presets/<name>.md
• /prompt-preset edit-global <name> — edit or create a global preset in ~/.pi/agent/presets/<name>.md
• /prompt-preset export-defaults — copy built-in presets to editable global Markdown files
• /prompt-preset export-defaults project — copy built-in presets to editable project Markdown files
• /prompt-preset delete <name> — delete a project-local preset
• /prompt-preset reset <name> — remove a project-local override and fall back to user/built-in if available
• /prompt-preset clear — clear the active base preset and all layers
• /lsp status|list|restart — inspect or restart language server state
• /redact-stats — show how many secrets were redacted this session
• /telemetry status|stats|query|export|on|off|path — inspect, query, export, or toggle local SQLite telemetry

How it works

1. Pi extension loads mcp.json configs (global + project)
2. Connects to each MCP server using stdio or HTTP transport
3. Performs the MCP initialize handshake
4. Calls tools/list to discover available tools
5. Registers each tool via pi.registerTool() as mcp__<server>__<tool>
6. /mcp enable/disable toggles tools via pi.setActiveTools()
7. Built-in extension state can be managed via /extensions and is persisted in ~/.config/my-pi/extensions.json
8. Cleanup on session_shutdown

Secret Redaction

The filter-output extension automatically redacts secrets (API keys, tokens, passwords, private keys) from tool output before the LLM sees them. Detection patterns from nopeek.

Use /redact-stats to see how many secrets were caught. Disable with --no-filter.

Prompt Presets

Prompt presets append runtime instructions to the system prompt through a built-in extension. They are split into:

• base presets — one active at a time
• prompt layers — additive checkboxes you can combine

Built-in base presets:

• terse — short, direct, no fluff
• standard — clear and concise with key context
• detailed — more explanation when nuance matters

Built-in layers:

• no-purple-prose
• bullets
• clarify-first
• include-risks

Preset sources are merged in this order:

1. built-in defaults
2. ~/.pi/agent/presets.json
3. ~/.pi/agent/presets/*.md
4. .pi/presets.json
5. .pi/presets/*.md

Project presets override global/default presets with the same name. Strings in JSON are treated as base presets by default. Object entries may set kind: "base" or kind: "layer". Markdown preset files use the filename as the preset name and optional frontmatter:

---
kind: base
description: Short, direct, no fluff
---

Be concise and direct.

Use /prompt-preset export-defaults to copy built-in presets to ~/.pi/agent/presets/*.md for editing, or /prompt-preset export-defaults project to write .pi/presets/*.md. /prompt-preset edit <name> writes a project Markdown preset; /prompt-preset edit-global <name> writes a global one. /preset is a short alias for /prompt-preset.

CLI layering is supported too:

• --preset terse,no-purple-prose,bullets
• --system-prompt "You are terse and technical."
• --append-system-prompt "Prefer one short paragraph."

Interactive sessions default to terse unless a project has a saved selection. /preset selections are restored on later sessions for the same project via ~/.pi/agent/prompt-preset-state.json; /preset clear persists no active preset for that project.

This repo also includes an example .pi/presets.json with sample base presets and layers.

LSP Integration

The built-in LSP extension adds Pi tools for:

• diagnostics
• hover
• definitions
• references
• document symbols

You still need the underlying language server binaries installed. my-pi prefers project-local binaries from node_modules/.bin and otherwise falls back to whatever is on PATH.

For the main TypeScript / JavaScript / Svelte workflow, install:

pnpm add -D typescript typescript-language-server svelte-language-server

That covers:

• TypeScript / JavaScript via typescript-language-server
• Svelte via svelteserver

my-pi can also use other language servers if you already have them installed and available on PATH, including:

• Python via python-lsp-server
• Go via gopls
• Rust via rust-analyzer
• Ruby via solargraph
• Java via jdtls
• Lua via lua-language-server

Use /lsp status to inspect active server state and /lsp restart all or /lsp restart <language> to clear cached clients.

Session Recall

The recall package nudges the model to use pnpx pirecall or npx pirecall when the user references prior work or when historical project context would help. It also triggers pirecall sync --json on session start and shutdown when the local recall database exists.

Reusable Pi packages

This repo is a pnpm workspace. The my-pi harness depends on reusable Pi packages via workspace:*, and those packages can also be published and installed into vanilla pi independently. Shared helper packages such as @spences10/pi-child-env, @spences10/pi-project-trust, and @spences10/pi-tui-modal are published only as dependencies and are not Pi packages to install via pi install.

pi install npm:@spences10/pi-redact
pi install npm:@spences10/pi-telemetry
pi install npm:@spences10/pi-mcp
pi install npm:@spences10/pi-lsp
pi install npm:@spences10/pi-confirm-destructive
pi install npm:@spences10/pi-skills
pi install npm:@spences10/pi-recall
pi install npm:@spences10/pi-nopeek
pi install npm:@spences10/pi-omnisearch
pi install npm:@spences10/pi-sqlite-tools
pi install npm:@spences10/pi-team-mode
pi install npm:@spences10/pi-themes

• @spences10/pi-redact — output redaction and /redact-stats
• @spences10/pi-telemetry — local SQLite telemetry and /telemetry
• @spences10/pi-mcp — MCP server integration and /mcp
• @spences10/pi-lsp — LSP-backed diagnostics and symbol tools
• @spences10/pi-confirm-destructive — destructive action confirmations
• @spences10/pi-skills — skill management, import, and sync
• @spences10/pi-recall — pirecall reminder and background sync
• @spences10/pi-nopeek — nopeek reminder for secret-safe environment loading
• @spences10/pi-omnisearch — mcp-omnisearch reminder for verified web research
• @spences10/pi-sqlite-tools — mcp-sqlite-tools reminder for safer SQLite database work
• @spences10/pi-team-mode — local orchestrator/team mode with RPC teammates, tasks, and mailboxes
• @spences10/pi-themes — bundled theme pack for Pi

Each package README is the entry point for install instructions, commands, runtime behavior, and development notes.

Project Structure

src/
  index.ts                 CLI entry point (citty + pi SDK)
  api.ts                   Programmatic API (create_my_pi + re-exports)
  extensions/
    manager/               Built-in extension manager and config
    prompt-presets/        Runtime prompt preset selection and editing
    session-name/          Session auto-naming
    hooks-resolution/      Claude-style hook resolution
packages/
  pi-redact/               Installable Pi package for output redaction
  pi-telemetry/            Installable Pi package for SQLite telemetry
  pi-mcp/                  Installable Pi package for MCP integration
  pi-lsp/                  Installable Pi package for LSP tools
  pi-confirm-destructive/  Installable Pi package for destructive action confirmations
  pi-skills/               Installable Pi package for skill management
  pi-recall/               Installable Pi package for pirecall reminders
  pi-nopeek/               Installable Pi package for nopeek reminders
  pi-omnisearch/           Installable Pi package for mcp-omnisearch reminders
  pi-sqlite-tools/         Installable Pi package for mcp-sqlite-tools reminders
  pi-team-mode/            Installable Pi package for team orchestration
  pi-themes/               Installable Pi theme pack
  pi-child-env/            Shared support package, not a Pi package
  pi-project-trust/        Shared support package, not a Pi package
  pi-tui-modal/            Shared support package, not a Pi package
.pi/
  presets.json             Optional project prompt presets (JSON)
  presets/*.md             Optional project prompt presets (Markdown files)
mcp.json                   Project MCP server config

Development

pnpm run dev        # Watch mode
pnpm run check      # Lint + type check
pnpm run test       # Run tests
pnpm run build      # Production build

License

MIT