Sidekick: keep using neovim while a dozen agents rewrite your code

Protects your unsaved Neovim work from Claude Code, Codex, opencode, pi, and Crush.

A conduit between Neovim and your AI agents — so they wait when you're typing.

Skip to 1:20 to see a block. The same recording is bundled in the binary — run sidekick demo after install to play it back offline.

I do less and less coding by hand. The part I still do, I do very deliberately — pop open a new pane, open Neovim, start editing. It's a flow state I have to push myself into. The catch: Neovim is the only thing in the system that knows I'm typing. When the agent in the next pane decides the file I'm in needs editing, the buffer reloads, my work gone. So I decided to do something about it.

Sidekick is the conduit between the editor and the agents. When you have unsaved changes in a buffer, the agents wait — the edit is denied, your buffer is untouched. Save the file and the next attempt proceeds. No flags, no confirmation prompts, no policy file. The 99% of edits that don't conflict with you go through untouched.

The other direction works too: when the AI modifies a file you have open, Sidekick refreshes the buffer in every Neovim instance, cursor position preserved.

• The AI waits on a file while you're editing it. You'll see this in Neovim: Edit blocked — file has unsaved changes

. - A file the AI edits while you have it open is auto-reloaded — no :e!

dance. - A current or recent visual selection in Neovim can be added to your next Claude Code, Codex, opencode, or pi prompt as context. Select code, type the prompt, hit enter.

Everything else stays the same. You keep using nvim

like normal.

The one-liner installs the binary with Cargo, registers Claude Code edit/refresh hooks, and adds the shell alias. Pipe through less

first if you want to read it.

curl -sSL https://raw.githubusercontent.com/NishantJoshi00/sidekick/main/scripts/install.sh | bash

Then restart your shell, or source the rc file the installer updated, and verify with sidekick doctor

:

  sidekick doctor

  ✓ sidekick v0.6.0 on PATH
      ~/.cargo/bin/sidekick
  ✓ NVIM v0.10.0 on PATH
  · AI harnesses: Claude Code, Codex
  ✓ Claude Code hook registered
  ✓ Codex plugin installed
  ✓ nvim alias: nvim → sidekick neovim (zsh)
  · no Neovim opened here
  · last activity: never

If a row fails, sidekick doctor --fix

offers consent-gated repairs for the Claude Code hook, Codex plugin, opencode plugin, pi extension, and nvim

alias. It shows the diff before writing anything.

The installer covers protection and buffer refresh for Claude Code. For Claude Code prompt-context injection, install the Claude Code plugin or add the UserPromptSubmit

hook shown below.

For Codex, run sidekick init

or sidekick doctor --fix

after installing the binary. Sidekick installs the Codex plugin into your personal Codex marketplace, enables plugin_hooks

, and enables sidekick@personal

.

Manual install (cargo + Claude Code plugin)

cargo install sidekick

/plugin marketplace add NishantJoshi00/claude-plugins
/plugin install sidekick@nishant-plugins

alias nvim='sidekick neovim'

Don't have Rust? curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

.

Manual Claude Code hook configuration (no plugin)

Add to ~/.claude/settings.json

:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "MultiEdit|Edit|Write", "hooks": [{ "type": "command", "command": "sidekick hook" }] }
    ],
    "PostToolUse": [
      { "matcher": "MultiEdit|Edit|Write", "hooks": [{ "type": "command", "command": "sidekick hook" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "sidekick hook" }] }
    ]
  }
}

The UserPromptSubmit

entry is optional. It is the one that adds your Neovim visual selection to Claude's prompt context.

sidekick doctor

prints this matrix per harness; here it is in one place. A ✓

is a feature sidekick exercises fully through that harness's hook surface; a —

