@codersbrew/pi-tools

A publishable pi package that bundles CodersBrew pi extensions, skills, and prompt templates.

Included resources

Extensions

security

Protects common dangerous tool operations by:

• warning or blocking risky bash commands such as rm -rf, sudo, and destructive disk operations
• blocking writes to sensitive paths like .env, .git, node_modules, SSH keys, and common secrets files
• prompting before lockfile edits such as package-lock.json, yarn.lock, and pnpm-lock.yaml

session-breakdown

Adds an interactive TUI for analyzing pi session history from ~/.pi/agent/sessions, including:

• sessions, messages, tokens, and cost over the last 7 / 30 / 90 days
• model, cwd, day-of-week, and time-of-day breakdowns
• contribution-style heatmap visualizations

update-pi

Adds a /update-pi slash command that upgrades @mariozechner/pi-coding-agent using your detected package manager (or configured npmCommand) and reminds you to restart pi afterward.

subagent

Delegates work to specialized subagents that run in isolated pi subprocesses.

Primary bundled agents:

• planner - investigates the codebase and produces tracked plans
• executor - materializes, executes, resumes, and updates tracked plans
• reviewer - performs an independent read-only review pass

Internal helper:

• worker - delegated implementation helper used by the executor

Primary prompt templates:

• /plan
• /execute-plan
• /implement
• /implement-and-review
• /review

Tracked markdown plans are written to plan/*.md with task IDs, status checkboxes, dependency metadata, and validation steps. Executors can fan out safe parallel worker batches, resume interrupted work, and update shared plan files as work completes.

Override behavior:

• packaged agents act as defaults
• ~/.pi/agent/agents/*.md overrides packaged agents of the same name
• .pi/agents/*.md overrides both packaged and user-level agents when agentScope: "project" or "both"

Skill: github-workflow

An opinionated GitHub workflow skill for branch creation, commits, pushes, PR creation, review, and merge work.

It prefers gh for GitHub-aware actions and uses plain git where local source-control operations are the better tool.

Invoke it in pi with:

/skill:github-workflow

Skill: plan

A /plan-style planning skill that investigates the codebase and writes a tracked markdown plan under plan/, but does the work in the current conversation context instead of delegating to the bundled subagent workflow.

It is useful when you want the same planning output shape as /plan without spinning up a separate planner/executor process.

Invoke it in pi with:

/skill:plan add Redis caching to the session store

Install

Global install:

pi install npm:@codersbrew/pi-tools

Project-local install:

pi install -l npm:@codersbrew/pi-tools

You can also add it manually to pi settings:

{
  "packages": ["npm:@codersbrew/pi-tools"]
}

Using the bundled subagent workflows

After installing the package, the prompt templates are available directly in pi:

/plan add Redis caching to the session store
/execute-plan plan/add-redis-caching.md
/implement add Redis caching to the session store
/implement-and-review add input validation to API endpoints
/review src/api/handlers.ts src/api/validation.ts

Tracked plans are written to plan/*.md. New-plan workflows create or reuse a focused git branch before materializing the plan when the checkout is clean enough to do so safely. Tasks are checked off in place, blocked tasks are marked explicitly, and testing/type-checking is required before executors mark implementation tasks complete.

If you want the same tracked-plan output without subagent delegation, use the skill instead:

/skill:plan add Redis caching to the session store

To customize or add agents, create markdown agent files in either:

• ~/.pi/agent/agents/ for your personal defaults
• .pi/agents/ for project-local agents

Package structure

This package uses pi's standard package manifest and currently publishes:

• extensions/security.ts
• extensions/session-breakdown.ts
• extensions/update-pi.ts
• extensions/subagent/index.ts
• skills/github-workflow/SKILL.md
• skills/plan/SKILL.md
• extensions/subagent/prompts/*.md

The root package.json exposes them through:

{
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./extensions/subagent/prompts"]
  }
}

Local development

Install dependencies:

npm install

Run local verification:

npm run check

Preview the publish tarball:

npm pack --dry-run

Releasing

This repo includes .github/workflows/release.yml.

Ongoing release flow:

1. Update the package version in package.json
2. Commit and push the change
3. Create and push a matching version tag such as v0.3.0
4. GitHub Actions will run verification, publish to npm, and create a GitHub release

The workflow supports either:

• npm trusted publishing via GitHub OIDC
• NPM_TOKEN fallback publishing when the secret is present

If you use manual dispatch, ensure the version in package.json has not already been published.

License

MIT