pi-switch-cwd

English | 简体中文

pi extension: /cwd — switch the session working directory (the session file moves with it).

Why

When you discuss/research in a large working directory and then move into an engineering directory to implement — without switching sessions: every bash round would otherwise need cd $CWD, which costs context tokens.

After /cwd, the bash/read/write tools, AGENTS.md context, and skills all point at the new directory automatically — "pwd" just works in the project directory.

Usage

/cwd                show the current cwd
/cwd <path>         switch to <path> (relative to the current cwd; ~ expands to $HOME;
                    missing directories are created with mkdir -p)

• Tab completion: directories only; dot-directories are hidden by default (shown when the input starts with .)
• Target == current cwd → no-op; path is a file → error
• Waits for the agent to be idle before switching (stops mid-stream first)

How it works

pi has no "change cwd in place" API — tools, context, and skills are cwd-bound services that are only rebuilt when the session runtime is replaced. So /cwd relocates the session:

1. Serialize the session from memory (header cwd field rewritten; id/entries preserved)
2. Write it to the target cwd's session directory (~/.pi/agent/sessions/--<encoded path>--/)
3. switchSession swaps the runtime (services for the new cwd rebuild automatically)
4. Delete the old session file on success

Same session identity (id unchanged, full history); switching back and forth accumulates nothing; if another extension vetoes the switch, the old file is kept untouched. Side effect: the session appears in /resume only under the directory it currently lives in.

Long sessions and prompt-prefix caching

/cwd preserves the conversation, but it does not preserve an identical provider prompt prefix. This distinction matters in a long-running session that relies on prompt caching.

Boundary	Behavior
While /cwd runs	No model request is made, so the command itself has no cache-read or token cost.
Session state	Session id, conversation entries, branches, and compaction state are preserved. Nothing is removed from the model's logical context.
First model request after the switch	Pi rebuilds cwd-bound runtime services. The system prompt always contains a different Current working directory; project context files, skills, settings, extensions, active tools, or tool schemas may differ too. The serialized prompt therefore diverges before the preserved conversation history.
Cache-miss scope	Provider-dependent. A provider may reuse the common prefix before the first changed token, but the conversation history after that divergence generally cannot be reused as the same cached prefix for this request. Expect a cold or mixed-cache turn, not context loss.
Later requests in the new cwd	The new prompt prefix can warm and receive normal cache hits again. Usually only the first model turn after a stable switch pays the transition cost.
Switching back	The old prefix may hit only if its provider cache entry is still alive, project resources and tool schemas are unchanged, and routing/session affinity reaches that cache. This is an optimization, not a guarantee.
Provider without prompt caching	There is no cache-hit penalty to observe; the rebuilt system prompt and project resources still change model behavior.

Keeping the same session id, cache key, or session-affinity value does not bypass content-prefix matching. Those values can route a request to a cache, but the prompt content must still satisfy the provider's matching rules.

For long sessions:

• Prefer one-way phase transitions such as research directory → implementation repository; avoid repeatedly switching between projects when cache latency or input cost matters.
• If the retained conversation is very large and the switch is a durable phase boundary, consider /compact before /cwd so the first uncached request in the new cwd is smaller.
• Use absolute paths instead of /cwd for brief cross-directory operations when retaining the current prefix is more important than loading the target project's context, skills, settings, extensions, and cwd-bound tools.

Install

pi install npm:@yceachan/pi-switch-cwd

Development

bun install                 # dev dependencies
bunx tsc                    # typecheck
bun cwd-utils.test.ts       # pure-function unit tests
./e2e-test.sh               # real e2e (tmux + real pi, needs a configured default model)

License

MIT