Agent Workbench

A workspace-aware Neovim workbench for coding agents, currently powered by pi.dev.

Built from pi2.nvim's foundation, independently maintained around multi-workspace sessions, reviewed edits, and an in-editor command workflow.

Agent Workbench runs pi --mode rpc beside Neovim and turns agent work into an editor-native workflow. Conversations, files, workspace state, tool output, shell commands, diffs, and attention requests stay inside Neovim without replacing normal editing.

Pi remains built-in and default. Backend plugins can register a semantic BackendSession factory; frontend features are enabled by backend capabilities instead of backend-name checks. Backends that implement list_history / load_history also use the standard continue/resume commands without Pi JSONL files.

The canonical Lua namespace is now agent-workbench:

require("agent-workbench").setup()

Legacy require("pi") remains as a deprecated compatibility entry until 2.0.0. New configuration should use the canonical namespace. This repository is not an official new version of pi.nvim.

Most agent integrations treat one Neovim process, one project, and one chat as one global context. That breaks down when work spans several projects, tabs, sessions, or editor windows.

This frontend treats agent work as stateful editor work:

• each tab can own one project workspace;
• each session owns its own transcript, prompt, attachments, model state, and RPC process;
• hidden sessions keep running without taking over the visible chat;
• agent edits remain reviewable before they reach files;
• local shell work stays available without entering model context;
• normal Neovim buffers and navigation remain first-class.

Agent Workbench keeps agent sessions, workspace state, and local shell work visible inside Neovim.

The overview recording shows buffer chat, independent sessions, background work, and workspace switching. Each workspace keeps its own session and editor view.

The Shell Worksheet recording shows !! opening persistent Fish, state surviving across cells, and btop opening in a terminal float before returning to the worksheet.

Each tab acts as an independent workspace with its own working directory, buffers, sessions, and agent process.

• :AgentWorkbenchNewWorkspace creates a workspace rooted at a selected directory.
• :AgentWorkbenchWorkspaces switches workspaces through a searchable picker.
• :AgentWorkbenchWorkspaceSidebar shows workspaces, open sessions, Pi's time-grouped file history, and ordinary buffers together.
• With the built-in Pi backend, open a historical row to resume it in that workspace without replacing another session; external backends use the standard continue/resume commands for their backend-owned history. Press p on an open-session row to preview live output without switching workspace or changing cwd.
• :AgentWorkbenchMoveBuffer moves ordinary buffers between workspaces.
• Workspace buffers stay scoped to the current tab instead of leaking across projects.
• Changing workspace cwd starts a fresh session only when the current session is idle.
• Workspace state and unsent drafts are isolated by cwd and Neovim process.

Sessions are buffer-owned instead of being one global chat singleton.

• Keep several sessions alive in one tab or across tabs.
• Switch sessions with ordinary buffer commands.
• Continue or resume sessions from Pi's cwd-scoped files or backend-owned history.
• Background output stays in its owning History buffer.
• Re-entering a session restores its last History cursor and folds.
• :AgentWorkbenchSessions gives one live overview of busy, idle, attention, and stopped sessions.
• :AgentWorkbenchTree navigates conversation branches and can summarize abandoned branches.
• :AgentWorkbenchSessionStats shows messages, tokens, cache usage, cost, and context usage.
• Manual and automatic context compaction keep long sessions usable.
• /new keeps the current session alive and opens another; /replace discards the current idle session and reuses its view.

Agent output is useful only when its changes remain understandable and reversible.

• :AgentWorkbenchDiff reviews all files changed by the current session in one panel.
• Two-way diff review supports accepting, rejecting, and editing proposed results.
• Review notes and permission-extension requests stay in the editor workflow.
• Unsaved buffers are never overwritten by automatic reload.
• Failed writes keep diff review open instead of silently closing it.
• gf jumps from paths, mentions, and line references in chat history.
• Search results can populate quickfix for normal :cnext and :cprev navigation.

Prompt editing keeps normal editor habits while adding agent-specific controls.

• Readline-style prompt history with <C-p> and <C-n>.
• Unsent prompts persist across restart.
• Drafts are scoped by workspace and process, preventing cross-project prompt leaks.
• @ mentions support files, line ranges, git state, LSP errors, quickfix entries, and custom providers.
• Slash commands and popup completion work inside the prompt; /model completes available models and /thinking completes levels supported by the current model.
• Queue follow-up prompts while the agent is busy.
• Double <Esc> aborts a running turn, including retry backoff.
• Attach images from disk, clipboard, or drag-and-drop.
• Optional image downscaling and re-encoding reduce attachment size.
• Zen mode provides a larger prompt for long instructions.
• Models and thinking levels can change during a session.

