@selesai/code 0.10.2 → 0.12.0

package/docs/sessions.md

@@ -1,145 +1,145 @@
-# Sessions
-
-Pi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
-
-## Session Storage
-
-Sessions auto-save to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
-
-```bash
-pi -c                  # Continue most recent session
-pi -r                  # Browse and select from past sessions
-pi --no-session        # Ephemeral mode; do not save
-pi --name "my task"    # Set session display name at startup
-pi --session <path|id> # Use a specific session file or partial session ID
-pi --fork <path|id>    # Fork a session file or partial session ID into a new session
-```
-
-Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
-
-For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
-
-## Session Commands
-
-| Command | Description |
-|---------|-------------|
-| `/resume` | Browse and select previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set the current session display name |
-| `/session` | Show session info |
-| `/tree` | Navigate the current session tree |
-| `/fork` | Create a new session from a previous user message |
-| `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
-| `/export [file]` | Export session to HTML |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
-
-## Resuming and Deleting Sessions
-
-`/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.
-
-In the picker you can:
-
-- search by typing
-- toggle path display with Ctrl+P
-- toggle sort mode with Ctrl+S
-- filter to named sessions with Ctrl+N
-- rename with Ctrl+R
-- delete with Ctrl+D, then confirm
-
-When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
-
-## Naming Sessions
-
-Use `/name <name>` to set a human-readable session name:
-
-```text
-/name Refactor auth module
-```
-
-Set the name at startup with `--name` or `-n`:
-
-```bash
-pi --name "Refactor auth module"
-pi --name "CI audit" -p "Review this build failure"
-```
-
-Named sessions are easier to find in `/resume` and `pi -r`.
-
-## Branching with `/tree`
-
-Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
-
-<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
-
-Example shape:
-
-```text
-├─ user: "Hello, can you help..."
-│  └─ assistant: "Of course! I can..."
-│     ├─ user: "Let's try approach A..."
-│     │  └─ assistant: "For approach A..."
-│     │     └─ user: "That worked..."  ← active
-│     └─ user: "Actually, approach B..."
-│        └─ assistant: "For approach B..."
-```
-
-### Tree Controls
-
-| Key | Action |
-|-----|--------|
-| ↑/↓ | Navigate visible entries |
-| ←/→ | Page up/down |
-| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
-| Shift+L | Set or clear a label on the selected entry |
-| Shift+T | Toggle label timestamps |
-| Enter | Select entry |
-| Escape/Ctrl+C | Cancel |
-| Ctrl+O | Cycle filter mode |
-
-Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
-
-### Selection Behavior
-
-Selecting a user or custom message:
-
-1. Moves the leaf to the selected message's parent.
-2. Places the selected message text in the editor.
-3. Lets you edit and resubmit, creating a new branch.
-
-Selecting an assistant, tool, compaction, or other non-user entry:
-
-1. Moves the leaf to that entry.
-2. Leaves the editor empty.
-3. Lets you continue from that point.
-
-Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
-
-## `/tree`, `/fork`, and `/clone`
-
-| Feature | `/tree` | `/fork` | `/clone` |
-|---------|---------|---------|----------|
-| Output | Same session file | New session file | New session file |
-| View | Full tree | User-message selector | Current active branch |
-| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
-| Summary | Optional branch summary | None | None |
-
-Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
-
-## Branch Summaries
-
-When `/tree` switches away from one branch to another, pi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
-
-When prompted, choose one of:
-
-1. no summary
-2. summarize with the default prompt
-3. summarize with custom focus instructions
-
-See [Compaction](compaction.md) for branch summarization internals and extension hooks.
-
-## Session Format
-
-Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
-
-For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).
+# Sessions
+
+Pi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
+
+## Session Storage
+
+Sessions auto-save to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
+
+```bash
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select from past sessions
+pi --no-session        # Ephemeral mode; do not save
+pi --name "my task"    # Set session display name at startup
+pi --session <path|id> # Use a specific session file or partial session ID
+pi --fork <path|id>    # Fork a session file or partial session ID into a new session
+```
+
+Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
+
+For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
+
+## Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/resume` | Browse and select previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set the current session display name |
+| `/session` | Show session info |
+| `/tree` | Navigate the current session tree |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+
+## Resuming and Deleting Sessions
+
+`/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.
+
+In the picker you can:
+
+- search by typing
+- toggle path display with Ctrl+P
+- toggle sort mode with Ctrl+S
+- filter to named sessions with Ctrl+N
+- rename with Ctrl+R
+- delete with Ctrl+D, then confirm
+
+When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
+
+## Naming Sessions
+
+Use `/name <name>` to set a human-readable session name:
+
+```text
+/name Refactor auth module
+```
+
+Set the name at startup with `--name` or `-n`:
+
+```bash
+pi --name "Refactor auth module"
+pi --name "CI audit" -p "Review this build failure"
+```
+
+Named sessions are easier to find in `/resume` and `pi -r`.
+
+## Branching with `/tree`
+
+Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
+
+<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
+
+Example shape:
+
+```text
+├─ user: "Hello, can you help..."
+│  └─ assistant: "Of course! I can..."
+│     ├─ user: "Let's try approach A..."
+│     │  └─ assistant: "For approach A..."
+│     │     └─ user: "That worked..."  ← active
+│     └─ user: "Actually, approach B..."
+│        └─ assistant: "For approach B..."
+```
+
+### Tree Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Navigate visible entries |
+| ←/→ | Page up/down |
+| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
+| Shift+L | Set or clear a label on the selected entry |
+| Shift+T | Toggle label timestamps |
+| Enter | Select entry |
+| Escape/Ctrl+C | Cancel |
+| Ctrl+O | Cycle filter mode |
+
+Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
+
+### Selection Behavior
+
+Selecting a user or custom message:
+
+1. Moves the leaf to the selected message's parent.
+2. Places the selected message text in the editor.
+3. Lets you edit and resubmit, creating a new branch.
+
+Selecting an assistant, tool, compaction, or other non-user entry:
+
+1. Moves the leaf to that entry.
+2. Leaves the editor empty.
+3. Lets you continue from that point.
+
+Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
+
+## `/tree`, `/fork`, and `/clone`
+
+| Feature | `/tree` | `/fork` | `/clone` |
+|---------|---------|---------|----------|
+| Output | Same session file | New session file | New session file |
+| View | Full tree | User-message selector | Current active branch |
+| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
+| Summary | Optional branch summary | None | None |
+
+Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
+
+## Branch Summaries
+
+When `/tree` switches away from one branch to another, pi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
+
+When prompted, choose one of:
+
+1. no summary
+2. summarize with the default prompt
+3. summarize with custom focus instructions
+
+See [Compaction](compaction.md) for branch summarization internals and extension hooks.
+
+## Session Format
+
+Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
+
+For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).

package/docs/settings.md

@@ -64,6 +64,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
 | `tuiMode` | string | `"fullscreen"` | TUI layout: `"fullscreen"` (default) or `"regular"`. `fullscreen` uses Pi's native alternate-screen viewport with a fixed dock for the input editor, status, and widgets; set `"regular"` to opt out |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"`, `"always"`, or `"hidden"`; configurable in `/settings`. No effect in regular TUI mode |
