Pi Session Continuity

Keep long-running Pi coding sessions moving without losing the plot.

Pi Session Continuity exists so extended agentic coding work can survive the boring failure modes: a context window fills up, a session reloads, a compaction happens, or the next agent has to recover the state of the task. Its job is not to be clever, visible, or exciting. Its job is to be dull enough that you forget it is there — until the moment it quietly gives the next session a reliable handoff.

Only after that intent is clear does the mechanism matter: Pi Session Continuity is a Pi package that intercepts Pi's native compaction, writes a structured Continuity Brief to disk first, and supplies that exact disk artifact as the compacted summary. Post-compaction work therefore starts with durable continuity already in context.

Why this exists

Long-running agentic coding work often fails at the worst possible boundary: the session is full, the model is tired, the transcript is noisy, and the next prompt has to reconstruct what matters. A normal compaction can reduce tokens, but compaction is still an in-session memory-management step. If the handoff itself fails, or if a reload happens at the wrong time, the recovery story can become ambiguous.

Pi Session Continuity turns that risky boundary into a small, repeatable reliability step:

1. let Pi native compaction decide when and how much context to compact;
2. intercept session_before_compact;
3. synthesize, validate, atomically write, and re-read the Continuity Brief;
4. cancel compaction if the Brief is not safe;
5. use the exact disk Brief as Pi's custom compaction summary;
6. after session_compact, submit a visible continuation when appropriate.

Core invariant:

Durable Continuity Brief first.
Native compaction uses that exact disk artifact as its summary.
Post-compaction continuation already has the Brief in context.

Why this approach is better for continuous coding

Pi Session Continuity is not trying to be magical or invisible. It is intentionally explicit:

• Recoverable: the important state is in a local Markdown artifact that can be inspected, archived, copied, or used by a future Pi session.
• Auditable: every handoff records task, done criteria, constraints, files, validation evidence, open questions, and next actions in a stable structure.
• Safer than memory-only continuation: the resume prompt is generated from the artifact on disk, so continuity does not depend on the agent remembering what it meant to say.
• Native-compaction guard: Pi owns trigger/cut-point mechanics; the extension guarantees that the summary is an exact projection of the durable disk artifact.
• Good for unattended work: if a long task reaches a context threshold, the package can create a visible handoff instead of silently drifting or truncating the useful state.

The result is a conservative infrastructure layer for extended Pi sessions: less clever, more durable, and easier to debug.

Installation

Recommended install from npm:

pi install npm:[email protected]

The v0.2.x release line is npm-first. Do not use a GitHub v0.2.x install command until a matching tag exists and its pinned-ref smoke has passed.

For local development only:

pi -e /path/to/pi-session-continuity

Do not install from sources you do not trust. Pi packages execute with local user permissions.

Quick start

/continuity
/continuity status
/continuity checkpoint

/continuity opens the settings/config menu in interactive Pi TUI sessions. /continuity settings can derive fixed native token values from approximate percentages for the current model and write the project Pi settings after confirmation. Restart Pi to activate them. /continuity checkpoint remains save-only.

Commands

• /continuity — opens the same settings/config menu as /continuity settings in interactive Pi TUI sessions.
• /continuity status — shows native reserveTokens/keepRecentTokens, the active model window, derived effective percentages, restart state, synthesis settings, artifacts, and failures.
• /continuity checkpoint — saves a schema-v2 Continuity Brief as pending. It does not compact or submit a continuation.
• /continuity settings — edits extension settings and provides an explicitly confirmed native-compaction setup wizard. Approximate percentages are converted once to fixed token values; a full Pi restart is required. Non-interactive mode is read-only.

Configuration

Project-local config is read only when the project is trusted:

<workspace>/<CONFIG_DIR_NAME>/session-continuity.json

CONFIG_DIR_NAME is supplied by Pi and is normally .pi.

Defaults:

{
  "enabled": true,
  "synthesisModel": "inherit",
  "synthesisEffort": "medium",
  "artifactDirectory": "session-continuity"
}

