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.
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.
A tool entry names what the tool acted on, and once it finishes, how it ended.
A completed edit presents its change as a diff, distinguishing added from removed lines, and that diff can be opened as a full editor comparison on request.
Navigating from an edit reaches its first changed line rather than the start of the file.
Output a tool produces while it runs appears as it arrives, not only at completion.
Output is presented in the language it came from when that language is known.
A result the agent could not keep in full says so, and its full output stays reachable.
An outcome stays legible while an entry is collapsed.
A tool that reports nothing about its own work degrades to naming its subject rather than to a guess.
stateDiagram-v2
[*] --> Started: tool call
Started --> Streaming: output arrives
Streaming --> Completed: tool ends
Started --> Completed: tool ends
Completed --> Compared: open the change
Compared --> Completed: return
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 completed edit shows added and removed lines distinctly and can be opened as an editor comparison.
Navigating from an edit entry lands on its first changed line.
Output of a long-running tool appears progressively rather than only at completion.
A truncated result is marked as truncated and its full output stays reachable.
A collapsed tool entry still states what the tool acted on and how it ended.
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 queued with explicit delivery and 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.
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_
---
# 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.
- While a session run is active, a new submission is queued with an explicit delivery choice and is never silently dropped.
- Queued submissions remain listable and clearable before delivery.
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Running: submit
Running --> Running: queue steering or follow-up
Running --> Idle: settle
Running --> Idle: abort
Idle --> [*]: 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.
- A tool entry names what the tool acted on, and once it finishes, how it ended.
- A completed edit presents its change as a diff, distinguishing added from removed lines, and that diff can be opened as a full editor comparison on request.
- Navigating from an edit reaches its first changed line rather than the start of the file.
- Output a tool produces while it runs appears as it arrives, not only at completion.
- Output is presented in the language it came from when that language is known.
- A result the agent could not keep in full says so, and its full output stays reachable.
- An outcome stays legible while an entry is collapsed.
- A tool that reports nothing about its own work degrades to naming its subject rather than to a guess.
```mermaid
stateDiagram-v2
[*] --> Started: tool call
Started --> Streaming: output arrives
Streaming --> Completed: tool ends
Started --> Completed: tool ends
Completed --> Compared: open the change
Compared --> Completed: return
```
## 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 completed edit shows added and removed lines distinctly and can be opened as an editor comparison.
- Navigating from an edit entry lands on its first changed line.
- Output of a long-running tool appears progressively rather than only at completion.
- A truncated result is marked as truncated and its full output stays reachable.
- A collapsed tool entry still states what the tool acted on and how it ended.
- 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 queued with explicit delivery and 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.
- 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.