Imported from rennis23/pi-mono (AGENTS.md). Install upstream with npx skills add rennis23/pi-mono. Copyright stays with the author.

AGENTS.md

Instructions for AI coding agents working on this repository.

Required: Read DOD-AGENT.md for the Definition of Done criteria that must be met before declaring any task complete.

Project overview

pi-mono is an npm workspaces monorepo for pi.dev extensions. Each package under packages/ is a self-contained pi extension published to npm under the @rennis23 scope.

Tech stack

• Runtime: Node.js 22+
• Language: TypeScript 6, strict mode, ES2022 target
• Module system: ESM ("type": "module", Node16 module resolution)
• Formatter/Linter: Biome 2.5
• Test runner: Vitest 4
• Git hooks: Husky 9

Commands

Always run npm run check and npm test before committing. The Husky pre-commit hook enforces this.

Repository layout

pi-mono/
├── packages/          # Workspace packages (each is a pi extension)
│   └── mx-pi-context-stats/ # Context/token/cost stats widget
├── scripts/           # sync-versions.js, release.mjs
├── test/              # Shared test setup (setup.ts)
├── biome.json         # Shared formatter/linter config
├── tsconfig.base.json # Shared TypeScript config
└── vitest.config.ts   # Shared test runner config

Code style

Biome is the single source of truth for formatting and linting. Key settings (see biome.json):

• Indent: tabs, width 3
• Line width: 120 characters
• noExplicitAny: off — any is allowed
• noNonNullAssertion: off — ! assertions are allowed
• useConst: error — always prefer const

Run npm run check to auto-fix formatting and lint issues (biome check --write).

Conventions

Package naming

Every extension and skill in this repository uses the mx-pi- prefix. All user-visible names must begin with mx-pi-:

• Directory: packages/mx-pi-<name>/
• npm name: @rennis23/mx-pi-<name>
• Registered commands and CLI flags: must start with mx-pi- (e.g. command /mx-pi-context-stats, flags --mx-pi-context-stats-rows)
• Skills (e.g. under sandbox/skills/): mx-pi-<name>/SKILL.md
• Include "pi": { "extensions": ["./index.ts"] } in package.json

Extension structure

Each extension exports a default function that receives ExtensionAPI:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function myExtension(pi: ExtensionAPI) {
   pi.registerCommand("myCommand", {
      description: "What it does",
      handler: async (args, ctx) => {
         // implementation
      },
   });
}

Testing

• Co-locate tests with source: hello.test.ts next to index.ts
• Shared setup lives in test/setup.ts
• Vitest is configured with clearMocks, restoreMocks, and unstubGlobals
• Coverage excludes node_modules, dist, .pi, *.test.ts, and *.d.ts

Versioning

All packages share the same version. Use the release:* scripts — never bump versions manually. The scripts run sync-versions.js and reinstall dependencies.

Git hooks

• pre-commit: runs npm run check (Biome format + lint + tsc)
• pre-push: runs npm test