@maxiaochao/pi-toolkit

Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.

Packages

Package details

extensionskilltheme

Install @maxiaochao/pi-toolkit from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@maxiaochao/pi-toolkit

Package: @maxiaochao/pi-toolkit
Version: 0.11.20
Published: Oct 14, 2026
Downloads: 9,074/mo · 5,580/wk
Author: maxiaochao
License: unknown
Types: extension, skill, theme
Size: 10.6 MB
Dependencies: 1 dependency · 4 peers

Pi manifest JSON

{
  "skills": [
    "./skills",
    "./packages/worktree/skills"
  ],
  "themes": [
    "./themes"
  ],
  "extensions": [
    "./packages/cache-export/extensions/cache-export.ts",
    "./extensions/btw/index.ts",
    "./packages/codex-edit/extensions/codex-edit.ts",
    "./packages/herdr-subagents/extensions/herdr-subagents.ts",
    "./packages/scheduler/extensions/scheduler.ts",
    "./packages/worktree/extensions/worktree.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-toolkit

Personal Pi distribution that bundles focused extensions, agent skills, the Night Owl theme, global instructions, and the pi-worktree CLI.

Install

Install the complete toolkit:

pi install npm:@maxiaochao/pi-toolkit

That one install enables five child packages by default, because their source is embedded in the toolkit tarball: pi-cache-export, pi-codex-edit, pi-herdr-subagents, pi-scheduler, and pi-worktree.

pi-openai-account-pool is not enabled and stays a separate install:

pi install npm:@maxiaochao/pi-openai-account-pool

Update it:

pi update npm:@maxiaochao/pi-toolkit

Restart Pi after updating. pi update --extensions has the same effect when updating all installed packages. Explicitly versioned sources remain pinned and must be changed or reinstalled without the old version suffix.

Child packages

Package	Capability	Installed by `pi-toolkit`	Install	Update	Why
pi-cache-export	Tau-aligned interactive cache dashboard for Pi sessions	Yes	`pi install npm:@maxiaochao/pi-cache-export`	`pi update npm:@maxiaochao/pi-cache-export`	Because I watched the cache video on @alejandro.ao YouTube, which has a Tau style page for viewing cache
pi-codex-edit	Codex-harness `apply_patch` routing for selected GPT models	Yes	`pi install npm:@maxiaochao/pi-codex-edit`	`pi update npm:@maxiaochao/pi-codex-edit`	The core lies in the fact that the Codex model is naturally good at apply_patch, and the model is trained on this during training. However, hash-based in-context patch schemes have high token costs and complexity
pi-herdr-subagents	Visible Herdr Pi Agents coordinated by a small task state machine	Yes	`pi install npm:@maxiaochao/pi-herdr-subagents`	`pi update npm:@maxiaochao/pi-herdr-subagents`	I wanted simple serial or bounded-parallel dispatch while each task stays a real interactive Pi session in its own Herdr pane, and the main conversation only receives short summaries instead of every child's full transcript
pi-openai-account-pool	Several ChatGPT Plus/Pro logins behind `openai-codex`, switching accounts on a proven quota limit	No	`pi install npm:@maxiaochao/pi-openai-account-pool`	`pi update npm:@maxiaochao/pi-openai-account-pool`	One `/login openai-codex` credential overwrites the previous one, so hitting the subscription limit meant logging in again by hand mid-task; this keeps the accounts I authorized side by side and continues the same request on the next usable one
pi-scheduler	Session-scoped interval prompts with Agent and `/schedule` controls	Yes	`pi install npm:@maxiaochao/pi-scheduler`	`pi update npm:@maxiaochao/pi-scheduler`	I don't recommend this, it's just that it sends messages to the main session at loop intervals
pi-worktree	Worktree CLI, current-session switching Extension, and agent skill	Yes	`pi install npm:@maxiaochao/pi-worktree`	`pi update npm:@maxiaochao/pi-worktree`	In addition to the basic worktree CLI + skill, what can be achieved is to directly switch to the worktree path in the main conversation to continue the task conversation after communicating the requirements in the main conversation

Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.

Herdr Subagents personas can opt into local extension files or npm/git Pi packages through extensions. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and --no-skills does not exclude explicitly selected package skills. See the extension-source contract for precedence, isolation, and examples.

Multiple standalone children may be installed together. pi-openai-account-pool may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above is embedded, so a second install exposes the same resource twice.

Use --local with install or remove when the package declaration belongs to a project's .pi/settings.json rather than personal settings.

Root and child versions remain independent, but repository release tooling publishes a modified child and a new toolkit snapshot from the same commit. Run pi update --extensions to update all installed packages. Explicit version sources such as npm:@maxiaochao/pi-toolkit@0.9.3 remain pinned.

Toolkit-only features

`/btw`

/btw opens a separate side-chat session that can inspect the main conversation and repository without entering the main context. Closing it can optionally inject a summary. Use Up / Down for line scrolling and PageUp / PageDown for page scrolling.

Global instructions and theme

The postinstall hook:

synchronizes global/AGENTS.md to ~/.pi/agent/AGENTS.md;
selects nightowl only when no theme is configured;
installs the bundled worktree CLI and bash completion.

Existing theme choices are preserved. To sync only the global instructions from a checkout:

bash scripts/install.sh

Bundled skills

Skill	Purpose
`web-browser`	Launch and automate an isolated Chrome/Chromium session through CDP
`show-me`	Explain the current topic with the smallest useful visual
`html-artifact`	Build self-contained HTML explainers and diagrams
`pdlog`	Decompress and inspect Pudu `.pdlog` files
`herdr`	Control Herdr workspaces, tabs, panes, and agents
`agent-team`	Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents
`tapd`	Investigate and operate on TAPD items with workspace, evidence, and safe-download guardrails

Package-specific skills, such as pi-worktree, are documented by their child package.

Repository

This repository is an npm workspace. Child implementations live under packages/*; extensions/ contains only the toolkit-only BTW module. Development, testing, media generation, and release rules are documented in AGENTS.md.