sidekick-reader.nvim

A readable, live view of your Sidekick Codex conversation.

Sidekick's terminal remains the place where you type, approve actions, and manage sessions. Sidekick Reader adds a normal Neovim buffer for reading the conversation: responses wrap like regular text, commands stay out of the way, file changes are highlighted, and familiar motions work as expected.

Important

Sidekick Reader currently supports Codex sessions managed by Sidekick with tmux. It is not a standalone chat client.

Features

• Streams prompts, Codex responses, command output, and file changes without parsing terminal text
• Wraps long responses cleanly and follows new output while you stay at the bottom
• Pauses automatic scrolling while you read earlier messages and shows a New output notice
• Folds command details by default and highlights live file diffs
• Opens file references from the conversation with gf
• Reviews the file changes from one AI turn with gd
• Shows the reader above the Sidekick terminal, or temporarily replaces it
• Hides and restores together with the Sidekick workspace while Codex keeps running in tmux

Requirements

• Neovim 0.11.2 or newer
• sidekick.nvim
• Codex CLI, installed and signed in
• Node.js 22 or newer
• tmux
• nui.nvim for the stacked layout
• diffview.nvim for per-turn reviews

Installation

The example below is a complete lazy.nvim setup. It connects Sidekick and Sidekick Reader, starts Codex through the included bridge, and adds <C-]> for moving between the terminal and reader.

{
  "folke/sidekick.nvim",
  dependencies = {
    {
      "mkdir700/sidekick-reader.nvim",
      dependencies = { "MunifTanjim/nui.nvim", "sindrets/diffview.nvim" },
    },
  },
  opts = function(_, opts)
    require("sidekick_reader.integrations.sidekick").setup(opts)
  end,
  keys = {
    {
      "<leader>aa",
      function()
        require("sidekick.cli").toggle({ name = "codex" })
      end,
      desc = "Toggle Sidekick Codex",
    },
  },
}

Restart Neovim, run :Lazy sync, then use <leader>aa to open Codex.

Usage

Sidekick Reader opens with the Sidekick Codex terminal. Type and approve actions in the terminal; use the reader when you want to follow or review the conversation.

Key	Action
<C-]> in Sidekick	Focus the reader
i or <C-]> in the reader	Return to Sidekick input
]m / [m	Next / previous message
]g / [g	Last / first message
G	Jump to the latest output and resume following
gf	Open the file reference under the cursor in the editor window on the left
gd	Review the current turn's file changes in Diffview
q	Hide the Sidekick workspace

Commands are folded automatically. Standard Neovim fold commands such as za, zo, and zc can expand or collapse them.

Layouts

stacked keeps both views visible, with the reader above the Sidekick terminal:

require("sidekick_reader.integrations.sidekick").setup(opts, {
  layout = "stacked",
  viewer_ratio = 0.8, -- 80% reader, 20% terminal
})

replace uses the Sidekick terminal window for the reader and restores the terminal when you leave:

require("sidekick_reader.integrations.sidekick").setup(opts, {
  layout = "replace",
})

The Sidekick integration defaults to stacked with an 80/20 split.

How it works

The included bridge starts a local Codex App Server and connects the normal Codex terminal to it. Sidekick Reader observes the same session and renders the structured events in a Neovim buffer. This is why long lines, command output, and file changes remain readable without scraping the terminal screen.

The gd review uses the changes reported by Codex for the selected turn. It does not use the repository's current diff, so changes that already existed in your working tree are not mixed into the review.

Troubleshooting

The Sidekick terminal opens, but the reader does not

• Confirm that Sidekick is using the tmux backend.
• Confirm node --version reports 22 or newer.
• Confirm codex works and is signed in when run directly.
• Check :messages for a Sidekick Reader error.

gf cannot open a file

The reference must point to an existing local file. Sidekick Reader opens it in a normal editor window to the left of the reader.

gd says there are no recorded changes

Place the cursor inside a turn where Codex changed files. Diffview also requires the conversation directory to be inside a Git repository.

Development

Run the automated test suite:

for spec in tests/*_spec.lua; do
  nvim --headless -u tests/minimal_init.lua -l "$spec" || exit 1
done

Run the bridge tests:

node --test tests/bridge_spec.mjs

The real Codex smoke test sends a short prompt using your signed-in Codex CLI:

nvim --headless -u tests/minimal_init.lua -l tests/real_codex_smoke.lua