Files
planning-with-files/docs/pi-agent.md
T
OthmanAdi 27ef36cd3b release: v2.39.0 (Pi full hook parity extension + Codex hooks flag fix)
Adds a bundled TypeScript extension under .pi/skills/planning-with-files/extensions/planning-with-files/
that maps Pi lifecycle events onto the same behavior the skill provides on Claude Code (PR #157 by
@TomXPRIME). Event surface: session_start, before_agent_start, tool_call, tool_result, agent_end,
session_before_compact, session_shutdown, input. Four modes: auto (DeepSeek-aware), parity,
cache-safe, notify. Attestation gate shares the v2.37 .attestation file. Four slash commands
registered (/plan-status, /plan-attest, /plan-goal, /plan-loop). 12 new contract tests.

Fixes docs/codex.md to use the canonical [features] hooks = true key (Issue #154 by @DLI1996),
with a deprecated-alias note so users on older configs keep working.

Version bumped to 2.39.0 across 14 SKILL.md variants, plugin.json, marketplace.json, CITATION.cff
via scripts/bump-version.py. .pi npm scheme bumped 1.0.1 -> 1.1.0 for the extension surface.
.continue, .gemini, .kiro lag intentionally.

Tests: 110 pass, 2 pre-existing Windows exec-bit failures unrelated to this release.
2026-05-21 21:33:16 +02:00

2.8 KiB

Pi Agent Setup

How to use planning-with-files with Pi Coding Agent.


Installation

pi install npm:pi-planning-with-files

This package now installs both:

  • Skill: planning-with-files (3-file planning workflow)
  • Extension: planning-with-files hook parity runtime

Manual Install (repo copy)

# Clone repo
git clone https://github.com/OthmanAdi/planning-with-files.git
cd planning-with-files

# Copy skill package into your Pi skills directory
mkdir -p ~/.pi/agent/skills/planning-with-files
cp -r .pi/skills/planning-with-files/* ~/.pi/agent/skills/planning-with-files/

What Pi Now Supports

Pi integration provides Claude-style lifecycle behavior via extension events:

  • Session catchup on session_start
  • Plan context reminder/injection on before_agent_start
  • Pre-tool plan recitation equivalent on tool_call
  • Post-write reminders on tool_result
  • Auto-continue guard on agent_end (limit: 3)
  • Pre-compaction reminder on session_before_compact
  • Plan attestation guard ([PLAN TAMPERED — injection blocked])

Mode System (DeepSeek-aware)

The extension supports four modes:

  • auto (default):
    • DeepSeek model -> cache-safe
    • Other models -> parity
  • parity: maximum Claude-equivalent behavior (dynamic plan injection)
  • cache-safe: stable fixed reminder for better DeepSeek KV-cache hit rate
  • notify: UI notifications only, no conversation injection

Configure via environment variable

PWF_MODE=auto pi
PWF_MODE=parity pi
PWF_MODE=cache-safe pi
PWF_MODE=notify pi

Configure via settings

Project-level (.pi/settings.json) overrides global (~/.pi/agent/settings.json):

{
  "planningWithFiles": {
    "mode": "auto"
  }
}

Commands

After installation, these extension commands are available:

  • /plan-status — show current plan counts and paths
  • /plan-attest [--show|--clear] — manage plan SHA-256 attestation
  • /plan-goal <text|default|clear> — set/clear continuation goal text
  • /plan-loop [10m] [prompt...] — periodic planning tick; use stop to cancel

Usage

Start with:

/skill:planning-with-files

Then ask Pi to create/update:

  • task_plan.md
  • findings.md
  • progress.md

For long tasks, keep task_plan.md as the source of truth and let hooks/extension events enforce the loop.


Troubleshooting

  1. Confirm package installed:
    pi list
    
  2. Reload runtime:
    /reload
    
  3. Check skill and extension paths:
    • skill: .pi/skills/planning-with-files/
    • extension: extensions/planning-with-files/index.ts
  4. If plan injection is blocked, run:
    /plan-attest --show
    
    Then re-attest intentionally changed plans:
    /plan-attest