Session auto-rename, standing-rules re-injection, and a session launcher for pi.
Install from git:
pi install git:github.com/yusrmuttaqien/pi-context-pluginOr clone and run directly:
git clone <repo>
cd pi-context-plugin
pi --extension ./src/index.tsConfiguration lives in ~/.pi/agent/pi-context-plugin-config.json (override with PI_CONTEXT_PLUGIN_CONFIG_PATH). It is created on first load with the full default block; missing keys are filled in, existing values are preserved, and old flat/autoname/nudge-rules keys are migrated automatically. See Configuration.
Three features:
- Auto-rename — after the first settled turn (and optionally on a schedule), generates a session title in
context: latest actionformat and sets it viapi.setSessionName. The rename is an out-of-band model call that reuses the live context as a prefix-cache hit, so it's cheap on a local server. Toggle per session with/auto-rename. - Rules nudge — re-injects your standing rules at the start of the first user turn and every Nth turn, so long conversations don't drift from rules stated in the leading system prompt. Active by default; toggle per session with
/nudge. - Session launcher —
/open-sessionstarts a new session (here or in a directory you type), opens an existing session, or deletes the current session and starts fresh./close-sessioncloses pi, deleting the current session first if it has a conversation.
Pi's session handling leaves a few gaps this plugin fills:
- Sessions are nameless. Pi gives sessions auto-generated filenames. Auto-rename gives every session a
context: latest actiontitle that tracks the conversation as it moves to new topics. - No single session manager. There's no one command to start a session in a chosen directory, switch to an existing one, or delete the current one.
/open-sessionis that unified launcher, and/close-sessioncloses pi (optionally deleting the session first). - Rules fall out of attention. Rules stated in the leading system prompt lose weight as tool output accumulates over a long conversation. The rules nudge re-states them periodically, riding in the same run as the real prompt.
At a configured boundary — after the first settled turn (if autorename.runAfterFirstTurn is on) and/or every autorename.refreshTurns settled turns — the plugin fires an out-of-band rename: a separate, fire-and-forget model call that never touches the live session, so there is nothing to hide or clean up.
How the request is built:
- On each real turn, the plugin captures the entire live request body (system, tools, thinking fields,
max_tokens,stream, …) and the leaf entry id at request time — i.e. before this turn's reply. - At the boundary, it sends that captured body verbatim, swapping only the messages for the rebuilt conversation (Pi's own converter,
buildSessionContext+convertToLlm, up to that captured leaf) plus a single naming instruction. Because every other field matches the live request, the server's prefix-cache key is the same, so the shared history is a full cache hit and only the appended instruction is new input. - The request goes through Pi's model registry (
registry.streamSimple, with acompleteSimplefallback on older Pi builds) using request-time auth — the same path a real turn uses. - The model is told to reply with only
{"name": "…"}; the name is parsed (tolerating a code fence or stray prose) and set viapi.setSessionName().
The rebuild reuses the model's live context: the whole conversation is the prefix and only the trailing instruction is new input, so it's a prefix-cache hit (fully realized on a local OpenAI-compatible server with a persistent KV cache; a cache-read discount on cloud providers). The name uses the context: latest action format; when a name already exists, the model refines it rather than inventing one.
An in-flight rename is aborted by a new user message, a restart, or a model change.
/auto-renametoggles the feature per session (it flips pause/resume; no arguments). State is stored as a per-session custom entry, so it survives restarts andpi --resume, is never sent to the LLM, and is readable after compaction. While paused, the footer showsauto-rename: off; while a rename is in flight it showsauto-rename: renaming….
Best-effort: failures are silent.
Standing rules stated in the leading system prompt fall out of the model's attention as tool output accumulates. This module re-states them at the start of the first user turn (if nudge.runOnFirstMessage is on) and at the start of every Nth user turn (nudge.everyNTurns).
- On
before_agent_start— once per run, after input handling, and only for real user turns (runs started by custom messages are skipped) — the handler returns a hiddencustom_messagewith the rules text when the turn count (compaction-aware) is the first turn or a multiple of N. - The message rides in the same run as the user's real prompt: the model reads it as standing context and responds once, to the real prompt. It never gets its own response turn.
display: falsehides it from the TUI. The entry persists in the session file and participates in compaction like any other message; once compacted away, the next scheduled turn simply re-injects.
Rules text resolution (precedence order):
nudge.overrideRulesFile— a file looked up in the current working directory (a project-local override). If it exists and is non-empty, it wins. Read at injection time, so a new file is picked up without a reload; while in effect the status pill showsnudge: <filename>.nudge.rulesFile— a fixed path (a leading~expands to the home directory), read at injection time so edits apply without a reload.nudge.rulesFallback— inline rules text, used when the above are empty or unreadable.
If all three are empty, no injection happens.
/nudgetoggles the feature per session (on/off/status; no argument flips). The nudge is active by default. State is stored as a per-session custom entry (survives restarts and session switches, never sent to the LLM).
/open-session is one entry point for session operations. It picks an action, asks delete the old session? (so you know what's coming), then acts:
- New session here — new chat in the current directory (like pi's
/new). - New session in… — new chat in a directory you type (live directory autocomplete in the TUI). The session file is created there and the runtime switches via
ctx.switchSessionwithcwdOverride. - Open a session — switch to an existing session, listed grouped by working directory (current directory first, newest first). Each row shows its id + date (toggle with
i); empty sessions are dimmed. Pressdto delete a listed session inline (y/n confirm).
The actual file removal happens in the post-switch withSession callback, after the new session is live. Esc cancels the whole flow at any step (action picker, path input, list, or delete prompt) — it's never "No, keep it"; the delete prompt has an explicit "No, keep it" for that.
Empty sessions. A session is "empty" when it has no user/assistant messages. Pi only writes a file once such a message exists, but the "new in directory" flow writes a header-only file up front (so the switch can derive the cwd). Empty sessions skip the delete prompt, and a session_shutdown cleanup removes any header-only file so throwaway sessions leave no trace on disk.
Arguments: /open-session (picker) · /open-session new or /open-session here (new here) · /open-session open (open existing) · /open-session new <path> (new in <path>).
/close-session closes pi, deleting the current session first if it has a conversation. It reuses the /open-session delete logic: an empty session (no user/assistant messages) has nothing to delete, so the prompt is skipped; a session with a conversation shows the delete dialog first. Esc cancels without closing.
| Command | Subcommands / args | What each does |
|---|---|---|
/auto-rename |
(none) | toggle pause/resume |
/nudge |
on · off · status · (none) |
enable · disable · show state · toggle |
/open-session |
new/here · open · new <path> · (none) |
new here · open existing · new in dir · action picker |
/close-session |
(none) | close pi, deleting the session first if it has a conversation |
/nudge and /open-session have true subcommands (a keyword switches behavior); /auto-rename and /close-session take no args. (/compact is pi's built-in, not registered here.)
~/.pi/agent/pi-context-plugin-config.json (override with PI_CONTEXT_PLUGIN_CONFIG_PATH), created on first load. Settings are namespaced by feature. Old flat keys (autonameSystemPromptPrefix, autonameRefreshTurns) and the old autoname / nudge.rules keys are migrated into this structure automatically; the removed compaction keys are dropped.
{
"autorename": {
"runAfterFirstTurn": true,
"refreshTurns": 5,
"debug": false
},
"nudge": {
"everyNTurns": 10,
"runOnFirstMessage": true,
"preamble": "[Automatic reminder — no reply needed; just apply these standing rules to the current task.]",
"overrideRulesFile": "",
"rulesFallback": "",
"rulesFile": ""
}
}autorename.runAfterFirstTurn— rename after the first settled turn, in addition to the periodic schedule. Defaulttrue.autorename.refreshTurns— re-evaluate the session title every N settled turns.0= no periodic re-rename (only the first-turn rename, if enabled). Default5.autorename.debug— show a per-request breakdown of each rename (prefill / think / respond tokens, finish reason, wall time) as a notification. Defaultfalse.
nudge.everyNTurns— re-inject the rules at the start of every Nth user turn (turns counted from the compaction-aware branch, so the cycle continues across compactions).0(or negative) disables the periodic re-injection. Default10.nudge.runOnFirstMessage— also inject the rules on the very first user message of the session. Useful when the rules aren't already in the system prompt. Defaulttrue.nudge.preamble— text prepended to the rules in the injected message. Default is the built-in reminder preamble ([Automatic reminder — no reply needed; ...]); set""to send the rules bare.nudge.overrideRulesFile— a project-local override: if a file with this name exists in the current working directory and is non-empty, it is used as the rules (highest precedence). Looked up at injection time. Empty = disabled. Default"".nudge.rulesFile— path to a rules file (a leading~expands to the home directory), read at injection time. Takes precedence overrulesFallback. Default"".nudge.rulesFallback— inline rules text, used whenoverrideRulesFileandrulesFileare empty, missing, or unreadable. With all three empty, no injection happens. Default"".
pi-context-plugin/
├── src/
│ ├── index.ts # entry point, registers all features (order matters)
│ ├── auto-rename.ts # session auto-rename: out-of-band retitle + /auto-rename + per-session state
│ ├── provider-call.ts # shared wire helpers: wireApi / modelKey / requestHeaders / cached-token extraction
│ ├── rules-nudge.ts # periodic re-injection of standing rules (before_agent_start)
│ ├── open-session/ # /open-session + /close-session: session launcher (new here / new in dir / open existing / delete+new / close)
│ │ ├── index.ts # re-exports the commands + empty-session cleanup
│ │ ├── command.ts # /open-session + /close-session commands + session_shutdown cleanup
│ │ ├── pickers.ts # action / path / session / delete pickers
│ │ ├── scan.ts # session scanning, grouping, date formatting, last-reply preview + label
│ │ └── ui.ts # GroupedList, Panel, WithHeader
│ ├── prompts.ts # prompt builders (rename instruction + rules reminder preamble)
│ ├── settings.ts # config: autorename + nudge namespaces, migration, scaffolding
│ └── status.ts # footer status pills (themed setStatus) + guarded notify
├── package.json
└── README.md