pi-packages

Independent Pi coding agent extensions focused on developer workflow. This repo keeps small Pi packages in one workspace while preserving independent package versions, release notes, and npm publishing.

Most packages publish raw TypeScript source that Pi loads through jiti, so they are not built to dist/. The exceptions are pi-station and pi-subagents (esbuild-bundled entrypoints), which build to dist/ via pnpm --dir packages/<pkg> build.

Packages

Package	Role	Install	npm	Version
pi-permission-system	Central permission gates for tools, bash, MCP, skills, file paths, and subagents. Edit permission prompt is status-only; the diff lives in the chat via the edit tool.	<NONE>		0.2.2
pi-reference	Project references: declare local dirs and Git repos as agent-accessible with @alias autocomplete.	<NONE>		0.2.1
pi-simplify	Reviews recent code changes for clarity, consistency, and maintainability.	pnpm add @nielpattin/pi-simplify	npm	0.2.9
pi-station	Station bar, fixed editor layout, bash mode, stash, prompt history, undo/redo, hashline read/edit with in-chat diff preview, and configurable segments for the Pi TUI.	pnpm add @nielpattin/pi-station	npm	0.9.0
pi-subagents	Autonomous subagent spawning, steering, result retrieval, and /agents UI.	<NONE>		0.2.1
pi-multi-auth	Multi-provider credential management, OAuth login, and account rotation.	<NONE>	source	0.12.0

Prerequisites

• Node.js 24
• pnpm 11
• Pi coding agent for running extensions

Setup

pnpm install

Daily Development

pnpm fmt       # format with oxfmt
pnpm lint      # auto-fix lint issues with oxlint
pnpm test      # run Vitest tests
pnpm coverage  # run Vitest coverage with enforced thresholds
pnpm check     # lint, format check, and TypeScript typecheck

Git hooks are the validation source for this repo:

• pre-commit: pnpm lint-staged (oxlint + oxfmt --check on staged files)
• pre-push: pnpm test and node scripts/require-changeset.mjs origin/main

GitHub has no CI workflow for routine pushes. Run the local hooks before pushing.

Package Validation

Use package dry runs to verify npm tarball contents before publishing:

pnpm --dir packages/pi-simplify pack --dry-run
pnpm --dir packages/pi-permission-system pack --dry-run
pnpm --dir packages/pi-reference pack --dry-run
pnpm --dir packages/pi-subagents pack --dry-run
pnpm --dir packages/pi-station pack --dry-run
pnpm --dir packages/pi-multi-auth pack --dry-run

For raw-TS packages, the dry-run output should include TypeScript source files and package docs, and should not include dist/. For pi-station and pi-subagents, the dry-run should include the built dist/.

Add a New Package

1. Create packages/pi-foo/ with package.json and tsconfig.json.
2. The root workspace already includes packages/* in pnpm-workspace.yaml and root package.json.
3. Ensure the package has:
   • "type": "module"
   • "engines": { "node": ">=24" }
   • main pointing to the TypeScript source entrypoint
   • pi.extensions or pi.skills pointing to package resources
   • a test script when it has tests
   • source files and docs in files[]
   • repository metadata with directory: "packages/pi-foo"
4. Add a changeset with pnpm changeset for package-impacting changes.

Changesets Release Flow

Packages are versioned independently with Changesets.

pnpm changeset          # record the package and semver impact
pnpm version-packages   # apply changesets and sync the root changelog summary

pnpm version-packages runs changeset version and then pnpm changelog:sync. Changesets updates package versions and package changelogs. CHANGELOG.md summarizes the latest package changelog entries and is generated from package changelogs.

Changesets uses scoped package tags such as @nielpattin/pi-station@0.9.0. Prefer that tag convention for new releases.

The legacy scripts/release.mjs script is kept for reference during the transition. Prefer Changesets for new releases.

pnpm release runs changeset publish and can publish packages to npm. Do not run release, publish, push, or commit steps unless explicitly intended.

Publish

Publishing is manual, exact, and tag-only. The GitHub publish workflow accepts a package plus a Changesets tag, checks out that tag, verifies the selected package version, runs package-local pack --dry-run, then publishes only that package.

./publish.sh pi-station --tag '@nielpattin/pi-station@0.9.0'

The publish workflow installs dependencies and packages the selected package. It does not run pnpm check, pnpm test, or pnpm coverage.

Aggregate Packages

Aggregate package collections are intentionally deferred. Pi package docs require bundled dependencies and node_modules/ resource paths for other pi packages. Publishable aggregates such as @nielpattin/pi-packages, @nielpattin/pi-extensions, or @nielpattin/pi-skills should only be added after local package installation tests prove those paths work for this repo's raw TypeScript packages.

Project Structure

pi-packages/
├── .changeset/                   # Changesets config and notes
├── .github/workflows/
│   └── publish.yml               # exact manual npm publish
├── .husky/
│   ├── pre-commit                # pnpm lint-staged
│   └── pre-push                  # pnpm test + changeset gate
├── .nvmrc                        # Node 24
├── openspec/                     # change proposals and specs
├── packages/
│   ├── pi-multi-auth             # unpublished
│   ├── pi-permission-system      # unpublished
│   ├── pi-reference              # unpublished
│   ├── pi-simplify               # published npm package
│   ├── pi-station                # published npm package
│   └── pi-subagents              # unpublished
├── scripts/
│   ├── release.mjs               # legacy per-package release orchestrator
│   ├── require-changeset.mjs     # local changeset gate
│   └── sync-monorepo-changelog.mjs
├── publish.sh                    # gh workflow dispatch helper
├── CHANGELOG.md                  # generated package changelog summary
├── oxlint.config.ts              # oxlint config
├── oxfmt.config.ts               # oxfmt config
├── package.json                  # workspaces, shared devDeps, scripts
├── pnpm-workspace.yaml           # packages/* workspace definition
├── tsconfig.json                 # shared TS config
└── vitest.config.ts              # tests and coverage

Tooling

Tool	Config	Purpose
Changesets	.changeset/	Versioning and changelogs
oxlint	oxlint.config.ts	Linting
oxfmt	oxfmt.config.ts	Formatting
Vitest	vitest.config.ts	Testing and coverage
TypeScript	tsconfig.json	Type checking
Husky	.husky/*	Git hooks
pnpm	pnpm-workspace.yaml	Package manager and workspaces

License

MIT