agent-tail.nvim

agent-tail-gif-2.mp4

Warning

agent-tail is currently experimental. Bugs are likely — expect rough edges.

A session review queue for AI coding agents in Neovim.

When Claude Code edits a file, agent-tail logs the event. Run :AgentTail to open a dedicated tab with a sidebar of every change in this session and a synthetic per-event diff for the selected one — your normal editing buffer is never disturbed.

:AgentTail layout
┌─────────────────────────┬──────────────────────────────────────────┐
│ Agent Tail              │ 14:22:07  Edit  src/lib/util.ts          │
│                         │                                          │
│ > 4. 14:22 E util.ts    │ --- old                                  │
│   3. 14:22 E util.ts    │ +++ new                                  │
│   2. 14:21 W README.md  │ @@ -1,3 +1,5 @@                          │
│   1. 14:20 E page.tsx   │  export function compute() {             │
│                         │ -  return 1                              │
│                         │ +  console.log('debug')                  │
│                         │ +  return 2                              │
│                         │  }                                       │
├─────────────────────────┴──────────────────────────────────────────┤
│ agent-tail  follow:paused  events:4  unique-files:3                │
└────────────────────────────────────────────────────────────────────┘

Quick start

1. Install with lazy.nvim:

{ 'Melkeydev/agent-tail.nvim', lazy = false }

2. Install dependencies:

brew install jq    # macOS — also need: nvim ≥ 0.10, shasum (preinstalled)

3. Inside Neovim, run:

:AgentTailInstallHook

Copy the JSON snippet it prints. Paste it under the top-level "hooks" key in ~/.claude/settings.json (the command does not modify your settings file — copy/paste keeps you in control of a file that holds API keys and other config).

4. Open a terminal split and run, both in the same project directory:

Pane 1	Pane 2
claude	nvim

Make any edit through Claude. The agent-tail tab auto-opens in the background. gt to switch into it.

Configuration

Defaults are sensible — most people won't need this. To change the sidebar width:

{
  'Melkeydev/agent-tail.nvim',
  lazy = false,
  opts = { width = 22 },  -- sidebar width in cols (default 22)
  config = function(_, opts) require('agent-tail').setup(opts) end,
}

Commands

Command	Action
:AgentTail	Open the review tab (sidebar + diff + status)
:AgentTailClear	Empty the event queue
:AgentTailInstallHook	Print the Claude hook JSON to paste into ~/.claude/settings.json
:AgentTailNext	Open next changed file in current window
:AgentTailPrev	Open previous changed file in current window
:AgentTailLast	Open the most recently changed file
:AgentTailQuickfix	Push touched files to the quickfix list (]q/[q to navigate)
:AgentTailStatus	Show socket state and queue counts

Next/Prev/Last cycle through unique files (deduped). The sidebar log keeps every event for forensic browsing.

Sidebar keymaps

Key	Action
j / k	Move selection (also drives the diff pane)
<Tab>	Next event
<CR>	Open selected file in your previous tab
p / f	Toggle follow mode (auto-jump to newest)
c	Clear the event queue
q	Close the agent-tail tab

Newest events appear at the top. Auto-follow tracks the latest as long as you haven't browsed away from it; once you move with j/k, your position is held even as new events arrive.

How it works

• Plugin startup computes a per-cwd socket path (sha256(cwd)[:12]) and calls serverstart().
• Claude's PostToolUse hook fires on every Edit / Write. The hook script normalizes the JSON payload (tool_name, file_path, old_string, new_string, content, ts) into an event file under ~/.cache/agent-tail/events-<hash>/, then RPCs the running nvim with the event file's path.
• The plugin reads the event file, appends an entry to an in-memory list, and deletes the temp file. The diff pane renders a synthetic unified diff from the hook's old_string → new_string (or the new content for Write) using vim.diff() — no git involvement, so what you see is exactly what Claude did this session.
• No daemon, no watcher, no IPC framework. Claude's hook → shell script → Neovim's built-in RPC.

See :help agent-tail for the full reference.

Limitations (v0.3)

• One Neovim per cwd. Open a second one in the same project and it logs a warning.
• Claude Code only. Codex CLI / OpenCode adapters land later.
• Events are session-scoped — "session" = nvim's lifetime. Edits made before nvim opened (or while it was closed) are not captured.
• Write events show only the new content (Claude's payload doesn't include the pre-write state).
• macOS / Linux only (uses shasum, POSIX shell).

Roadmap

• v0.4: Codex CLI + OpenCode hook adapters.
• v0.5: cumulative-per-file diff toggle (in addition to per-event).
• v0.6: multi-Neovim-per-cwd handling.
• v0.7: hunk-level navigation inside the diff pane.

License

MIT