Refs

Refs — Open Referenced File:Line Locations in nvim

Take the file:line references from a message, open them in a fresh nvim session in a tmux split, and preconfigure global marks ('A..'Z) and a quickfix list at each location so the user can jump straight to what was discussed.

You ARE the orchestrator. Three steps.

Step 1: Collect the references

From the target message, collect every file:line reference. The target is the most recent message that contains such references (usually your own last substantive reply); if the user's argument names a different message ("the one about the parser"), use that one instead.

A reference is a path with an optional line (and column): src/app.py:42, lib/util.ts:10:5, or a bare README.md. Collect them in the order they appear, keeping duplicates out. Produce a space-separated list of the raw tokens.

If the message contains no file:line references, say so and stop — do not open a split.

Step 2: Stage the session

Run the helper with the collected tokens:

bash ~/.claude/skills/refs/scripts/open-refs.sh <tok1> <tok2> ...

It validates each reference against the filesystem, writes the kept set to a JSON data file, and prints REFS_JSON, REFSVIM, REQUEST_PATH, CWD, TS, one MARK line per kept reference, SKIP lines for unresolved ones, and COUNT.

• If the script exits non-zero (no nvim, no tmux, not in a tmux session), relay its error and stop.
• If COUNT is 0, tell the user none of the references resolved to real files (list the SKIPs) and stop.

Step 3: Open the split

The split fires from a Write-tool write to the pane request (a bash write will not trigger the hook). Using the values the script printed, write this to REQUEST_PATH with the Write tool:

{
  "name": "refs/<TS>",
  "direction": "h",
  "size": 50,
  "cmd": "CLAUDE_REFS_JSON='<REFS_JSON>' nvim -S '<REFSVIM>'",
  "cwd": "<CWD>"
}

Substitute <TS>, <REFS_JSON>, <REFSVIM>, and <CWD> with the printed values. The pane hook opens the split and runs nvim, which sources refs.vim: it lands on the first reference, opens the quickfix window, and sets marks A.. for the first 26 references.

Then report to the user:

• the mark map — which letter jumps to which file:line (from the MARK lines);
• navigation: 'A, 'B, … jump by mark; :cnext / :cprev (or the open quickfix window) walk all references in order;
• any skipped references, and — if more than 26 resolved — that marks cover the first 26 while the quickfix list holds them all.

Error Recovery