Skip to content
edhor1608Public

About

Pi package with model-specific prompts and structured compaction

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pi-tools

pi-tools is a focused Pi package with twelve independent extensions:

  • external-session-import imports local Claude Code and Codex transcripts into new native Pi sessions
  • subagents runs background Pi and Claude Code agents with strict model routing
  • statusline adds a Claude-style footer with context and Codex limit telemetry, composing statuses published by other extensions
  • file-footnotes keeps file-heavy assistant answers readable
  • stash stores complete prompts for controlled later release
  • structured-compaction preserves continuity in long sessions
  • review-loop runs a session-persisted review-fix state machine (/review-loop, agent-callable)
  • lifecycle-failures appends redacted failed tool calls to ~/memories/tool-failures.jsonl
  • memories-sync commits writes under ~/memories/memory/ with path-scoped git commits
  • usage-guard warns and directs wrap-up before Codex subscription limits are exhausted
  • session-gap injects a re-orientation briefing after two days of session inactivity
  • personal-lint returns personal (non-CI) lint diagnostics for freshly edited JS/TS files

The package is developed and validated against Pi 0.82.1. See docs/pi-version-notes.md for integration details.

Install

Install Pi first if needed:

npm install -g @earendil-works/pi-coding-agent

Install this package:

pi install git:github.com/edhor1608/pi-tools

A local checkout also works:

pi install /absolute/path/to/pi-tools

The twelve extensions are exposed separately and can be enabled or disabled through pi config.

External Session Import

/resume-external, /resume-claude, and /resume-codex discover local sessions; each accepts an optional path or cwd filter. The importer asks for the target working directory, then creates a new native Pi session containing the user/assistant text, provenance, non-contextual full tool activity, and compact contextual tool summaries. Press Escape to cancel parsing. Source sessions are never modified.

Subagents

Subagents run autonomously with their own context windows, sessions, and normal host permissions. The pi harness runs an in-process Pi SDK session and inherits the parent model and thinking level by default. The claude harness uses the local Claude Code executable and its existing authentication; omitted model and reasoning options preserve Claude Code defaults.

The parent model can use:

  • subagent_spawn to start background work
  • subagent_check and subagent_list to inspect the complete agent tree without blocking
  • subagent_send to steer or continue any tracked session
  • subagent_wait when a result is required immediately
  • subagent_cancel to abort work while preserving its transcript

Set mode: "orchestrator" on a Claude spawn to give it direct host-managed spawn, check, list, send, wait, and cancel controls. It can dynamically create Pi or Claude descendants; every node remains visible and steerable from the main agent and /subagents. Nested results return to their immediate parent, and a root orchestrator is not reported complete while descendants remain active.

Settled results return automatically. /subagents opens a hierarchical picker, then a full-screen transcript where any node can be steered or aborted. There is no extension-level concurrency limit, workflow, approval gate, sandbox, or project trust gate. Ordinary workers and all Pi children remain leaves; orchestrator capability is explicit. Claude's separate native Agent/Task tree and interactive user prompts remain disabled.

Claude requires an authenticated local installation:

claude auth status

OpenRouter is reserved for rare paid root specialists. It requires all three gates: an explicit openrouter/<model-id>, persistent "allowPaidOpenrouter": true in the user-owned ~/.pi/agent/pi-tools.json before Pi loads the extension, and allowPaidOpenrouter: true on that spawn. OpenRouter is never selected by a bare id, inheritance, nested orchestration, or fallback. Claude-family ids still use Claude Code. OpenCode providers are retired and rejected explicitly.

Statusline

Statusline replaces Pi's default footer with a compact Claude-style line:

  • repo-relative cwd, git branch, and dirty marker
  • active model and thinking level
  • context-window progress bar from Pi's current context usage
  • session token and cost totals
  • Codex account usage from https://chatgpt.com/backend-api/codex/usage
  • both Codex windows when OpenAI reports them, e.g. 5h and 7d

The Codex segment uses Pi's existing openai-codex OAuth token, caches only non-secret usage data in ~/.pi/agent/pi-statusline-cache.json, and refreshes at most once per minute. Provider x-ratelimit-* headers are still used as a fallback when present. If OpenAI returns only one account window, only that window is shown. Account usage fetches require python3; if it is unavailable, the footer keeps working and only the Codex usage segment is omitted or shown as unavailable.

Toggle or inspect it at runtime:

/pi-statusline
/pi-statusline debug

File Footnotes

Finalized assistant messages are transformed through Pi's public message_end hook:

  • absolute file links become short labels with numbered links
  • a visible File references list is appended to the same message
  • web links, inline code, and fenced code remain unchanged
  • footnotes persist across resumed and exported sessions

Use the command as a fallback opener:

/file-footnotes
/file-footnotes open 1
/file-footnotes vscode 1

Stash

Stash is a deferred-prompt lane. Waiting items stay outside model context until released.

Modes:

  • manual — release explicitly
  • draft — load into the editor when the agent is ready
  • send — send automatically when the agent is ready

Examples:

/stash add manual Review the final diff
/stash add draft Write the changelog
/stash add send Run the release checklist
/stash list
/stash apply 1
/stash send 1

Shortcuts:

  • Ctrl+Alt+S stashes the current editor text
  • Ctrl+Shift+S opens the stash UI

Structured Compaction

Structured Compaction keeps Pi's native trigger and session storage while replacing the compacted span with a versioned artifact.

Backends:

  • auto — try provider-native Codex/OpenAI compaction, then fall back locally
  • codex-remote — require provider-native Responses compaction
  • pi-model — summarize with a configured or active Pi model

Compatible remote output is persisted and reinjected into later Responses requests. A human-readable local summary remains available when the model or provider changes.

Runtime files are seeded under:

~/.pi/agent/structured-compaction/config.json
~/.pi/agent/structured-compaction/prompts/system.md
~/.pi/agent/structured-compaction/prompts/compact.md

Project overrides use .pi/structured-compaction/.

Commands:

/compaction-report latest
/compaction-report all
/trigger-compact
/trigger-compact preserve implementation decisions

Offline session analysis:

pnpm run analyze ~/.pi/agent/sessions/.../session.jsonl

More details: defaults/structured-compaction/README.md.

Development

pnpm install --frozen-lockfile
pnpm run check

pnpm run check runs Oxfmt verification, Oxlint with type-aware linting and compiler diagnostics, and the Node test suite. TypeScript scripts run directly on Node 26.

About

Pi package with model-specific prompts and structured compaction

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages