SuPi (Super Pi)

SuPi is a curated extension toolkit for the PI coding agent: code understanding, external knowledge lookup, context and cache observability, structured decisions, review/reporting workflows, and quality-of-life in one package family.

It is also my daily PI setup, shared as installable packages so you can use the full stack or only the parts that fit your workflow.

What SuPi is trying to achieve

• Make PI stronger in real coding sessions: code understanding, external docs lookup, session-aware review, reporting, diagnostics, and quality-of-life.
• Bring IDE-like navigation and tool-supported refactorings into agent workflows.
• Build with the initial context window in mind: focused tools, concise descriptions, and short guidelines.
• Make agent-user decisions structured when free-form chat would be ambiguous.
• Make sessions observable with context usage monitors, prompt-cache health, debug events, and usage insights.
• Stay modular: install the recommended stack or only the packages you want.

Quick Start

Install the release SuPi stack globally:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install.sh | bash

Or install it project-locally into .pi/settings.json:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install.sh | bash -s -- -l

Want everything including beta packages? Use install-all.sh instead. Prefer a single package? Use any install command from the package cards below, for example:

pi install npm:@mrclrchtr/supi-code-intelligence

Run /reload in PI after installing new extensions.

What you get

Code understanding & IDE-like navigation

High-level code briefs, impact analysis, semantic navigation, AST-level structural inspection, and tool-supported refactorings.

Install @mrclrchtr/supi-code-intelligence for the full code-understanding stack. @mrclrchtr/supi-lsp and @mrclrchtr/supi-tree-sitter are linked for lower-level details and direct use.

External knowledge & project context

Fetch public web pages as clean Markdown, look up focused library docs, and keep repository-specific context close to the files where it matters.

Packages: supi-web, supi-claude-md

Observability

See how the current session spends context, watch prompt-cache health, inspect cache regressions across sessions, and debug extension behavior when something looks wrong.

Packages: supi-context, supi-cache, supi-debug

Review & reporting

Run session-aware review workflows over git snapshots and generate reports from historical PI sessions.

Packages: supi-review, supi-insights

Quality-of-life & structured decisions

Give the agent a richer way to ask focused questions, prevent hung shell commands from stalling a session, add ghost-text prompt suggestions, and small PI conveniences like aliases, prompt stashing, and activity indicators.

Packages: supi-ask-user, supi-bash-timeout, supi-extras, supi-prompt-suggestions

Configure SuPi

@mrclrchtr/supi-settings provides the shared /supi-settings TUI for project/global configuration exposed by SuPi packages.

pi install npm:@mrclrchtr/supi-settings

Read package README →

Packages

Badges: Agent means PI can use the package directly through tools, injected context, or tool-call hooks. Human means the user drives it through commands, reports, shortcuts, or UI. Beta marks packages that are still stabilizing. DevTool marks packages primarily for debugging or extension development.

Code understanding & IDE-like navigation

@mrclrchtr/supi-code-intelligence

Agent

Architecture briefs, caller/callee analysis, impact assessment, pattern search, and tool-supported refactorings. Recommended entry point for the full code-understanding stack.

pi install npm:@mrclrchtr/supi-code-intelligence

Read package README →

@mrclrchtr/supi-lsp

Agent Human

Language Server Protocol support for semantic navigation, references, diagnostics, hover types, rename, and an LSP status view.

pi install npm:@mrclrchtr/supi-lsp

Read package README →

@mrclrchtr/supi-tree-sitter

Agent

AST-level structural analysis for outlines, imports/exports, syntax nodes, custom queries, and outgoing callees.

pi install npm:@mrclrchtr/supi-tree-sitter

Read package README →

External knowledge & project context

@mrclrchtr/supi-web

Agent

Clean Markdown web fetching and focused library-documentation lookup for grounded agent research.

pi install npm:@mrclrchtr/supi-web

Read package README →

@mrclrchtr/supi-claude-md

Agent Beta

Bundled skills for auditing and revising repository-specific CLAUDE.md/AGENTS.md guidance.

pi install npm:@mrclrchtr/supi-claude-md

Read package README →

Observability

