Pi Kit

Meng's personal Pi Coding Agent setup: reusable skills, extensions, a theme, and supporting utilities used across projects.

This repository lives directly at ~/.pi/agent, so Pi discovers its extensions, skills, theme, settings, and global instructions without a package manifest. Most items are tuned for macOS, Ghostty, Bun, uv, and an OpenAI Codex subscription.

Configuration

settings.json configures the default workflow:

• OpenAI Codex with gpt-5.6-sol and high thinking
• gpt-5.6-luna, gpt-5.6-terra, and xai/grok-4.5 as enabled alternatives
• nightowl as the active theme
• automatic context compaction disabled

AGENTS.md supplies the global instruction to report with extreme concision. Credentials, sessions, trust decisions, model metadata, and extension state stay local through .gitignore.

Skills

Skills live in skills. Each skill has a SKILL.md plus any helper scripts or reference notes it needs.

• /agent-browser - Automate browsers, web-app testing, Electron apps, and remote browser environments.
• /google-workspace - Read and edit Google Docs, Sheets, Drive, and Gmail through gws.
• /imagegen - Generate or edit raster images, including reference-guided and transparent outputs.
• /librarian - Cache and refresh GitHub repositories for local source reference.
• /transcribe - Transcribe audio or video locally. Nothing is uploaded.
• /uv - Prefer uv for Python environments, scripts, dependencies, and builds.
• /web-search - Search the live web for current or verifiable facts.
• /youtube - Summarize and answer questions about YouTube videos from their captions.

Extensions

Pi extensions live in extensions:

• answer - /answer and ctrl+. turn questions from the last assistant response into an interactive Q&A flow.
• btw - /btw opens a persistent side-chat popover for tangential questions.
• context - /context shows what fills the context window; /context compact starts with the summary grid.
• continue - shift+option+enter sends continue when the agent is stopped.
• cosmetic - Image header, model/context/Codex footer, completion sound, and animated working indicator.
• dictate - /dictate provides macOS push-to-talk input with streaming transcription.
• dupe - /dupe duplicates the current session into a right-hand Ghostty split, optionally sending a prompt.
• edit - Replaces edit with a constrained Codex-style apply_patch tool with live preflight previews.
• emoji - :shortcode: autocomplete plus an /emoji picker.
• fast - /fast toggles the OpenAI Codex priority service tier and persists the preference.
• files - /files browser with Git/session context and shortcuts for opening, revealing, or Quick Looking referenced files.
• goal - /goal long-running objective mode with budgets, automatic continuation, and goal-management tools.
• recall - Project-scoped prompt history integrated into the editor's up/down navigation.
• reset - /reset redeems an available OpenAI Codex usage-limit reset.
• review - /review and /end-review handle uncommitted, branch, commit, PR, and folder reviews, with optional loop fixing.
• skills - Short skill commands such as /imagegen, with autocomplete, highlighting, and inline skill expansion.
• subagent - subagent tool delegating one task at a time to a child Pi in tmux, attachable with pi --attach-subagent <id>.
• talk - /talk runs a macOS realtime voice conversation that drives the coding agent.
• todos - /todos TUI plus the todo tool for claimable, file-backed project tasks.
• usage - /usage shows Codex limits, credits, token activity, and daily/weekly/cumulative charts.
• uv - Replaces bash with a uv-aware tool that blocks common pip, Poetry, and venv workflows.

Shared implementation lives in extensions/lib. Pi skips it because it has no index.ts; extensions use it for Codex auth, Git operations, state, audio, realtime sockets, formatting, loaders, pickers, and common utilities.

Theme

Custom themes live in themes:

• nightowl.json - Night Owl dark theme used by this setup.

Environment Overrides

All overrides are optional:

• PI_CODING_AGENT_DIR - Pi agent directory used for assets and extension state.
• PI_CODEX_CHATGPT_BASE_URL, PI_CODEX_FAST_MODE, PEEK_CODEX_BIN - Codex backend, initial fast-mode preference, and footer helper binary.
• PI_TALK_LANGUAGE, PI_TALK_VAD_THRESHOLD, PI_TALK_DEBUG - Realtime conversation language, VAD, and debug logging. Model (gpt-realtime-2.1), voice (marin), and transcription model (gpt-realtime-whisper) are fixed in code.
• PI_DICTATE_LANGUAGE, PI_DICTATE_DELAY, PI_DICTATE_AUDIO_DEVICE, PI_DICTATE_FFMPEG - Dictation language, latency, input device, and ffmpeg path. Endpoint and model (gpt-realtime-whisper) are fixed in code.
• PI_TODO_PATH - Override the default project-local .pi/todos directory.
• EDITOR, VISUAL - Editor used by the file browser.
• PI_HOST_ROOT - Pi installation used by scripts/link-host.ts for host type links.
• PI_CODING_AGENT_MODULE, PI_HOME - Pi runtime module lookup and generated-image output root used by helper scripts.

Support Files and Utilities

• assets - Emoji data, command shims, header artwork, notification audio, realtime audio helper, and working messages.
• scripts/analyze-edits.py - uv run utility for edit-tool usage and failure statistics from session logs.
• scripts/shimmer-preview.ts - Standalone preview harness for the animated working row.
• scripts/link-host.ts - Links the globally installed Pi runtime and bundled types into node_modules for typechecking.
• tests/extensions.smoke.test.ts - Cross-extension registration and architecture checks; unit tests live beside their implementations.
• state - Gitignored extension state for dictation mode, fast mode, prompt recall, and similar preferences.

Development

Install dependencies, link the active Pi host, then run typechecking and tests:

bun install
bun run link-host
bun run check

Pi loads each extensions/*/index.ts directly. The smoke suite verifies every extension registers, shared imports go through extensions/lib, headless notifications remain guarded, and host types are not bypassed.