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.
• /grilling - Relentlessly stress-test a plan, decision, or idea.
• /handoff - Compact the conversation into a handoff doc for another agent (/skill:handoff; user-invoked only).
• /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.
• /writing-great-skills - Reference for writing predictable skills (/skill:writing-great-skills; user-invoked only).
• /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.
• cosmetic - Image header, model/context/Codex footer, completion sound, animated working indicator, an editor pinned to the bottom row, and a wheel-scrollable transcript that leaves it there.
• dictate - /dictate provides macOS alt+space toggle dictation with streaming transcription.
• git - /git and ctrl+shift+g browse commit history and file diffs in the TUI.
• 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.
• 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.

Transcript scrolling needs one thing outside this repository: the WheelUpPane and WheelDownPane binds in ~/.tmux.conf send ESC[120~ and ESC[121~ to a pane flagged @pi_pane instead of entering copy-mode. Without them the wheel still opens copy-mode and shift+pageUp / shift+pageDown scroll instead.

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.