@mrclrchtr/supi-context

Human

Detailed current-session context usage monitor for token budgets, active skills, guidelines, tool definitions, and injected context.

pi install npm:@mrclrchtr/supi-context

Read package README →

@mrclrchtr/supi-cache

Agent Human Beta

Prompt-cache health monitoring and cross-session cache-regression forensics.

pi install npm:@mrclrchtr/supi-cache

Read package README →

@mrclrchtr/supi-debug

Agent Human DevTool

Shared debug-event capture, inspection commands, and an agent tool for troubleshooting SuPi/PI extension behavior.

pi install npm:@mrclrchtr/supi-debug

Read package README →

Review & reporting

@mrclrchtr/supi-review

Human Beta

Guided session-aware review over git snapshots with brief synthesis, plan preview, read-only reviewer agents, and structured findings.

pi install npm:@mrclrchtr/supi-review

Read package README →

@mrclrchtr/supi-insights

Human Beta

Historical PI session analytics and shareable HTML reports for usage patterns.

pi install npm:@mrclrchtr/supi-insights

Read package README →

Quality-of-life & structured decisions

@mrclrchtr/supi-ask-user

Agent Human

Keyboard-driven questionnaire UI for structured decisions when the agent needs focused input before continuing.

pi install npm:@mrclrchtr/supi-ask-user

Read package README →

@mrclrchtr/supi-bash-timeout

Agent Beta

Default timeouts for bash tool calls so a hung shell command does not stall the session.

pi install npm:@mrclrchtr/supi-bash-timeout

Read package README →

@mrclrchtr/supi-extras

Human

Aliases, skill shorthand, prompt stash overlay, activity indicators, and other PI session polish.

pi install npm:@mrclrchtr/supi-extras

Read package README →

@mrclrchtr/supi-prompt-suggestions

Human

Advisory ghost-text prompt suggestions after each assistant response, generated by a cheap model you choose.

pi install npm:@mrclrchtr/supi-prompt-suggestions

Read package README →

Infrastructure packages

These packages support the extension stack and are linked for maintainers and extension authors. They are not promoted as standalone PI extensions.

• @mrclrchtr/supi-core — shared infrastructure for SuPi extensions, including configuration, settings, path helpers, reporting, and session utilities.
• @mrclrchtr/supi-code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack.
• @mrclrchtr/supi-test-utils — shared test helpers for SuPi extension packages.

Install details

Release stack

Global install:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install.sh | bash

Project-local install into .pi/settings.json:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install.sh | bash -s -- -l

The release script installs the stable SuPi packages from npm.

Full stack (release + beta)

Global install:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install-all.sh | bash

Project-local install into .pi/settings.json:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/install-all.sh | bash -s -- -l

The full-stack script adds beta packages on top of the release set. Run /reload in PI after installation.

Individual packages

pi install npm:@mrclrchtr/supi-web
pi install npm:@mrclrchtr/supi-review

Use any package name from the catalog above.

Full workspace from git or local path

pi install git:github.com/mrclrchtr/supi

pi install /path/to/supi

The repo root includes the workspace extension manifest for development and full-stack local installs. When installed from a local path, PI loads the working tree directly; after edits, use /reload or restart PI.

Uninstall

Release stack

Global uninstall:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/uninstall.sh | bash

Project-local uninstall from .pi/settings.json:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/uninstall.sh | bash -s -- -l

Full stack (release + beta)

Global uninstall:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/uninstall-all.sh | bash

Project-local uninstall from .pi/settings.json:

curl -fsSL https://raw.githubusercontent.com/mrclrchtr/supi/main/scripts/uninstall-all.sh | bash -s -- -l

The uninstall scripts also attempt to remove deprecated (@mrclrchtr/supi, @mrclrchtr/supi-rtk) and formerly-standalone (@mrclrchtr/supi-lsp, @mrclrchtr/supi-tree-sitter) packages as a best-effort cleanup — they show — instead of ✗ when not installed.

Individual packages

pi uninstall npm:@mrclrchtr/supi-web
pi uninstall npm:@mrclrchtr/supi-review

Run /reload in PI after uninstalling extensions.