The Core Idea

OpenPi turns Pi into a richer engineering environment without copying another assistant's file layout.

It uses Pi-owned package surfaces:

• prompts/*.md for slash-command prompt templates
• skills/*/SKILL.md for Pi skills
• agents/*.md for specialist role prompts
• extensions/*.ts for native Pi commands, tools, profile switching, themes, and workflow orchestration
• themes/*.json for terminal UI themes

Plain Pi session                         OpenPi session

Manual project scan                      /prime and /explore orient the session
Ad hoc planning                          /spec, /clarify, /blueprint, /debate
One long assistant context               spawn_agents delegates to role agents
Manual grep/tree work                    project_tree and code_search_batch
Manual safety checks                     secret_scan, env_scan, ghost_test_scan
Lost session reasoning                   /snapshot, goal_state, write_snapshot
One profile for every task               /openpi use <profile>

OpenPi is not a project template. It is a reusable Pi package you install once and activate per project or globally.

Install

npm i @matyah00/openpi

For Pi:

pi install npm:@matyah00/openpi

Restart Pi after install, then activate a profile:

/openpi use full
/reload

The npm names openpi and open-pi are blocked by npm's package-name similarity policy, so the public npm package is:

@matyah00/openpi

Quick Start

/openpi list                 show every profile
/openpi use commands         enable prompt commands and core tools
/openpi use workflow         enable /add, /fix, /review and spawn_agents
/openpi use guard            enable security, dependency, and ship gates
/openpi use commands+guard   combine multiple profiles (e.g. focus+safety)
/openpi use full --dry-run   preview profile settings changes without writing
/openpi use full             enable the broad OpenPi surface
/openpi clear                remove OpenPi-managed extensions

Use --global to install the selected profile into your global Pi settings:

/openpi use full --global

Profiles update .pi/settings.json. Run /reload or restart Pi after switching.

What You Get

OpenPi
  13 profiles          choose or compose a focused runtime surface
  23 prompt commands   /prime, /blueprint, /deep, /ship, /refactor, ...
  42 agent prompts     planner, reviewer, tester, api-designer, Pi experts
  9 skills             ultrathink, test-first, refactor-guide, bowser, ...
  11 themes            tokyo-night, rose-pine, gruvbox, nord, dracula, ...
  Native tools         search, audit, state, snapshot, dispatch, chains
  Audit Telemetry      structured JSONL audit logging to .pi/logs/

OpenPi is designed around one practical rule: load only the surface you need.

| Need | Profile | What it adds | |------|---------|--------------| | Slash commands | commands | Prompt commands, search tools, state tools, theme switching | | Explore a repo | explore | Tree/search/discovery workflows | | Implement work | workflow | /add, /fix, /review, spawn_agents | | Pre-ship safety | guard | Security, dependency, environment, and test-integrity tools | | Focused UI | focus | Minimal Pi UI plus theme defaults | | Session purpose | purpose | Keeps task purpose visible while working | | Metrics | metrics | Model, context, branch, token, cost, and tool counters | | Personas | system | Switch active system persona from bundled agents | | Teams | team | Dispatcher-only role team with dispatch_agent | | Chains | chain | Sequential workflow runner with run_chain | | Everything | full | Commands, workflow, safety, metrics, personas, teams, chains |

Commands

OpenPi prompt commands are markdown templates with frontmatter metadata. They are loaded from the package and can be extended by project-local .pi/prompts/*.md.

Planning and reasoning

| Command | Purpose | |---------|---------| | /prime | Load project orientation before work | | /spec | Turn a vague feature into a structured spec | | /clarify | Ask focused clarification questions before coding | | /blueprint | Build an implementation blueprint before risky work | | /debate | Run adversarial decision analysis for tradeoffs | | /deep | Use deeper evidence-led reasoning for hard bugs or architecture | | /plan-team | Create a team-oriented implementation plan |

Discovery and state

| Command | Purpose | |---------|---------| | /explore | Map relevant files and code paths | | /goal | Manage durable task goals in .pi/memory/goals.md | | /snapshot | Save a continuation checkpoint before compaction | | /compress | Compress current task context into a handoff brief | | /commands | List loaded OpenPi and project prompt commands | | /command:status | Show command loader status and collisions |

Quality and release

| Command | Purpose | |---------|---------| | /code-review | Review code or changes for bugs and missing tests | | /test | Select or design focused validation | | /validate | Run targeted validation for current work | | /deps | Audit dependency manifests, lockfiles, pins, and update risk | | /ghost-test | Detect vacuous tests and reward-hacking test patterns | | /sentinel | Read-only security and environment safety scan | | /ship | Pre-ship gate for tests, security, dependency risk, and git readiness | | /parallel | Plan safe parallel work with ownership checks |

Agent Workflows

The workflow profile adds high-level commands that prompt Pi to use role agents and verification steps.

/add <feature>       discover files -> plan -> edit -> test -> review
/fix <bug>           reproduce/inspect -> plan -> patch -> validate -> review
/review [scope]      read-only review over diff or requested scope
/openpi-agents       list available role agents

OpenPi role agents include:

| Agent | Role | |-------|------| | file-picker | Finds relevant files and line ranges before edits | | planner | Produces scoped implementation plans | | editor | Performs isolated edits when the plan is clear | | tester | Selects and runs targeted validation | | reviewer | Reviews diffs for bugs, regressions, and missing tests | | security-auditor | Checks secrets, risky automation, and security-sensitive changes | | problem-architect | Turns ambiguous work into a concrete team spec | | spec-reviewer | Challenges unclear requirements before implementation | | ship-guard | Reviews release readiness | | red-team | Challenges plans and assumptions | | api-designer | Reviews REST/GraphQL APIs for design and naming consistency | | perf-auditor | Evaluates bundle sizes, N+1 queries, and resource leaks | | migration-expert | Plans database and architecture migration sequences | | docs-writer | Generates/maintains READMEs, manuals, and architecture documents |

The spawn_agents tool can run agents sequentially or in parallel as isolated Pi subprocesses. It returns structured outputs: files, line ranges, commands, exact validation output, findings, and assumptions.

Team and Chain Modes

OpenPi has two orchestration modes for larger work.

Team dispatcher

/openpi use team
/agents-list
/agents-team guard

The team profile registers dispatch_agent and uses teams from agents/teams.yaml, including:

| Team | Agents | |------|--------| | research | scout, directory-lister, glob-matcher, code-searcher, librarian, documenter, red-team | | validation | tester, basher, reviewer | | guard | security-auditor, rule-verifier, ship-guard, spec-reviewer | | frontend | scout, frontend, reviewer | | backend | scout, backend, reviewer | | pi-pi | Pi package, extension, skill, prompt, config, theme, TUI, CLI, and keybinding experts | | perf | scout, perf-auditor, planner, reviewer | | docs | scout, docs-writer, reviewer | | api | scout, api-designer, reviewer | | migration | scout, migration-expert, planner, reviewer |

Chain runner

/openpi use chain
/chain-list

The chain profile registers run_chain for sequential workflows from agents/agent-chain.yaml:

| Chain | Flow | |-------|------| | plan-build-review | planner -> builder -> reviewer | | research-plan | scout -> red-team -> planner | | deep-explore | directory-lister -> code-searcher -> thinker | | evidence-validate | code-searcher -> tester -> reviewer | | spec-to-plan | problem-architect -> spec-reviewer -> planner | | ship-gate | security-auditor -> ship-guard -> reviewer | | pi-package-design | Pi experts -> planner | | refactor-flow | scout -> problem-architect -> planner -> reviewer | | docs-flow | scout -> docs-writer -> reviewer | | perf-audit | scout -> perf-auditor -> planner | | full-lifecycle | problem-architect -> planner -> plan-reviewer -> builder -> tester -> reviewer |

Tooling

OpenPi registers native Pi tools through profiles.

| Tool | Purpose | |------|---------| | project_tree | Return a scoped project tree with ignore handling (supports file sizes) | | code_search_batch | Run multiple code searches in one call (supports case-sensitivity & regex toggle) | | env_scan | Detect stack, package managers, scripts, and environment clues (24+ frameworks) | | secret_scan | Search for 22 types of cloud keys, tokens, credentials, and high-entropy hex strings | | ghost_test_scan | Find weak, empty, mocked-everything, self-comparing, or reward-hacked tests | | sast_scan | Static Application Security Testing for eval, SQL concat, SSRF, CORS wildcards, and XSS | | dependency_inventory | Summarize dependency manifests and lockfiles | | session_state | Read current session state | | goal_state | Read goal memory state | | write_snapshot | Write a continuation snapshot | | parallel_safety_check | Check file ownership overlap before parallel work | | spawn_agents | Run role agents as isolated Pi subprocesses (supports retries & timeouts) | | dispatch_agent | Dispatch to the active specialist team | | run_chain | Run a named sequential agent chain (supports step timeouts, continueOnError, & $STEP_N) |

Skills

OpenPi ships focused Pi skills:

| Skill | Use it for | |-------|------------| | ultrathink | Hard debugging, architecture tradeoffs, root-cause analysis | | test-first | Production code, bug fixes, refactors, validation planning | | security-guard | Credentials, env files, external code, automation, deploy risk | | spec-driven | Vague requirements, unclear features, acceptance criteria | | session-continuity | Long context, resuming, stopping, compaction handoffs | | env-scanner | Unknown repos, setup issues, stack detection | | bowser | Playwright-powered browser automation and UI testing | | refactor-guide | Guides safe codebase refactoring with code smell detection and verification | | perf-auditor | Structured resource profiling and runtime execution optimization |

Themes and UI Profiles

OpenPi includes 11 bundled themes:

catppuccin-mocha  cyberpunk  dracula  everforest  gruvbox
midnight-ocean    nord       ocean-breeze  rose-pine
synthwave         tokyo-night

Use the theme profile or the full profile, then:

/theme
/theme tokyo-night

UI-oriented profiles:

| Profile | Purpose | |---------|---------| | focus | Minimal, distraction-free Pi UI | | metrics | Status bar and usage metrics | | tool-widget | Live per-tool usage counts | | purpose | Session purpose gate and visible task focus | | safety | Damage-control rules and actionable blocked-tool feedback |

Architecture

OpenPi is a package, not a project scaffold.

@matyah00/openpi
  package.json              Pi package manifest
  prompts/                  prompt commands
  skills/                   Pi skills
  agents/                   role agents, teams, chains
  extensions/               native Pi extensions and tools
  themes/                   terminal UI themes
  damage-control-rules.yaml safety feedback rules

The activation flow is explicit:

1. Install package with Pi
2. Run /openpi use <profile>
3. OpenPi writes selected extension paths into .pi/settings.json
4. Run /reload or restart Pi
5. Use only the commands/tools for that profile

This keeps OpenPi portable across projects. You can add project-specific prompts and agents in .pi/prompts and .pi/agents; OpenPi will load them alongside the bundled resources where the active profile supports it.

Why It Is Different

| Without OpenPi | With OpenPi | |----------------|-------------| | One generic assistant flow | Profiles for planning, workflow, guard, team, chain, UI | | Manual project discovery | /explore, project_tree, code_search_batch | | Vague implementation prompts | /spec, /clarify, /blueprint, problem-architect | | Manual review discipline | /review, reviewer, ship-guard, ghost_test_scan | | One large context | spawn_agents, dispatch_agent, run_chain | | Repeated session loss | /snapshot, write_snapshot, goal_state | | Ad hoc security checks | secret_scan, /sentinel, security-guard | | Same UI for every task | focus, metrics, purpose, tool-widget, safety profiles |

Verified

Before publish, the package is checked with:

npm pack --dry-run
npx tsc --noEmit
npm install @matyah00/openpi@latest --dry-run

Current npm package:

npm i @matyah00/openpi
pi install npm:@matyah00/openpi

License

MIT - haytamAroui