@pi-unipi/utility

Environment info, diagnostics, cleanup, and the session name badge. The grab-bag package for maintaining your development environment and keeping an eye on provider cache behavior.

Commands

| Command | Description | |---------|-------------| | /unipi:env | Show environment info (Node, Pi, OS, paths) | | /unipi:doctor | Run diagnostics across all modules | | /unipi:status | Show immediate guidance to the live /unipi:info dashboard and /unipi:doctor diagnostics | | /unipi:cleanup | Clean stale DBs, temp files, old sessions | | /unipi:reload | Explain how to reload extensions | | /unipi:name-badge | Toggle name badge overlay | | /unipi:badge-gen | Generate session name via LLM and enable badge | | /unipi:badge-name | Set the session name shown in the badge | | /unipi:badge-settings | Configure badge behavior | | /unipi:util-settings | Unified settings TUI (badge) | | /unipi:prefix-cache | Show privacy-safe request-prefix transitions and provider cache token counters |

Examples

/unipi:env                 # Show environment
/unipi:doctor              # Run diagnostics
/unipi:cleanup             # Clean stale files
/unipi:cleanup --dry-run   # Preview what would be cleaned
/unipi:name-badge          # Toggle the session name badge
/unipi:badge-gen           # Generate a session name via LLM

Special Triggers

Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment. When Herdr is present, the badge module syncs the session name to the pane title.

Provider prefix-cache diagnostics

/unipi:prefix-cache observes Pi's provider-native request payloads without modifying them. It reports session-local cache epochs, exact structural prefix extensions, retries, request-envelope/history boundaries, and provider-reported cacheRead/cacheWrite token totals.

The fingerprints are keyed HMAC-SHA-256 values using a random in-memory key that is discarded on reload. Raw prompts, messages, tool arguments, tool schemas, and provider payloads are never retained or logged by this diagnostic. Fingerprints therefore cannot be compared across process lifetimes. A reported prefix extension means the request is structurally eligible for reuse; provider TTL, routing, and cache policy still decide whether a hit occurs.

/unipi:cleanup includes private ~/.unipi/tool-results/ artifacts in the normal temporary-file retention policy (7 days by default). Use dry-run mode to review candidates before deletion.

Agent Tools

| Tool | Description | |------|-------------| | ctx_env | Environment inspection for debugging | | set_session_name | Set the session name for badge display (when badge agent-tool is enabled) |

Configurables

Name Badge

/unipi:util-settings        # Open unified settings TUI

Or edit .unipi/config/util-settings.json directly (migrated automatically from the legacy .unipi/config/badge.json on first read):

{
  "badge": {
    "badgeEnabled": true
  }
}

The badge is a persistent HUD overlay in the top-right corner showing the current session name. It auto-restores visibility on session restart.

Skill Startup Discovery

Controls whether Unipi's built-in skills are cataloged in the agent's system prompt at startup (default: on). Your own skills — global, project, settings-mounted, and third-party packages — always stay cataloged.

/unipi:skills-settings        # Interactive toggle (or /unipi:skills-settings on|off)

Or edit ~/.pi/agent/settings.json directly:

{
  "unipi": {
    "skills": { "discovery": false }
  }
}

When off, Unipi's bundled skills are removed from the <available_skills> catalog, so their metadata never populates agent context. They remain invocable via /skill:name — pi expands those commands by reading the skill file directly, independent of the prompt catalog. The filter is applied consistently every turn, so provider prefix caching is unaffected.

Programmatic API

| Module | Path | Description | |--------|------|-------------| | ProcessLifecycle | lifecycle/process | Parent PID polling, orphan detection, signal handlers | | cleanupStale | lifecycle/cleanup | Stale DB/temp/session cleanup with dry-run | | AnalyticsCollector | analytics/collector | Privacy-respecting event collection with daily rollup | | runDiagnostics | diagnostics/engine | Cross-module health checks with plugin architecture |

Privacy

The analytics collector is privacy-respecting:

• No file contents recorded
• No sensitive data (API keys, tokens, passwords) — redacted automatically
• Strings truncated to 500 characters
• All data stays local

License

MIT