Utils Pi Package

A pi-native package offering /effort for setting model thinking levels, /继续 (/continue) for resuming interrupted tasks or continuing based on recommendations, /init for creating or updating scoped AGENTS.md contributor guides, multi-session directory awareness (/sessions), git worktree session switching, plus git worktree path and @ completion isolation.

Structure

text
utils/
├── index.ts              — Package-root extension entry point
├── extensions/
│   ├── continue.ts       — /continue and continuation keyword interception
│   ├── effort.ts         — /effort thinking-level menu
│   ├── init.ts           — /init repository guide generation
│   ├── sessions.ts       — /sessions directory awareness + listing tool
│   ├── worktree.ts       — git worktree add path redirect
│   ├── worktree-completion.ts — worktree-aware @ filtering
│   └── worktree-session.ts — EnterWorktree / ExitWorktree session switching
├── features/             — BDD contract
├── tests/                — Package E2E tests
└── README.md

Installation

# published
pi install npm:@fradser/pi-utils
# or from this repo: pi install /path/to/pi-packages/packages/utils

Commands

init — repository contributor guides

/init asks the active agent to inspect the repository and create or update scoped AGENTS.md files. It checks existing guides before writing, preserves useful instructions, and keeps root and nested guides aligned without needless duplication. An optional argument adds focus:

/init
/init focus on package release commands

sessions — cross-session directory awareness

/sessions lists active and recent Pi coding sessions in the current directory (cwd), including their PID, status, latest goal, and recent work.

/sessions                           # List active/recent sessions in cwd

Features:

1. Cross-Session Awareness: Multiple Pi sessions in the same project directory register their status, latest goal, and touched files in ~/.pi/agent/directory-sessions/.
2. Automated Prompt Injection: When multiple sessions run in the same directory, before_agent_start automatically injects a concise directory recap into the system prompt so each agent is aware of parallel work.
3. Dead PID Pruning: Stale or dead process IDs are automatically detected (process.kill(pid, 0)) and cleaned up from the directory registry.
4. Agent Tool (list_directory_sessions): Exposes a tool for agents to inspect active sessions in the directory programmatically.

continue — resume or continue execution

/continue (or simply typing "continue" in conversation):

/continue                           # resume from interrupted step or continue based on last suggestion
/continue Please focus on performance  # optional custom follow-up prompt

Behavior:

1. Input Interception: Intercepts plain text continue and routes it according to the last turn state.
2. Direct Recovery: For interrupted, failed, truncated, pending, or tool-error turns, starts a request from the existing conversation state without adding continue or an internal instruction as a user message. A hidden marker is removed before the provider request, along with every trailing incomplete assistant response (automatic provider retries can stack several); an assistant tool-call message always stays paired with its saved tool results.
3. Current-Configuration Retry: Failures are never re-classified into permanent refusals. After switching models or fixing configuration, the very next /continue retries on whatever model and configuration are current.
4. Suggestion Continuation: Only after a normally completed assistant turn does /continue become a visible user request, allowing the continuation instruction to remain in the transcript and model context.
5. Session Recovery and Tree Selection: Before continuing, the last persisted entry is checked against the active session index. The same session file is reloaded only when another process has appended an entry the active session has never loaded. If the user navigated to an earlier tree node, the known selected leaf remains authoritative and continuation starts there instead of resuming the abandoned failed branch.

effort — set the thinking level

/effort with no argument opens a menu of the thinking levels the current model supports (the current level is marked). With an argument it sets the level directly:

/effort          # menu
/effort max      # set directly
/effort min      # aliases: min, med, xh, none, 0

Valid levels: off, minimal, low, medium, high, xhigh, max. Unknown values are rejected with a hint listing the valid levels. The level is clamped to the model's capabilities, and the menu is narrowed to what the model actually supports (a reasoning-off model only gets off).

Git worktree redirect

A standalone, simple git worktree add bash command is rewritten so the linked worktree lives inside .pi/worktrees/<name> instead of a sibling directory:

git worktree add ../foo feature/foo
# → mkdir -p .pi/worktrees && git worktree add .pi/worktrees/foo feature/foo

The redirect preserves Git's documented worktree add options, including --lock (a flag), --reason <string>, --orphan <branch>, -b <branch>, -B <branch>, and the optional <commit-ish>. It preserves quoted and escaped path arguments, and leaves an already redirected path untouched.

For safety, it only rewrites the direct git worktree add form. Commands with shell operators, redirections, substitutions, expansions, malformed quoting, unknown options, or extra arguments are left unchanged rather than being partially rewritten.

Git worktree-aware @ completions

Editor file suggestions (@) are filtered to the session's own git worktree: a session in main never suggests linked worktree contents, and a session inside a linked worktree never suggests sibling worktrees or the main checkout. The built-in read tool also blocks direct reads from a foreign worktree and directs the agent to enter_worktree; only a replacement session rooted in that worktree may read its files. Worktree roots are discovered once per session via git worktree list --porcelain; outside a git repository nothing is filtered. Quoted and @-prefixed values are resolved (relative, absolute, and ~/ forms) before the containment check.

EnterWorktree / ExitWorktree

Pi cannot mutate the current runtime's cwd in place. These commands use Pi's session replacement API so the built-in read, edit, bash, and @ tools are all rebound to the selected worktree:

/enter-worktree feature-auth
/enter-worktree {"path":".pi/worktrees/existing"}
/exit-worktree

/enter-worktree creates a managed worktree at .pi/worktrees/<name> on a pi/worktree/<name> branch, or enters an existing registered git worktree when path is supplied. The replacement session preserves the current conversation and records the parent session. The LLM-facing enter_worktree and exit_worktree tools queue these commands and report queued until the session replacement is applied. Their TUI uses the same pi-kit lifecycle style as monitor_start: an empty tool-call row followed by one compact event row, for example [worktree] enter · feature-auth or [worktree] exit · current worktree.

/exit-worktree returns to the parent session. For worktrees created by Pi, it asks whether to keep or remove the worktree; dirty work is kept unless the user explicitly chooses forced removal. Existing worktrees are never removed by this command.

License

MIT