Submit !! to open a persistent Fish worksheet inside the existing Prompt buffer. Submit !!command to run an initial command.

The worksheet is file-style Neovim editing, not terminal-mode input:

• Fish state persists across cells, including cwd, variables, aliases, and functions.
• Commands bypass pi RPC and stay outside LLM context.
• Fish completion comes from the same persistent session.
• Completion covers commands, options, aliases, functions, variables, and paths.
• Command whitespace triggers argument and path completion immediately.
• Exact current options remain visible alongside longer Fish candidates.
• Completed command and output blocks are protected and foldable.
• Shell status shows Fish's cwd and execution state; ❯ starts a command and ↳ clearly marks foreground input.
• Live output is readable, selectable, and searchable without waiting for completion.
• ANSI colors, URLs, paths, unified diffs, and JSON output receive editor highlights when supported.
• Copying, searching, visual selection, gf, and normal motions operate on original output text.
• Copy a cell's output or attach it to your compose draft explicitly; attaching never sends it automatically.
• Normal-mode editing from historical output jumps to the current input cell.
• While a command is running, <CR> sends the current input to its foreground PTY instead of starting a second cell. This supports line-oriented nested shells and REPLs such as nix shell.
• Commands that enter a standard alternate screen, including btop, htop, fzf, and lazygit, automatically open the same persistent PTY in a native terminal float. Leaving the alternate screen or ending the outer command restores the worksheet; terminal-mode <C-g>c interrupts it, terminal-mode <C-g>p returns early while leaving it running, and Normal-mode q interrupts the program and closes the float.
• <C-c> interrupts only while a command is running; idle behavior stays native.
• Outside the terminal float, <C-d>, q, and <C-g>p return to compose while preserving worksheet state.
• Prompt requests can temporarily replace the worksheet while Fish keeps running.

The worksheet currently requires the fish executable. It does not replace the user's normal shell configuration and does not make !! commands private: commands can still modify files and external systems. Foreground input stays line-oriented until a command emits a standard alternate-screen sequence; Agent Workbench then displays that same PTY in a native terminal float for full-screen input and resize handling. For pagers and prompts that do not enter an alternate screen, <C-g>o opens the running command's existing terminal manually. Never enter passwords in worksheet input—switch to the terminal first. See the shell worksheet guide for controls and limitations.

The frontend uses normal Neovim buffers, windows, extmarks, folds, quickfix, and buffer navigation.

• Chat supports buffer, side, and float layouts.
• History is a listed nofile buffer with subtle assistant-segment rails plus structured tool and thinking blocks.
• Tool output folds without losing extmarks or transcript state.
• Statusline shows agent state, elapsed time, queue count, context, token usage, cost, and abort hints.
• Attention requests queue until the user opens them.
• Extension UI can use dialogs, pickers, widgets, and custom blocks.
• Message-level Markdown uses Markview's parser API plus Agent Workbench Extmarks, so malformed Markdown cannot leak across messages; Obsidian-style cursor reveal exposes only the active source element for smooth navigation. blink.cmp, img-clip.nvim, bufferline.nvim, and nvim-web-devicons integrate when installed.

1. Install pi and make sure it is in $PATH.
2. Install this plugin and the Markview Markdown parser dependency.
3. Run :checkhealth agent-workbench.
4. Open a project and run :AgentWorkbench.
5. Type a prompt and press <CR>.
6. Use @path/to/file to attach code context.
7. Use :AgentWorkbenchDiff to inspect completed edits; enable a permission extension for pre-execution approval.
8. Use !! when local shell work should stay outside agent context.

• Neovim 0.10+
• pi in $PATH
• OXY2DEV/markview.nvim and the Markdown Tree-sitter parsers for isolated History rendering
• fish for the !! Shell Worksheet

Optional:

• Additional Tree-sitter language parsers for syntax highlighting inside fenced code blocks
• HakonHarnes/img-clip.nvim for :AgentWorkbenchPasteImage
• blink.cmp for popup prompt completion
• bufferline.nvim for workspace tabs
• nvim-web-devicons for workspace sidebar icons and path highlights

Run :checkhealth agent-workbench after installation.

