# pi-show-cwd

A [pi](https://github.com/earendil-works/pi-mono) extension that makes the
harness's working directory a first-class thing: you can always see it, and
you can change it — without asking the LLM anything.

Two commands, rendered as neat boxed entries in the chat transcript (deterministic
UI, zero tokens spent):

- **`/show-cwd`** — prints the harness process's current working directory
  directly into the transcript.
- **`/change-cwd <dir>`** — switches the harness process's working directory
  (`process.chdir`). Supports:
  - `~` expansion (pi does no shell expansion on command args)
  - `-` to jump back to the previous directory
  - filesystem-aware argument completion: tab-complete through directories
    and files, drill with `.`/`..`, hidden entries appear when you type a
    leading `.`

Legacy aliases **`/show-pwd`** and **`/change-pwd`** are registered with the
exact same handlers, so `/pwd` muscle memory still surfaces them in the
command dropdown.

## Why this exists

The harness's cwd is the one fact that every path the agent touches is
interpreted against, yet stock pi gives you no direct way to read or move it.
This extension closes that gap with two deterministic commands — no model
round-trips, no shell indirection: what you get is exactly what
`process.cwd()` says, and `/change-cwd` is a real `process.chdir`.

## Behavior notes, stated plainly

- **Validation before the jump.** `/change-cwd` checks existence and
  directory-ness before calling `chdir`, so a bad path produces a friendly
  boxed error instead of a crash.
- **`-` is a one-deep stack.** Only the immediately previous directory is
  remembered; `/change-cwd -` with no history says so instead of guessing.
- **Empty argument shows usage** rather than silently doing nothing.
- **The important caveat, surfaced every time.** pi pins its session at
  startup: the agent's bash/read tools and `@` file completion keep
  resolving against the *startup* directory until pi restarts. Every
  successful `/change-cwd` prints this warning in the boxed entry (and as a
  notify), so the partial nature of the switch is never a surprise. Restart
  pi in the new directory for a full switch.
- **Completion mirrors the filesystem.** Directory entries come first, then
  files, capped at 30 suggestions; broken symlinks and unreadable entries
  are skipped quietly.

## Install

This package lives in pi's global extension directory, so pi discovers it
automatically on startup — no settings change, nothing to enable:

```
~/.pi/agent/extensions/pi-show-cwd/
```

To use it anywhere else: `pi install pi-show-cwd`, or try it once with
`pi -e /path/to/pi-show-cwd`.

## Files

```
index.ts       everything: path expansion/completion helpers + command
               registration and the two boxed entry renderers
package.json   pi package manifest (auto-discovered extension)
```