ARC (Adaptive Refresh Cycle) for Pi: a safe-boundary session refresh extension that carries recent context into a fresh Pi session with a deterministic redacted handoff packet.
pi install git:github.com/12wqa/arc-piOr test a local checkout:
pi -e /path/to/arc-pi/arc # status
/arc debug # print raw ctx.getContextUsage() and ARC threshold math
/arc check # evaluate current context and refresh now if over threshold
/arc now # create a safe-boundary ARC refresh now
/arc recommend # show suggested settings for the current model
/arc 35% # set refresh threshold and show current-model recommendation
/arc threshold 35% # same as above; refreshes now if current context is already over threshold
/arc upper 20% # warn again 20% beyond the refresh threshold (default)
/arc auto # enable threshold detection/advisory at turn_end
/arc manual # disable automatic refresh; keep /arc now
/arc hydrate auto # auto-submit the packet in the new session (default)
/arc hydrate draft # draft the packet and wait for Enter instead
/arc draft # shortcut for /arc hydrate draft
/arc replenish 1200 # transcript-line budget for the handoff packet
/arc continuity 300 # si.md/tl.md line budget for the packet
/arc instructions 300 # AGENTS.md/agent.md/CLAUDE.md line budget for the packet
/arc off # disable ARC
/arc on # enable ARC
/arc practical # use practical window, default 200k tokens
/arc full # use full model context window
/arc window 200000 # set practical window
/arc recent 20 # recent clean messages to consider before line budgeting
When ARC is enabled, the Pi status line shows a compact graphical progress bar toward the next refresh threshold:
ARC A ▰▰▰▱▱▱▱▱ 14k/40k
A= automatic threshold detection enabledM= manual-only mode- filled blocks = current context progress toward the ARC refresh target
!appears when the configured threshold has been crossed!!appears when the upper/imminent limit has been crossed↻Nappears during post-refresh cooldown turns
The extension watches Pi context usage at turn_end. If the current context is over the configured threshold at that safe boundary, ARC drafts /arc-rollover threshold in the editor, writes ~/.pi/agent/arc/trigger.json, and notifies you to press Enter. If you delete that draft and keep working, ARC will not nag every turn; it escalates only after the upper limit is crossed. By default /arc upper 20% means the imminent warning happens 20% beyond the refresh threshold (for example, 35% refresh threshold -> 42% upper limit). Pi currently exposes session replacement (ctx.newSession) only to command handlers, not passive event hooks, so event-driven detection cannot directly switch sessions by itself. Explicit command paths such as /arc check, /arc now, or /arc threshold 35% can refresh immediately. The rollover then:
- waits for Pi to be idle;
- builds a deterministic restart packet from recent non-system session messages;
- redacts credential-like strings;
- writes the packet to
~/.pi/agent/arc/packets/; - starts a new Pi session with the old session recorded as parent;
- either auto-submits the ARC packet in the replacement session (
/arc hydrate auto) or places it in the editor for manual review (/arc hydrate draft).
ARC also copies optional continuity files from the current working directory before transcript content:
si.mdis for current session instructions: behavior, constraints, and fallback rules for this run.tl.mdis for current task state: a durable human-readable ledger when todo state alone is not enough or when other agents/tools need the same task context.
These files are included within the /arc continuity <lines> budget and appear before project instruction files and recent transcript in the packet. They are intentionally separate from AGENTS.md/CLAUDE.md: those files are durable project defaults, while si.md and tl.md are live continuity state for the current session/task.
ARC also copies ancestor AGENTS.md, agent.md, CLAUDE.md, and GEMINI.md-style instruction files into the packet within the /arc instructions <lines> budget. Pi should reload supported files from the new session cwd as normal; including them in the packet makes the handoff explicit.
For continuity, each packet includes previous_session_file when Pi exposes the prior session log path. The packet is intended to be authoritative for normal continuation, but it also tells the next assistant to inspect that session log before asking you to restate missing details.
This uses public Pi extension APIs rather than monkeypatching Pi internals.
Until Pi has native queued-command/session-replacement support from passive hooks, ARC includes proof-of-concept drivers that submit the drafted rollover command externally.
Run Pi in one tmux pane. In that Pi pane, get the target pane id:
tmux display-message -p '#{pane_id}'In another pane:
arc-pi/scripts/arc-driver-tmux.sh %12By default the driver watches ~/.pi/agent/arc/trigger.json and presses Enter in the target pane after ARC drafts /arc-rollover threshold. This is intentionally simple and experimental.
scripts\arc-driver.bat "pi"The Windows driver uses SendKeys, mirroring the old Claude Code proof-of-concept. Native Pi support is preferred once the concept is proven.
ARC supports two optional files in the current working directory:
Use si.md for instructions that apply to the current run, especially instructions that should survive an ARC refresh. Keep it compact and directive. Example:
# Session Instructions
Follow these unless overridden:
- Treat this file as current session policy.
- Treat tl.md or todo state as current task state.
- If unsure, inspect previous_session_file before asking the user to restate context.Use tl.md when the active task needs a durable human-readable ledger: current goals, completed work, decisions, blocked items, and next steps. This is optional when Pi todo state is enough, but useful for long-running work, cross-agent workflows, or tasks that need richer prose than a checklist.
ARC places si.md before tl.md in refresh packets so the new session sees session policy before task state. Missing files are ignored.
See docs/context-reference.md for model-family degradation notes, OpenRouter metadata fields, a data-capture schema, and the recommendation table used by /arc recommend.
npm install
npm run typecheck
npm run pack:checkARC packets exclude system prompts and redact common API-key/token/secret shapes as [REDACTED]. Redaction is a safety net, not a reason to paste real secrets into chat.
That is not the intended behavior. /arc now should switch to a new Pi session and keep the TUI open. In auto-hydrate mode it submits the packet automatically; in draft mode it places the packet in the editor. If your terminal returns to the shell, restart Pi and use /resume. Packet audit copies live under:
~/.pi/agent/arc/packets/
If it keeps happening, disable threshold detection while debugging:
/arc manual