{
    "saya-ashen/agent-workbench.nvim",
    dependencies = {
        "OXY2DEV/markview.nvim",
        "HakonHarnes/img-clip.nvim", -- optional: :AgentWorkbenchPasteImage
    },
    opts = {},
}

vim.pack.add({
    "https://github.com/saya-ashen/agent-workbench.nvim",
    "https://github.com/OXY2DEV/markview.nvim",
})

require("agent-workbench").setup()

Defaults are usable without a custom configuration. Global keymaps remain disabled unless you enable the recommended preset. Full options live in doc/configuration.md.

Every command has a Lua API counterpart. See doc/api.md.

Legacy :Pi* aliases remain available during the migration period. Agent Workbench skips an alias when another plugin already owns that command, so the canonical :AgentWorkbench* commands can coexist with pi.nvim. The compatibility Lua modules require("pi") and pi.completion.blink remain inherently runtimepath-order dependent when both plugins are installed; use require("agent-workbench") and agent-workbench.completion.blink in mixed setups.

require("agent-workbench").setup({
    auto_start_session = false,
    keymaps = {
        preset = "recommended", -- opt-in: <Leader>a…, <M-h/l> buffers, <M-j/k> workspaces
        prefix = "<Leader>a",
    },
    layout = {
        default = "buffer",
        side = { position = "right", width = 80 },
    },
    workspace_bar = {
        enabled = true,
        label = "name",
        session_count = true,
        status = true,
    },
    workspace_sidebar = {
        position = "right",
        width = 38,
    },
})

See doc/configuration.md for all options.

Enter the reproducible Linux development shell:

nix develop

It provides Neovim, a fixed Demo Neovim profile, pi, Fish, btop, VHS, ttyd, ffmpeg, Plenary, StyleLua, LuaLS, Just, Python, Node.js, Make, Git, and the Linux GUI-automation tools. The Demo profile bundles Catppuccin, Lualine, web-devicons, Markview, and the Markdown Treesitter grammar. PLENARY_PATH points at the packaged Plenary checkout, so tests do not depend on a user plugin installation.

Run local checks through just:

just test
just smoke
just markdown-e2e  # real Markview parser + Tree-sitter injections
just style
just lint
just docs-links
just check

just is available inside nix develop; Makefile targets remain available for CI and existing workflows.

Run Neovim from this checkout:

./scripts/nvim-dev

The development launcher enables the recommended global keymap preset after user configuration loads, so it respects the active <Leader> and any custom keymaps.prefix. Regular plugin setup still leaves the preset disabled by default.

Record deterministic README demos with VHS:

just demo-overview
just demo-shell

When outside the development shell, use nix develop -c just demo-overview or nix develop -c just demo-shell.

VHS runs the fixed agent-workbench-demo-nvim profile from flake.nix, using scripts/demo/init.lua as its config. Recordings keep their own deterministic Agent Workbench setup without loading user configuration, while still showing the bundled theme, statusline, icons, and Markdown renderer. overview opens a buffer chat through :Pi, creates and switches workspaces, runs multiple sessions, and shows their live status dashboard. shell opens the buffer chat, enters the persistent Fish worksheet, and runs btop in its terminal float before returning to the worksheet. It atomically replaces assets/overview-demo.gif or assets/shell-worksheet.gif; both keep an MP4 source under /tmp/agent-workbench-vhs. Set DEMO_NVIM_BIN, OUTPUT, or SOURCE_VIDEO to override the demo Neovim wrapper or either destination.

Direct Neovim test commands are documented in .agents/skills/develop/ for environments without Nix or Make.

• Usage: chat, prompt, shell worksheet, completion, attachments, statusline, rendering, and navigation
• Sessions: workspaces, session ownership, resume, tree navigation, and compaction
• Diff review: review workflow, notes, and permission extensions
• Configuration: complete annotated defaults and project trust
• Keymaps: key specifications, stable filetypes, and setup examples
• API: public Lua API
• Extensions: extension UI and custom RPC blocks
• Highlight groups: all plugin highlight groups
• Migration: move from pi.nvim compatibility entry points to the canonical Agent Workbench namespace
• Troubleshooting: healthcheck, RPC logs, and lifecycle diagnosis

This project started from pi.nvim and keeps its compatible Lua namespace and command family. It is independently maintained and focuses on editor-native workspaces, multiple live sessions, reviewed agent edits, and persistent local shell workflows.

It is not an official successor or replacement for pi.nvim. Upstream changes are reviewed selectively rather than merged blindly. Credit for the original foundation remains with the upstream project and its authors.

MIT