claude-tmux-notify.nvim

claude-tmux-notify.nvim

Get a Neovim toast when a Claude Code session
running in another tmux window needs your attention — either because it's
waiting for input (a permission prompt / idle) or because it just finished a
task.

If you run several Claude sessions across tmux windows and work in Neovim, you
no longer have to keep switching windows to check whether one is blocked on you.

How it works

- A Claude Code hook fires the moment Claude needs input (Notification) or
  finishes (Stop) — no screen scraping, it's the official signal.
- The hook records the tmux window it ran in and appends one JSON line to a
  cache file.
- This plugin tails that file and raises a toast — unless the waiting
  Claude is in the tmux window you're currently looking at (no noise for
  sessions you can already see).

Requirements

- Neovim ≥ 0.10 (vim.uv)
- tmux (for window labels + focus suppression;
  works without it, but with no location info and no suppression)
- A notifier: folke/snacks.nvim (used
  automatically if present) or any vim.notify backend
  (nvim-notify, fidget, …)
- jq recommended (the hook falls back to a pure-bash parser without it)

Install

lazy.nvim

packer.nvim

Wire up the Claude Code hook

The plugin handles the Neovim side. The Claude Code side lives in
~/.claude/settings.json and points at the bundled scripts/tmux-notify.sh.

Automatic (recommended)

After installing the plugin, run once inside Neovim:

This merges the Notification and Stop hooks into ~/.claude/settings.json
(backing it up to settings.json.bak first) pointing at the bundled script.
Restart any running Claude Code session afterward so it picks up the hooks.

Manual

Find the script path with :ClaudeTmuxNotifyHookPath, then add to
~/.claude/settings.json:

Test

A toast should appear within…