Opinionated Pi Extensions

@jtsang/pi-extensions is my opinionated collection of extensions and agent skills for Pi. It reflects how I want coding agents to work: focused defaults, small additions, and no attempt to be a neutral framework for every workflow.

The resources share one npm package and release lifecycle. Pi users can use pi config to enable only the resources they want.

Extensions

Extension	Purpose	Interface	Behavior and limits
Subagent	Delegate independent tasks to continuable Pi child sessions.	pi_subagent: spawn, wait (all/any), send, stop, list, result, forget.	Separate contexts, scoped built-ins, pinned model/thinking, live progress and usage, four active turns, deadlines and turn budgets. Runs and artifacts live under ~/.pi/subagents/; compact parent snapshots reference immutable histories loaded only on continuation. Full reports support pagination; completed records can be removed without deleting archives. --no-session keeps state in memory. Shared filesystem; no nested delegation or other extension hooks. Supports TUI, JSON and RPC.
BTW	Persistent parallel side conversations that stay outside the main model context.	/btw <question> creates a thread; /btw opens the picker; /btw:cancel cancels the active turn. Picker: r resumes and c cancels. Overlay: ↑/↓ scroll, PageUp/PageDown scroll by page, Esc hides, /cancel cancels, /resume or Ctrl+R resumes, and Ctrl+O expands tool output.	Threads are branch-sensitive snapshots with pinned model/thinking settings, built-in tools, follow-ups, compaction, and full restoration. One turn runs at a time; others wait in FIFO order and become paused across reloads. btw_handoff transfers explicitly requested content to the main session; this is prompt-enforced without a second confirmation. TUI only; no deletion controls or other extension tools/hooks. Built-in tools therefore bypass extension-provided guards, and edit avoidance is prompt guidance rather than a security boundary.
Monitor	Event-driven background command monitoring without keeping the model running.	pi_background_monitor starts a command, pi_background_monitor_list inspects active monitors, pi_background_monitor_stop stops one or all, and /monitors opens TUI details.	Non-persistent monitors time out after five minutes; persistent monitors run until stopped or shutdown. Output is batched for 200 ms, stripped of terminal controls, capped at 16 KB per event, and delivered immediately when idle or as steering after the active tool batch. There is no extension-level concurrency limit. Commands have the Pi process's system access, so keep sources selective.

Archived extensions

Extensions retired from the published package live under archives/; they stay in the repository for reference and are not loaded by Pi or shipped on npm. better-compaction was the first to move there.

Skills

Skill	Purpose	Dependencies and compatibility
Lark Monitor	Keeps concurrent agent sessions reachable through a shared Lark topic group: each session owns a thread and relays only results, blockers, questions, decisions, and verified replies.	Delegates to lark-shared, lark-im, lark-event, lark-cli, and node. State lives in ~/.lark-monitor/ (target group config + session-thread map); legacy P2P mode is kept in references/p2p-mode.md for explicit opt-in. Works with any host that can stream a long-lived process; for Claude Code, copy or link it into .claude/skills/lark-monitor.

Installation

Install the npm package:

pi install npm:@jtsang/pi-extensions

Or install directly from GitHub:

pi install git:github.com/jtsang4/pi-extensions

Pi packages run with full system access. Review extension source before installing or enabling it.

Development

Requirements:

• Node.js 22.19 or newer
• pnpm (the version is pinned in package.json)
• Pi

corepack enable
pnpm install
pi -e .
pnpm check

Pi loads TypeScript directly through jiti, so this package intentionally has no build artifact. pnpm verify runs tests, TypeScript checking, and the publish package inspection; prepublishOnly runs it automatically before publishing.

The Verify workflow runs these checks and the deterministic subagent E2E suite on pushes to main and pull requests targeting main. Feature-branch pushes do not also create duplicate runs. Changes confined to repository documentation, the license, or local agent/skill configuration skip verification; mixed code/documentation changes and published skills/ content still run it. Manual verification remains available through gh workflow run verify.yml. Real-model tests run separately and do not incur model API usage in CI.

Small extensions belong in extensions/<name>.ts. Multi-file extensions use extensions/<name>/index.ts. Keep shared code in lib/ only after real reuse appears.

Publishing

Use the repository's release skill to handle the whole release: commit pending changes, fetch and merge current code, read npm versions, update the version, push the release tag, and verify the result. For example, ask to "release a patch" or "publish version 0.5.0". Without a version, it first synchronizes the repository and then asks you to choose major, minor, or patch with concrete version numbers. An explicit version already in package.json is reused; increment requests use the higher of the synchronized local version and npm's highest stable version.

The skill lives in .agents/skills/release, with relative symlinks at claude/skills/release and .claude/skills/release (Claude Code's project skill location). It is repository maintenance tooling and is not included in the npm package.

Releases use npm trusted publishing from GitHub Actions. No npm token secret is needed. The publish.yml workflow uses the pnpm version pinned in package.json, installs the frozen lockfile, and runs the existing prepublishOnly checks before publishing.

The package's npm Settings → Trusted Publisher connection must specify:

Field	Value
Provider	GitHub Actions
Organization or user	jtsang4
Repository	pi-extensions
Workflow filename	publish.yml
Environment	Leave empty
Allowed actions	Enable direct publishing (npm publish), not only staging

To validate the configuration without releasing a version:

gh workflow run publish.yml --ref main -f dry_run=true

The dry run exchanges the workflow's OIDC identity for an npm credential to verify the real trust relationship, then runs pnpm publish --dry-run. Credentials stay in memory and are never printed or stored. Both this repository and the package are public, so pnpm's OIDC flow also enables npm provenance.

For a release, bump the version, commit the changes, and push main. Then push a tag matching package.json exactly:

release_tag="v$(node -p 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8")).version')"
git tag "$release_tag"
git push origin "$release_tag"

The tag push publishes automatically. Stable versions use the latest npm dist-tag; prereleases use next. The workflow rejects mismatched tags and commits outside main's history. Manual runs default to dry-run mode; to retry a failed release, dispatch the workflow at its release tag with dry_run=false. An already-published version cannot be overwritten.

License

MIT