pivi makes Pi feel native inside Neovim rather than embedding Pi's terminal interface.
Pi remains a fully empowered coding agent.
Neovim supplies editing, navigation, presentation, and live editor context.
Live access to core Neovim state and unrestricted Neovim Lua execution.
A bundled Pi companion extension loaded in addition to the user's normal Pi configuration.
Initial editor tools focus on buffers, selections, windows, tabs, marks, jumps, changes, lists, diagnostics, commands, and Lua execution.
LSP-specific tools are outside the initial scope.
Session behavior
A Pi session is an explicit task identity with persistent history.
Each session captures a working directory as its execution scope.
Multiple sessions may share one working directory.
A tab may select a default session but does not own its lifetime.
Source buffers do not own sessions.
Closing a session window hides presentation without deleting history or implicitly stopping Pi.
A session can be resumed: the most recent session for the working directory by default, or an earlier session chosen by identity.
Resuming attaches to persistent history without starting a new conversation and without a model call.
Prior sessions for the working directory are listable so one can be chosen to resume.
The client can restart: pivi reloads itself while a working session is resumed by identity, losing neither its history nor its place.
While a session run is active, a submission is delivered as steering or as a follow-up, by a distinct and announced choice, and is never silently dropped.
Accepting the prompt while the agent is working steers the active run, the way Pi does; a separate, announced key queues a follow-up.
Steering reaches the active run; a follow-up is queued, and queued follow-ups remain listable and clearable before delivery.
Resuming a session is worthless if the conversation it resumes is invisible, so a resumed session shows the document it already is.
Resuming rebuilds the transcript from the session's recorded history as addressable entries, with messages rendered and tool calls paired with their results.
A restored entry is navigable, collapsible, and inspectable exactly like a live one; restoration is presentation and never alters recorded history.
A restored tool entry whose recorded result carries no change detail degrades to its subject and result text rather than a fabricated diff.
Restoration performs the history reads it needs but no model call, and a large history stays responsive as it renders.
pivi restores its own sessions; it never owns the editor's session persistence. Coupling to a native Neovim session workflow stays weak.
pivi publishes a serializable descriptor of its live sessions for a working directory, and an idempotent restore entry point.
A consumer captures the descriptor when it saves its own editor session and invokes restore after loading it; pivi registers no editor session-load hook and imposes no global mapping.
Restore resumes the described sessions and rebuilds their transcripts; a missing descriptor or an absent session degrades quietly to no restoration.
stateDiagram-v2
[*] --> Absent
Absent --> Resuming: resume last in cwd or chosen session
Absent --> Resuming: consumer restore from descriptor
Resuming --> Restored: history rebuilt as entries
Restored --> Restored: restart reloads client, resumes by identity
Restored --> [*]: stop session
Slash commands
Pi slash commands are available through :Pi command ....
Only commands Pi exposes to non-interactive clients are offered; terminal-only commands are absent.
In a Pi input buffer, / invokes slash-command entry only when the cursor is at the first character.
Elsewhere, / retains ordinary Neovim behavior.
One-shot help
:Pi help answers a fast question about Neovim, pivi, or Pi.
Help runs as an independent ephemeral agent run with no persisted session and no shared history.
Help never enters a working session's transcript, queue, or status.
Help stays available while a working session runs, and neither delays nor interrupts it.
Help failure is isolated and never degrades a working session.
Help may read, and never modifies the editor, the filesystem, or Pi state.
Each question carries what the user can currently see rather than whole buffers.
Editor documentation is answered from the running instance, so the version and installed plugins decide the answer.
pivi's own behavior is supplied as knowledge to the agent rather than assumed.
flowchart LR
editor["Neovim"] --> session["Working session run"]
editor --> help["Ephemeral help run"]
session --> history["Persistent session history"]
help --> discard["Discarded after answer"]
help --> readonly["Read-only editor and documentation lookups"]
Editor context
Each submission may carry an immutable snapshot of its originating buffer, path, revision, cursor, range, selection kind, selected text, and bounded surrounding text.
Queued submissions retain their own snapshots.
Pi can obtain fresh ambient editor state before later model calls.
Full buffer contents are fetched on demand rather than attaching every open buffer automatically.
Loaded buffers, including unsaved contents, are authoritative for editor-aware reads.
The Pi prompt receives a short stable orientation to the live Neovim environment without replacing existing system or project instructions.
Editing
Pi may edit without an approval gate.
Reads, edits, and writes preserve the behavior and improvements of Pi's upstream tools while making loaded Neovim buffers authoritative.
Agent changes to loaded buffers appear directly in Neovim, remain undoable, and become visible to filesystem-based commands without requiring manual reload.
Unloaded paths retain normal Pi filesystem behavior.
Validated edit intent may appear progressively as ghost text while tool arguments stream.
Real buffer mutation begins only after complete valid edit arguments exist.
An edit operation presents one coherent undoable change where Neovim permits it.
pivi uses no filesystem watchers.
Arbitrary shell or third-party tool mutations without identified paths are not represented as precise editor edits.
Transcript presentation
A transcript is the conversation itself, presented as the document it already is.
Transcript text is the messages as authored; pivi's own framing is presentation rather than content.
Copying transcript text yields the original message text, without framing.
Message formatting is rendered rather than shown as markup, and embedded code is presented in its own language.
Rendering degrades to plain readable text when a format cannot be rendered.
Presentation never performs Pi RPC, and streaming stays responsive as a transcript grows.
Transcript navigation
Every transcript entry is an addressable unit: a submission, an answer, a tool call, a tool result, or an error.
An entry can be collapsed to a single readable line or expanded to its full content.
Voluminous entries, such as tool results, start collapsed.
The user can move between entries, and between tool calls, with ordinary motions.
An entry that names a location is navigable to that location.
An entry can be inspected in detail without leaving the transcript.
Entry state is presentation only and never alters session history.
A tool call is work the user did not watch happen, so the transcript has to account for it, the way Pi's own interface does, without turning the log into noise.
The transcript stays a lean log and the detail is summoned, not spilled.
A tool is one headline while collapsed: a tool-coloured gutter indicator, the tool, what it acted on, and how it ended.
An entry expands in place to its detail and collapses back; voluminous detail starts collapsed and an outcome stays legible either way.
Expanded detail reads as the tool's own content set apart from the conversation, not as more message text.
The focused entry is distinguished from the rest.
A tool that reports nothing about its own work degrades to its subject and indicator, never to a guess.
Each tool is presented as what it actually reports.
A completed edit shows its change as a diff with added and removed lines distinguished, and that change opens as a full editor comparison on request; navigating from the edit reaches its first changed line.
A shell tool shows its output as it arrives, in the language it came from when known, and a truncated result says so while its full output stays reachable.
A search tool groups its matches by file with the matched text distinguished, and its cross-file findings reach a quickfix list.
A file read shows a syntax-aware preview that leads to the file itself.
A failed tool shows a single red outcome and no body.
Full detail that does not belong inline is a dedicated detail surface, distinct from the transcript and dismissible, never overwriting the user's working window.
stateDiagram-v2
[*] --> Collapsed: tool call
Collapsed --> Collapsed: output arrives, outcome updates
Collapsed --> Expanded: expand
Expanded --> Collapsed: collapse
Expanded --> Detail: open comparison or full output
Collapsed --> Detail: open comparison or full output
Detail --> Expanded: dismiss
Detail --> Collapsed: dismiss
Agent activity
Active edits may use signs, line highlights, extmarks, virtual text, or virtual lines.
Completed edits leave a navigable changed-line trail until cleared by defined editor activity or session action.
Activity belongs to its Pi session and does not overwrite unrelated diagnostic or extmark namespaces.
File and range references are navigable through normal Neovim motions and lists.
Cross-file findings use quickfix lists.
Window-associated findings use location lists.
AI diagnostics remain distinguishable from compiler and language-server diagnostics.
Follow-agent mode
Follow mode is optional and disabled unless selected by the user.
It follows location-bearing reads, edits, findings, and explicit navigation rather than every event.
It can follow in a dedicated window, a dedicated tab, or the current window.
Dedicated-window following preserves the user's working window.
Passive following avoids unnecessary jumplist pollution.
The user can return to the location held before following began.
Pi compatibility
The companion extension is shipped with pivi and injected additively when Pi starts.
User, project, package, provider, skill, prompt, and tool configuration continues to load under Pi's normal rules.
pivi does not silently alter Pi project trust or restrict available tools.
TUI-only renderers, custom components, keybindings, headers, footers, and terminal input are not emulated.
Supported extension dialogs and status requests map to native Neovim surfaces.
Unrestricted Neovim Lua execution is available alongside structured convenience tools.
Native integration invariant
pivi is an optional producer of native Neovim state, never the owner of surrounding configuration.
It does not replace or require a statusline, winbar, tabline, picker, notification system, layout, or keymap framework.
It publishes cached state through native variables and semantic User events.
It offers commands and <Plug> mappings without imposing global mappings.
Consumers can degrade to ordinary Neovim behavior when pivi is absent.
Loading pivi succeeds when the Pi executable is unavailable; starting Pi reports the missing capability.
Status consumers never perform Pi RPC during statusline evaluation.
Transport and status
Pi RPC uses a non-terminal JSONL subprocess channel.
Terminal dimensions, alternate screens, cursor escapes, and terminal key forwarding are not part of pivi.
Standard error remains separate from protocol output.
ANSI styling in payload text is stripped or translated before native presentation.
Semantic session status includes connection, queue, run, tool, waiting, compaction, retry, abort, and error states.
Status also exposes available model, thinking, session, context, usage, and extension-status data.
Status changes redraw native status surfaces and emit a semantic event.
Acceptance criteria
A Pi slash command can run through :Pi command ...; / invokes slash-command entry only at the first character of a Pi input buffer.
A transcript renders message formatting, presents embedded code in its own language, and still yields the original text when copied.
A collapsed tool entry is one line carrying a tool-coloured indicator, the subject, and the outcome; the focused entry is visibly distinguished.
A tool entry expands its detail in place and collapses back, and the detail is set apart from conversation text.
A completed edit shows added and removed lines distinctly, opens as an editor comparison on a dedicated surface that preserves the working window, and navigating from it lands on its first changed line.
Output of a long-running tool appears progressively rather than only at completion, and a truncated result is marked and its full output stays reachable.
A search tool groups matches by file with the matched text distinguished and sends cross-file findings to a quickfix list.
A file read presents a syntax-aware preview that leads to the file.
A failed tool shows a single outcome line and no body.
A tool result is collapsed on arrival, expands on request, and collapsing never changes session history.
A user can move between transcript entries with ordinary motions and reach the location an entry names.
Transcript presentation performs no Pi RPC, and a long streamed answer stays responsive.
:Pi help answers while a working session run is active, without appearing in that session's history, queue, or status.
A help question carries the visible editor region, layout, selection, recent messages, and the last error, and no full buffer.
Help can answer an editor documentation question from the running instance, including documentation of installed plugins.
No help run can modify a buffer, a file, or Pi state.
A submission made during an active run is delivered as steering or a follow-up by a distinct, announced choice, and is never silently dropped.
Accepting the prompt while the agent is working steers the run; a separate announced key queues a follow-up.
A queued follow-up can be listed and cleared before delivery.
A user can create, resume, switch, and stop explicit Pi sessions without tying their lifetime to a source buffer or tab.
Resuming with no target resumes the most recent session for the working directory; a specific session resumes by identity; neither starts a new conversation nor calls the model.
Prior sessions for the working directory can be listed and one chosen to resume.
Resuming rebuilds the transcript as addressable entries with rendered messages and tool calls paired to their results, and the rebuild performs no model call.
A restored tool entry whose recorded result carries no change detail shows its subject and result text rather than a fabricated diff.
Restarting reloads the pivi client and resumes the active session by identity with its history and place intact.
pivi publishes a serializable per-working-directory session descriptor and an idempotent restore entry point, registers no editor session-load hook, and imposes no global mapping, so a native-session workflow can capture and restore pivi without pivi owning session persistence.
Restoring from a missing descriptor or an absent session degrades quietly to no restoration.
A prompt can include an unsaved selection with stable source and revision metadata.
Pi can read unsaved loaded-buffer content and use current core Neovim context on demand.
Pi can execute arbitrary Neovim Lua and use structured editor operations.
A normal Pi edit to a loaded buffer appears without reload, is undoable, remains coherent with subsequent shell work, and receives visible activity markers.
Streaming edit arguments can produce non-mutating ghost presentation; incomplete arguments never mutate the real buffer.
Follow mode can track an agent edit in a dedicated viewport without taking over the user's working window.
Quickfix, location-list, diagnostic, and file navigation use normal Neovim behavior.
Existing Pi extensions and tools continue to run except for capabilities inherently specific to Pi's TUI.
A custom Neovim configuration can consume pivi state and events without requiring pivi to be installed or loaded.
pivi does not modify user-owned statuslines, winbars, tablines, global mappings, or picker configuration.
No filesystem watcher is started.
---
id: NVIM-SPEC-GMWDCMJZ
type: spec
title: pivi Native Neovim Integration
research:
- NVIM-RESEARCH-KZYYEFY_
- NVIM-RESEARCH-NOSZ7JUQ
- NVIM-RESEARCH-T3BL4TK4
---
# pivi Native Neovim Integration
## Intent
pivi makes Pi feel native inside Neovim rather than embedding Pi's terminal interface.
Pi remains a fully empowered coding agent.
Neovim supplies editing, navigation, presentation, and live editor context.
[Accepted native edit and follow-mode mockup](./native-agent-trail.html)
## Scope
pivi provides:
- Persistent Pi sessions controlled through Pi RPC.
- Neovim buffers for prompts, transcripts, session navigation, and detailed output.
- Native quickfix lists, location lists, diagnostics, extmarks, signs, diffs, and navigation.
- Live access to core Neovim state and unrestricted Neovim Lua execution.
- A bundled Pi companion extension loaded in addition to the user's normal Pi configuration.
Initial editor tools focus on buffers, selections, windows, tabs, marks, jumps, changes, lists, diagnostics, commands, and Lua execution.
LSP-specific tools are outside the initial scope.
## Session behavior
- A Pi session is an explicit task identity with persistent history.
- Each session captures a working directory as its execution scope.
- Multiple sessions may share one working directory.
- A tab may select a default session but does not own its lifetime.
- Source buffers do not own sessions.
- Closing a session window hides presentation without deleting history or implicitly stopping Pi.
- A session can be resumed: the most recent session for the working directory by default, or an earlier session chosen by identity.
- Resuming attaches to persistent history without starting a new conversation and without a model call.
- Prior sessions for the working directory are listable so one can be chosen to resume.
- The client can restart: pivi reloads itself while a working session is resumed by identity, losing neither its history nor its place.
- While a session run is active, a submission is delivered as steering or as a follow-up, by a distinct and announced choice, and is never silently dropped.
- Accepting the prompt while the agent is working steers the active run, the way Pi does; a separate, announced key queues a follow-up.
- Steering reaches the active run; a follow-up is queued, and queued follow-ups remain listable and clearable before delivery.
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Running: submit
Running --> Running: steer, or queue follow-up
Running --> Idle: settle
Running --> Idle: abort
Idle --> [*]: stop session
```
## Session restoration
Resuming a session is worthless if the conversation it resumes is invisible, so a resumed session shows the document it already is.
- Resuming rebuilds the transcript from the session's recorded history as addressable entries, with messages rendered and tool calls paired with their results.
- A restored entry is navigable, collapsible, and inspectable exactly like a live one; restoration is presentation and never alters recorded history.
- A restored tool entry whose recorded result carries no change detail degrades to its subject and result text rather than a fabricated diff.
- Restoration performs the history reads it needs but no model call, and a large history stays responsive as it renders.
pivi restores its own sessions; it never owns the editor's session persistence. Coupling to a native Neovim session workflow stays weak.
- pivi publishes a serializable descriptor of its live sessions for a working directory, and an idempotent restore entry point.
- A consumer captures the descriptor when it saves its own editor session and invokes restore after loading it; pivi registers no editor session-load hook and imposes no global mapping.
- Restore resumes the described sessions and rebuilds their transcripts; a missing descriptor or an absent session degrades quietly to no restoration.
```mermaid
stateDiagram-v2
[*] --> Absent
Absent --> Resuming: resume last in cwd or chosen session
Absent --> Resuming: consumer restore from descriptor
Resuming --> Restored: history rebuilt as entries
Restored --> Restored: restart reloads client, resumes by identity
Restored --> [*]: stop session
```
## Slash commands
- Pi slash commands are available through `:Pi command ...`.
- Only commands Pi exposes to non-interactive clients are offered; terminal-only commands are absent.
- In a Pi input buffer, `/` invokes slash-command entry only when the cursor is at the first character.
- Elsewhere, `/` retains ordinary Neovim behavior.
## One-shot help
- `:Pi help` answers a fast question about Neovim, pivi, or Pi.
- Help runs as an independent ephemeral agent run with no persisted session and no shared history.
- Help never enters a working session's transcript, queue, or status.
- Help stays available while a working session runs, and neither delays nor interrupts it.
- Help failure is isolated and never degrades a working session.
- Help may read, and never modifies the editor, the filesystem, or Pi state.
- Each question carries what the user can currently see rather than whole buffers.
- Editor documentation is answered from the running instance, so the version and installed plugins decide the answer.
- pivi's own behavior is supplied as knowledge to the agent rather than assumed.
```mermaid
flowchart LR
editor["Neovim"] --> session["Working session run"]
editor --> help["Ephemeral help run"]
session --> history["Persistent session history"]
help --> discard["Discarded after answer"]
help --> readonly["Read-only editor and documentation lookups"]
```
## Editor context
- Each submission may carry an immutable snapshot of its originating buffer, path, revision, cursor, range, selection kind, selected text, and bounded surrounding text.
- Queued submissions retain their own snapshots.
- Pi can obtain fresh ambient editor state before later model calls.
- Full buffer contents are fetched on demand rather than attaching every open buffer automatically.
- Loaded buffers, including unsaved contents, are authoritative for editor-aware reads.
- The Pi prompt receives a short stable orientation to the live Neovim environment without replacing existing system or project instructions.
## Editing
- Pi may edit without an approval gate.
- Reads, edits, and writes preserve the behavior and improvements of Pi's upstream tools while making loaded Neovim buffers authoritative.
- Agent changes to loaded buffers appear directly in Neovim, remain undoable, and become visible to filesystem-based commands without requiring manual reload.
- Unloaded paths retain normal Pi filesystem behavior.
- Validated edit intent may appear progressively as ghost text while tool arguments stream.
- Real buffer mutation begins only after complete valid edit arguments exist.
- An edit operation presents one coherent undoable change where Neovim permits it.
- pivi uses no filesystem watchers.
- Arbitrary shell or third-party tool mutations without identified paths are not represented as precise editor edits.
## Transcript presentation
A transcript is the conversation itself, presented as the document it already is.
- Transcript text is the messages as authored; pivi's own framing is presentation rather than content.
- Copying transcript text yields the original message text, without framing.
- Message formatting is rendered rather than shown as markup, and embedded code is presented in its own language.
- Rendering degrades to plain readable text when a format cannot be rendered.
- Presentation never performs Pi RPC, and streaming stays responsive as a transcript grows.
## Transcript navigation
Every transcript entry is an addressable unit: a submission, an answer, a tool call, a tool result, or an error.
- An entry can be collapsed to a single readable line or expanded to its full content.
- Voluminous entries, such as tool results, start collapsed.
- The user can move between entries, and between tool calls, with ordinary motions.
- An entry that names a location is navigable to that location.
- An entry can be inspected in detail without leaving the transcript.
- Entry state is presentation only and never alters session history.
```mermaid
stateDiagram-v2
[*] --> Collapsed: entry appended
Collapsed --> Expanded: expand
Expanded --> Collapsed: collapse
Expanded --> Located: follow reference
Located --> Expanded: return
```
## Tool presentation
A tool call is work the user did not watch happen, so the transcript has to account for it, the way Pi's own interface does, without turning the log into noise.
[Accepted tool presentation mockup](./tool-presentation.html)
The transcript stays a lean log and the detail is summoned, not spilled.
- A tool is one headline while collapsed: a tool-coloured gutter indicator, the tool, what it acted on, and how it ended.
- An entry expands in place to its detail and collapses back; voluminous detail starts collapsed and an outcome stays legible either way.
- Expanded detail reads as the tool's own content set apart from the conversation, not as more message text.
- The focused entry is distinguished from the rest.
- A tool that reports nothing about its own work degrades to its subject and indicator, never to a guess.
Each tool is presented as what it actually reports.
- A completed edit shows its change as a diff with added and removed lines distinguished, and that change opens as a full editor comparison on request; navigating from the edit reaches its first changed line.
- A shell tool shows its output as it arrives, in the language it came from when known, and a truncated result says so while its full output stays reachable.
- A search tool groups its matches by file with the matched text distinguished, and its cross-file findings reach a quickfix list.
- A file read shows a syntax-aware preview that leads to the file itself.
- A failed tool shows a single red outcome and no body.
Full detail that does not belong inline is a dedicated detail surface, distinct from the transcript and dismissible, never overwriting the user's working window.
```mermaid
stateDiagram-v2
[*] --> Collapsed: tool call
Collapsed --> Collapsed: output arrives, outcome updates
Collapsed --> Expanded: expand
Expanded --> Collapsed: collapse
Expanded --> Detail: open comparison or full output
Collapsed --> Detail: open comparison or full output
Detail --> Expanded: dismiss
Detail --> Collapsed: dismiss
```
## Agent activity
- Active edits may use signs, line highlights, extmarks, virtual text, or virtual lines.
- Completed edits leave a navigable changed-line trail until cleared by defined editor activity or session action.
- Activity belongs to its Pi session and does not overwrite unrelated diagnostic or extmark namespaces.
- File and range references are navigable through normal Neovim motions and lists.
- Cross-file findings use quickfix lists.
- Window-associated findings use location lists.
- AI diagnostics remain distinguishable from compiler and language-server diagnostics.
## Follow-agent mode
- Follow mode is optional and disabled unless selected by the user.
- It follows location-bearing reads, edits, findings, and explicit navigation rather than every event.
- It can follow in a dedicated window, a dedicated tab, or the current window.
- Dedicated-window following preserves the user's working window.
- Passive following avoids unnecessary jumplist pollution.
- The user can return to the location held before following began.
## Pi compatibility
- The companion extension is shipped with pivi and injected additively when Pi starts.
- User, project, package, provider, skill, prompt, and tool configuration continues to load under Pi's normal rules.
- pivi does not silently alter Pi project trust or restrict available tools.
- Extension tools, commands, hooks, prompt changes, session behavior, and supported RPC dialogs remain functional.
- TUI-only renderers, custom components, keybindings, headers, footers, and terminal input are not emulated.
- Supported extension dialogs and status requests map to native Neovim surfaces.
- Unrestricted Neovim Lua execution is available alongside structured convenience tools.
## Native integration invariant
pivi is an optional producer of native Neovim state, never the owner of surrounding configuration.
- It does not replace or require a statusline, winbar, tabline, picker, notification system, layout, or keymap framework.
- It publishes cached state through native variables and semantic `User` events.
- It offers commands and `<Plug>` mappings without imposing global mappings.
- Consumers can degrade to ordinary Neovim behavior when pivi is absent.
- Loading pivi succeeds when the Pi executable is unavailable; starting Pi reports the missing capability.
- Status consumers never perform Pi RPC during statusline evaluation.
## Transport and status
- Pi RPC uses a non-terminal JSONL subprocess channel.
- Terminal dimensions, alternate screens, cursor escapes, and terminal key forwarding are not part of pivi.
- Standard error remains separate from protocol output.
- ANSI styling in payload text is stripped or translated before native presentation.
- Semantic session status includes connection, queue, run, tool, waiting, compaction, retry, abort, and error states.
- Status also exposes available model, thinking, session, context, usage, and extension-status data.
- Status changes redraw native status surfaces and emit a semantic event.
## Acceptance criteria
- A Pi slash command can run through `:Pi command ...`; `/` invokes slash-command entry only at the first character of a Pi input buffer.
- A transcript renders message formatting, presents embedded code in its own language, and still yields the original text when copied.
- A collapsed tool entry is one line carrying a tool-coloured indicator, the subject, and the outcome; the focused entry is visibly distinguished.
- A tool entry expands its detail in place and collapses back, and the detail is set apart from conversation text.
- A completed edit shows added and removed lines distinctly, opens as an editor comparison on a dedicated surface that preserves the working window, and navigating from it lands on its first changed line.
- Output of a long-running tool appears progressively rather than only at completion, and a truncated result is marked and its full output stays reachable.
- A search tool groups matches by file with the matched text distinguished and sends cross-file findings to a quickfix list.
- A file read presents a syntax-aware preview that leads to the file.
- A failed tool shows a single outcome line and no body.
- A tool result is collapsed on arrival, expands on request, and collapsing never changes session history.
- A user can move between transcript entries with ordinary motions and reach the location an entry names.
- Transcript presentation performs no Pi RPC, and a long streamed answer stays responsive.
- `:Pi help` answers while a working session run is active, without appearing in that session's history, queue, or status.
- A help question carries the visible editor region, layout, selection, recent messages, and the last error, and no full buffer.
- Help can answer an editor documentation question from the running instance, including documentation of installed plugins.
- No help run can modify a buffer, a file, or Pi state.
- A submission made during an active run is delivered as steering or a follow-up by a distinct, announced choice, and is never silently dropped.
- Accepting the prompt while the agent is working steers the run; a separate announced key queues a follow-up.
- A queued follow-up can be listed and cleared before delivery.
- A user can create, resume, switch, and stop explicit Pi sessions without tying their lifetime to a source buffer or tab.
- Resuming with no target resumes the most recent session for the working directory; a specific session resumes by identity; neither starts a new conversation nor calls the model.
- Prior sessions for the working directory can be listed and one chosen to resume.
- Resuming rebuilds the transcript as addressable entries with rendered messages and tool calls paired to their results, and the rebuild performs no model call.
- A restored tool entry whose recorded result carries no change detail shows its subject and result text rather than a fabricated diff.
- Restarting reloads the pivi client and resumes the active session by identity with its history and place intact.
- pivi publishes a serializable per-working-directory session descriptor and an idempotent restore entry point, registers no editor session-load hook, and imposes no global mapping, so a native-session workflow can capture and restore pivi without pivi owning session persistence.
- Restoring from a missing descriptor or an absent session degrades quietly to no restoration.
- A prompt can include an unsaved selection with stable source and revision metadata.
- Pi can read unsaved loaded-buffer content and use current core Neovim context on demand.
- Pi can execute arbitrary Neovim Lua and use structured editor operations.
- A normal Pi edit to a loaded buffer appears without reload, is undoable, remains coherent with subsequent shell work, and receives visible activity markers.
- Streaming edit arguments can produce non-mutating ghost presentation; incomplete arguments never mutate the real buffer.
- Follow mode can track an agent edit in a dedicated viewport without taking over the user's working window.
- Quickfix, location-list, diagnostic, and file navigation use normal Neovim behavior.
- Existing Pi extensions and tools continue to run except for capabilities inherently specific to Pi's TUI.
- A custom Neovim configuration can consume pivi state and events without requiring pivi to be installed or loaded.
- pivi does not modify user-owned statuslines, winbars, tablines, global mappings, or picker configuration.
- No filesystem watcher is started.