3 -Background Pi agent overlay for quick side-channel prompts.
7 -Loaded through the root pi-ext package.
8 -See [root README](../../README.md).
10 -##
Commands / tools / settings 14 -- `/ghost` opens the ghost overlay.
15 - If it is already open, it focuses it.
16 -- `/ghost <prompt>` opens the overlay if needed and sends `<prompt>` to the
18 - If the overlay is already open, it sends the prompt to the existing session.
19 -- `/ghost` requires interactive mode.
23 -- `alt+g` opens the ghost overlay in interactive mode.
31 -- `session_start` loads ghost config.
32 -- `session_shutdown` disposes the ghost session and clears its widget.
37 - `ghost` object in Pi agent `settings.json`
40 -- project config overrides global config field by field
41 -- invalid project JSON or non-object project config is reported as a warning and
43 -- invalid global JSON is ignored
45 -Supported config fields:
50 - `center`, `top-left`, `top-center`, `top-right`, `right-center`,
51 - `bottom-right`, `bottom-center`, `bottom-left`, `left-center`
53 - positive number or positive percent string
54 -- `overlay.maxHeight`:
55 - positive number or positive percent string
56 -- `overlay.margin.top`:
58 -- `overlay.margin.bottom`:
60 -- `overlay.margin.left`:
62 -- `overlay.margin.right`:
70 - "anchor":
"bottom-center",
73 - "margin": {
"top":
0,
"bottom":
1,
"left":
0,
"right":
0 }
80 -Ghost starts a secondary in-memory Pi agent session in the current cwd.
81 -It uses the active model unless both `model.provider` and `model.id` match a
82 -model in the registry.
83 -If the configured model is missing, it falls back to the active model.
85 -The overlay renders user messages, assistant streaming updates, and tool
86 -execution output from that secondary session.
87 -It keeps an event log so hidden overlays can reopen with current session state.
91 -- Enter submits trimmed input.
92 -- empty input is ignored.
93 -- `ctrl+s` hides the overlay and keeps the ghost session running.
94 -- `esc` closes the overlay and disposes the ghost session.
95 -- Up/down/page-up/page-down/home/end scroll transcript history.
97 -When hidden, ghost shows a small widget above the editor:
98 -`/ghost is running • run /ghost to bring it back`.
100 -Closing the overlay or Pi session shutdown cleans up the overlay, widget, event
101 -log, subscription, and ghost session.
102 -Overlay failure also cleans up that state.