is an upstream gap (the harness doesn't expose the hook event sidekick would need).

Harness	Edit deny	Buffer refresh	Selection injection
Claude Code	✓	✓	✓
Codex	✓	✓	✓
opencode	✓	✓	✓
pi	✓	✓	✓
Crush	✓	—	—

Use with Codex

Codex uses plugin-bundled hooks. After installing the sidekick

binary, let Sidekick wire the plugin and config:

sidekick init

or:

sidekick doctor --fix

The repair writes the plugin to ~/plugins/sidekick

, registers it in ~/.agents/plugins/marketplace.json

, enables [features].plugin_hooks = true

, and enables [plugins."sidekick@personal"].enabled = true

in ~/.codex/config.toml

.

Codex may ask you to review and trust the new hook before it runs. Run sidekick doctor

to confirm. See plugins/codex/ for details.

Use with opencode

opencode uses a plugin system instead of CLI hooks. After installing the sidekick

binary, drop the plugin into your global opencode config:

mkdir -p ~/.config/opencode/plugin
curl -sSL https://raw.githubusercontent.com/NishantJoshi00/sidekick/main/plugins/opencode/sidekick.ts \
  -o ~/.config/opencode/plugin/sidekick.ts

opencode loads it at startup. If sidekick

is not on PATH

, the plugin no-ops rather than blocking opencode.

For a per-project install, use <project>/.opencode/plugin/sidekick.ts

. Run sidekick doctor

to confirm. See plugins/opencode/ for details.

Use with pi

pi uses a TypeScript extension system instead of CLI hooks. After installing the sidekick

binary, drop the extension into your global pi config:

mkdir -p ~/.pi/agent/extensions
curl -sSL https://raw.githubusercontent.com/NishantJoshi00/sidekick/main/plugins/pi/sidekick.ts \
  -o ~/.pi/agent/extensions/sidekick.ts

pi loads it at startup. If sidekick

is not on PATH

, the extension no-ops rather than blocking pi.

For a per-project install, use <project>/.pi/extensions/sidekick.ts

. Run sidekick doctor

to confirm. See plugins/pi/ for details.

Use with Crush

Crush registers hooks directly in crush.json

— no plugin file to bundle. After installing the sidekick

binary, let Sidekick merge the hook into your global Crush config:

sidekick init

or:

sidekick doctor --fix

The repair merges a PreToolUse

hook against ^(edit|write|multiedit)$

into ~/.config/crush/crush.json

, preserving every other key.

Crush only emits PreToolUse

, so the buffer-protect path is covered but two pieces of the sidekick contract are intentionally absent: there is no post-edit buffer refresh, and no visual-selection injection on prompt submit. Both are upstream limitations, not sidekick configuration.

Run sidekick doctor

to confirm. See plugins/crush/ for details.

Just use nvim

. The shell alias routes through sidekick so the hook can find your editor.

nvim src/main.rs

If you do not want the alias, run sidekick neovim <args>

directly. You won't notice anything different until Claude Code, Codex, opencode, or pi tries to overwrite unsaved work, at which point sidekick denies the edit and tells the agent why.

Command	What it does
sidekick neovim <args>
Launches Neovim with a per-directory socket the hook can find. Aliased as nvim .
sidekick hook
Reads hook JSON on stdin and decides allow/deny, refreshes buffers, and returns visual-selection context. You don't run this directly — Claude Code and Codex do, and the opencode/pi bridges pipe to it.
sidekick doctor [--fix] [--no-color]
Checks your install: binary on PATH, nvim on PATH, AI harnesses present, hooks/plugins registered, alias active, sockets open in this directory, last hook decision. --fix offers consent-gated repairs where possible.
sidekick demo
Plays the demo cast inline in a ratatui frame. Useful for showing a coworker.
`sidekick stats [--range week	month
Local activity dashboard built from append-only JSONL events: launches, allows, blocks, refreshes, and top files. Nothing leaves your machine.

sidekick neovim

launchesnvim --listen /tmp/<blake3(cwd)>-<pid>.sock

. The socket path is deterministic per canonical working directory and unique per process, so the hook can find every Neovim instance opened from the same project.- Claude Code and Codex call sidekick hook

before file edits. The opencode and pi bridges do the equivalent for theiredit

andwrite

tools. The hook globs/tmp/<blake3(cwd)>-*.sock

, connects to reachable instances over msgpack-rpc with a short timeout, and asks whether each target is active with unsaved changes. If yes, the edit is denied; otherwise it is allowed. If no Neovim socket is found, sidekick degrades to allow. - After an edit lands, the hook tells every reachable Neovim instance with the file open to reload it. Cursor positions and visible windows are preserved.

• On prompt submission, if Neovim has a live visual selection or recent visual marks, sidekick returns fenced context blocks like [Selected from path:start-end]

. Claude Code and Codex receive them as additional context; opencode and pi append them to the submitted prompt text. - Decisions, refreshes, Neovim launches, and stats views are appended locally to sidekick/events.jsonl

under your OS data directory. Writes are best-effort and analytics never block the hook path.

No daemons, no background service. Just one CLI, Neovim RPC sockets in /tmp

, and optional per-tool bridge files.

Neovim with RPC + Lua support, a Unix-like system, and at least one supported AI harness: Claude Code, Codex, opencode, or pi. Rust/Cargo is required for cargo install

or building from source; the install script also needs python3

or python

to merge Claude Code settings.

Sidekick is Phase 1 — Neovim plus Claude Code, Codex, opencode, pi, and Crush. The longer arc is a small protocol any editor can expose and any AI tool can query before writing: is this file being edited by a human right now? PHILOSOPHY.md has the roadmap (Helix, Zed, VS Code; Aider, Goose, Continue) and the extension points.

Issues and PRs welcome. If you want to add a new editor or AI tool, the Action

trait in src/action.rs

is the contract — PHILOSOPHY.md covers the architecture.

source & further reading

github.com — original article