+| `fullscreenCopyOnSelect` | boolean | `true` | Automatically copy selected text in fullscreen mode; disable to copy selections with Ctrl+X. Configurable in `/settings`. No effect in regular TUI mode |
 
 ### Telemetry and update checks
 
@@ -169,6 +170,9 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
 | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
+| `terminal.images` | string | `"auto"` | Terminal image protocol: `"kitty"`, `"iterm2"`, `"auto"`, or `false` to disable inline images |
+| `terminal.trueColor` | boolean/string | `"auto"` | Pin true-color support (`true`/`false`) or keep `"auto"` detection |
+| `terminal.hyperlinks` | boolean/string | `"auto"` | Pin hyperlink support (`true`/`false`) or keep `"auto"` detection |
 | `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
 | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
 | `images.imageCaptionModel` | string | unset | Vision model (`provider/model`) to describe images when the active model cannot accept images; the caption text is used in place of the image (e.g. `tokenin/gemma-4`, `tokenin/kimi-k3`) |

package/docs/shared-host-extensions.md

@@ -1,109 +1,109 @@
-# Shared Host Extensions
-
-Selesai is a pi fork with its own config directory (`~/.selesai/agent/`). By default it only reads your extensions from there. If you already use `pi` and have extensions installed under `~/.pi/agent/extensions/`, you can let selesai reuse them without duplicating auth, sessions, models, or settings.
-
-This page covers three things:
-
-1. The shared-host fallback (how selesai reads pi's extensions).
-2. Collisions: what happens when the same extension exists in both.
-3. Picking the winner per extension via `extensionHost`.
-
-## What gets shared, and what does not
-
-| Read from `~/.pi/agent/` | Kept separate under `~/.selesai/agent/` |
-|---|---|
-| `extensions/` | `auth.json` |
-| | `models.json` |
-| | `settings.json` |
-| | `sessions/` |
-| | `skills/`, `prompts/`, `themes/` |
-
-Only **extensions** are shared from the pi host dir. Everything tied to your identity, model defaults, and settings stays in selesai's own dir. This means you can keep a single set of API keys in `~/.pi/agent/auth.json` for pi, and a different set in `~/.selesai/agent/auth.json` for selesai, while both agents load the same extension code.
-
-The host directory is hardcoded to `~/.pi/agent/extensions`. If pi ever renames its config dir, selesai will silently stop loading pi's extensions — no error, the extensions just won't appear. There is no env var to override this; the path is deliberately fixed so your two installs can't drift into loading the wrong dir.
-
-## Collisions: same extension in both dirs
-
-If an extension named `pi-subagents` exists in both `~/.selesai/agent/extensions/` and `~/.pi/agent/extensions/`, selesai does **not** load both. Loading both causes split-brain problems for stateful extensions (timers, event handlers, watchers running twice with separate `state` objects), so selesai loads exactly one copy and drops the other.
-
-The "name" used for dedup is the **top-level entry name** under the extensions dir:
-
-- A packaged extension dir (e.g. `pi-subagents/` with a `package.json`) → the dir name `pi-subagents`.
-- A loose `.ts` file (e.g. `copy-turn.ts`) → the file name `copy-turn.ts`.
-
-If you fork `pi-subagents` into a dir called `my-subagents`, the names differ and both load — no collision.
-
-### Default winner
-
-Without any config, **selesai's copy wins**. The pi copy is dropped entirely (never loaded), and a warning is printed at startup:
-
-```
-Warning: Extension "pi-subagents" exists in both ~/.selesai/agent/extensions and ~/.pi/agent/extensions; loaded the selesai copy, skipped the other. Set "extensionHost": { "pi-subagents": "pi" } or "selesai" in settings.json to change the winner.
-```
-
-## Picking the winner: `extensionHost`
-
-You control the winner per extension in `~/.selesai/agent/settings.json`:
-
-```json
-{
-  "extensionHost": {
-    "pi-subagents": "pi",
-    "copy-turn.ts": "selesai"
-  }
-}
-```
-
-| Value | Behavior |
-|---|---|
-| `"selesai"` | selesai's copy loads, pi's is dropped. |
-| `"pi"` | pi's copy loads, selesai's is dropped. |
-| (omitted) | Default applies (= selesai wins). |
-
-Typical reasons to pick `"pi"`:
-- You hack on an extension under `~/.pi/agent/extensions/` and want both agents to run your working copy.
-- pi's version is newer and you have not ported your changes into selesai yet.
-- An extension carries host-specific state (a socket path, a lockfile).
-
-Typical reasons to leave it at `"selesai"` (default):
-- You have a selesai-specific fork and want it to shadow pi's.
-- You are migrating toward selesai and are phasing pi's copy out.
-
-The setting is scoped by name, so you can mix: keep pi's `pi-subagents` but use selesai's `copy-turn.ts`.
-
-### Where to put it
-
-Global (`~/.selesai/agent/settings.json`) applies to every project. Project-local `.selesai/settings.json` (or `.pi/settings.json` inside a trusted project) overrides per project, since project settings merge on top of global. See [settings.md](settings.md) for the full merge rules.
-
-## Workflow: running pi and selesai side by side
-
-1. Keep your current install as-is:
-   ```
-   ~/.pi/agent/
-     extensions/      <- your shared extensions live here
-     auth.json
-     settings.json
-   ~/.selesai/agent/
-     extensions/      <- (optional) selesai-specific forks override the above
-     auth.json        <- separate keys, separate sessions
-     settings.json    <- add extensionHost here
-   ```
-2. If you hit a collision warning and want the other copy, add one line to `~/.selesai/agent/settings.json`:
-   ```json
-   { "extensionHost": { "pi-subagents": "pi" } }
-   ```
-3. Restart. The warning now reads that pi's copy won and selesai's was skipped.
-
-## How detection works (under the hood)
-
-- During resource resolution, selesai collects all enabled extensions from `~/.selesai/agent/extensions/`, then walks `~/.pi/agent/extensions/` for the rest.
-- For each pi-host entry, it computes the top-level entry name and checks it against the selesai set.
-- On a match, `extensionHost[name]` decides the winner; the loser is removed from the resolved set before anything loads, so no double-load of factories, no orphaned timers.
-- Each drop is recorded as a collision and surfaced as a startup warning (see [Settings](settings.md) for where diagnostics are reported).
-
-## Limitations
-
-- **Only extensions are shared.** Skills, prompts, and themes in `~/.pi/agent/skills/` etc. are never read by selesai. Copy them into `~/.selesai/agent/` if you want them.
-- **Only name collisions are deduped.** If two unrelated extensions register the same tool or command name (e.g. both define `/foo`), that conflict is handled by pi's normal first-registration-wins rule after load, not by `extensionHost`.
-- **No version check.** If selesai's `pi-subagents` is 0.2.0 and pi's is 0.4.0, `extensionHost: { "pi-subagents": "pi" }` silently loads 0.4.0. Picking the winner is purely by install location, not by version. You are responsible for matching versions when you want consistent behavior.
-- **Hardcoded host path.** If you rename pi's config dir away from `~/.pi`, selesai stops seeing it. There is no resolver hook yet.
+# Shared Host Extensions
+
+Selesai is a pi fork with its own config directory (`~/.selesai/agent/`). By default it only reads your extensions from there. If you already use `pi` and have extensions installed under `~/.pi/agent/extensions/`, you can let selesai reuse them without duplicating auth, sessions, models, or settings.
+
+This page covers three things:
+
+1. The shared-host fallback (how selesai reads pi's extensions).
+2. Collisions: what happens when the same extension exists in both.
+3. Picking the winner per extension via `extensionHost`.
+
+## What gets shared, and what does not
+
+| Read from `~/.pi/agent/` | Kept separate under `~/.selesai/agent/` |
+|---|---|
+| `extensions/` | `auth.json` |
+| | `models.json` |
+| | `settings.json` |
+| | `sessions/` |
+| | `skills/`, `prompts/`, `themes/` |
+
+Only **extensions** are shared from the pi host dir. Everything tied to your identity, model defaults, and settings stays in selesai's own dir. This means you can keep a single set of API keys in `~/.pi/agent/auth.json` for pi, and a different set in `~/.selesai/agent/auth.json` for selesai, while both agents load the same extension code.
+
+The host directory is hardcoded to `~/.pi/agent/extensions`. If pi ever renames its config dir, selesai will silently stop loading pi's extensions — no error, the extensions just won't appear. There is no env var to override this; the path is deliberately fixed so your two installs can't drift into loading the wrong dir.
+
+## Collisions: same extension in both dirs
+
+If an extension named `pi-subagents` exists in both `~/.selesai/agent/extensions/` and `~/.pi/agent/extensions/`, selesai does **not** load both. Loading both causes split-brain problems for stateful extensions (timers, event handlers, watchers running twice with separate `state` objects), so selesai loads exactly one copy and drops the other.
+
+The "name" used for dedup is the **top-level entry name** under the extensions dir:
+
+- A packaged extension dir (e.g. `pi-subagents/` with a `package.json`) → the dir name `pi-subagents`.
+- A loose `.ts` file (e.g. `copy-turn.ts`) → the file name `copy-turn.ts`.
+
+If you fork `pi-subagents` into a dir called `my-subagents`, the names differ and both load — no collision.
+
+### Default winner
+
+Without any config, **selesai's copy wins**. The pi copy is dropped entirely (never loaded), and a warning is printed at startup:
+
+```
+Warning: Extension "pi-subagents" exists in both ~/.selesai/agent/extensions and ~/.pi/agent/extensions; loaded the selesai copy, skipped the other. Set "extensionHost": { "pi-subagents": "pi" } or "selesai" in settings.json to change the winner.
+```
+
+## Picking the winner: `extensionHost`
+
+You control the winner per extension in `~/.selesai/agent/settings.json`:
+
+```json
+{
+  "extensionHost": {
+    "pi-subagents": "pi",
+    "copy-turn.ts": "selesai"
+  }
+}
+```
+
+| Value | Behavior |
+|---|---|
+| `"selesai"` | selesai's copy loads, pi's is dropped. |
+| `"pi"` | pi's copy loads, selesai's is dropped. |
+| (omitted) | Default applies (= selesai wins). |
+
+Typical reasons to pick `"pi"`:
+- You hack on an extension under `~/.pi/agent/extensions/` and want both agents to run your working copy.
+- pi's version is newer and you have not ported your changes into selesai yet.
+- An extension carries host-specific state (a socket path, a lockfile).
+
+Typical reasons to leave it at `"selesai"` (default):
+- You have a selesai-specific fork and want it to shadow pi's.
+- You are migrating toward selesai and are phasing pi's copy out.
+
+The setting is scoped by name, so you can mix: keep pi's `pi-subagents` but use selesai's `copy-turn.ts`.
+
+### Where to put it
+
+Global (`~/.selesai/agent/settings.json`) applies to every project. Project-local `.selesai/settings.json` (or `.pi/settings.json` inside a trusted project) overrides per project, since project settings merge on top of global. See [settings.md](settings.md) for the full merge rules.
+
+## Workflow: running pi and selesai side by side
+
+1. Keep your current install as-is:
+   ```
+   ~/.pi/agent/
+     extensions/      <- your shared extensions live here
+     auth.json
+     settings.json
+   ~/.selesai/agent/
+     extensions/      <- (optional) selesai-specific forks override the above
+     auth.json        <- separate keys, separate sessions
+     settings.json    <- add extensionHost here
+   ```
+2. If you hit a collision warning and want the other copy, add one line to `~/.selesai/agent/settings.json`:
+   ```json
+   { "extensionHost": { "pi-subagents": "pi" } }
+   ```
+3. Restart. The warning now reads that pi's copy won and selesai's was skipped.
+
+## How detection works (under the hood)
+
+- During resource resolution, selesai collects all enabled extensions from `~/.selesai/agent/extensions/`, then walks `~/.pi/agent/extensions/` for the rest.
+- For each pi-host entry, it computes the top-level entry name and checks it against the selesai set.
+- On a match, `extensionHost[name]` decides the winner; the loser is removed from the resolved set before anything loads, so no double-load of factories, no orphaned timers.
+- Each drop is recorded as a collision and surfaced as a startup warning (see [Settings](settings.md) for where diagnostics are reported).
+
+## Limitations
+
+- **Only extensions are shared.** Skills, prompts, and themes in `~/.pi/agent/skills/` etc. are never read by selesai. Copy them into `~/.selesai/agent/` if you want them.
+- **Only name collisions are deduped.** If two unrelated extensions register the same tool or command name (e.g. both define `/foo`), that conflict is handled by pi's normal first-registration-wins rule after load, not by `extensionHost`.
+- **No version check.** If selesai's `pi-subagents` is 0.2.0 and pi's is 0.4.0, `extensionHost: { "pi-subagents": "pi" }` silently loads 0.4.0. Picking the winner is purely by install location, not by version. You are responsible for matching versions when you want consistent behavior.
+- **Hardcoded host path.** If you rename pi's config dir away from `~/.pi`, selesai stops seeing it. There is no resolver hook yet.

package/docs/shell-aliases.md

@@ -1,13 +1,13 @@
-# Shell Aliases
-
-Pi runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
-
-To enable your shell aliases, add to `~/.pi/agent/settings.json`:
-
-```json
-{
-  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
-}
-```
-
-Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.
+# Shell Aliases
+
+Pi runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
+
+To enable your shell aliases, add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
+}
+```
+
+Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.