synthesisEffort accepts inherit, minimal, low, medium, high, or xhigh. artifactDirectory resolves under <workspace>/<CONFIG_DIR_NAME>/ unless absolute. Upgrade note: legacy triggerAtPercent/keepRecentPercent fields are rejected rather than silently migrated because the extension no longer runs a competing trigger. Remove them, run /continuity settings, confirm native token values, and restart Pi.

In interactive Pi sessions, /continuity settings updates these extension fields and separately configures native Pi compaction. Non-interactive mode is read-only.

Native Pi compaction

Native Pi compaction is required and is the runtime source of truth:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 93000,
    "keepRecentTokens": 55800
  }
}

Pi triggers when:

contextTokens > contextWindow - reserveTokens

/continuity settings may ask for 75%/15% against a 372k current model, preview reserveTokens: 93000 and keepRecentTokens: 55800, then merge those fixed values into project .pi/settings.json after confirmation. Percentages are not persisted as policy. Until full restart, status continues to label the startup snapshot as live and shows the newly written values separately as pending restart. If the model later changes, tokens stay fixed and status recalculates only the displayed percentages.

Artifact layout

<artifactDirectory>/<sessionId>/pending/<eventId>.md
<artifactDirectory>/<sessionId>/archive/<timestamp>-<eventId>.md
<artifactDirectory>/<sessionId>/failed/<timestamp>-<eventId>.md

Artifacts from other sessions are inert. Same-session stale pending artifacts after reload are reported but not injected automatically.

Successful handoffs are archived only after a matching session_compact confirms the custom summary, event, path, and SHA-256 hash. The newest 10 archived Briefs are retained per session.

Privacy and security

Continuity Briefs are local files that may contain prompts, tool output, file paths, command results, and sensitive project context. v0.2.0 does not guarantee secret redaction. Choose artifact directories and ignore rules accordingly.

This package must not push, publish, create repositories, upload artifacts, or mutate external systems.

Manual smoke and release validation

Local package gates:

npm test
npm run typecheck
npm run smoke:manual
npm pack --dry-run

npm run smoke:manual prints a checklist template for the required clean Pi smoke assertions. For v0.2.0 npm publication, validate the exact packed artifact and record real threshold, overflow, and manual-compaction lifecycle evidence. A GitHub installation must additionally pass smoke from its pinned ref.

External validation commands such as npm publishing, git tags, releases, or uploads require separate explicit human approval.

Known limitations in v0.2.0

• Local Pi sessions only.
• Native token settings require a full Pi restart after setup.
• Tokens remain fixed when the active model/window changes; percentages shown by status are derived presentation only.
• The visible continuation message is not guaranteed to be the first queued message. Continuity remains safe because the exact Brief is already the compacted context.
• Only one custom-compaction summary handler should be loaded. If another extension replaces this extension's hook result, Pi Session Continuity refuses continuation, clears its in-memory gate, and leaves its pending Brief inert.
• No user-facing cleanup command, cross-machine sync, or cloud storage.
• GitHub clean-install smoke is required before public announcement.

Troubleshooting

• Invalid config: fix the JSON at the reported path; automatic behavior stays disabled until corrected.
• Synthesis/write/re-read failure: native compaction is cancelled; inspect the failed artifact path if one was written.
• Stale pending artifact: /continuity status reports it as inert and never silently compacts or injects it.
• Native compaction refused: run /continuity settings, apply valid fixed token values for the current model, and restart Pi.
• Model/window changed: tokens remain fixed; inspect the newly derived percentages and rerun setup only if the resulting policy is undesirable or structurally invalid.
• Untrusted project: trust the project before relying on project-local config or automatic behavior.

Update / uninstall

pi update --extension npm:pi-session-continuity
pi remove npm:pi-session-continuity

# For a future pinned GitHub v0.2.0 install after its tag is validated:
pi update --extension git:github.com/bernardofortes/[email protected]
pi remove git:github.com/bernardofortes/pi-session-continuity

Removing the package stops loading the extension. Existing local artifacts remain on disk unless you remove them manually.

Compatibility

Validated against Pi CLI/package APIs from @earendil-works/pi-coding-agent 0.80.6, Node.js 22, and Linux. Record exact Pi version, OS, install command, and smoke transcript before tagging a public release.