Herdr File Viewer

Herdr File Viewer

Use this skill when the user asks to open, show, or reveal a file, source line, range, or function in the Herdr file viewer (also called "Files"). Use it when you have identified a likely change and offer to show the user where it is.

Resolve the location

Resolve the request to a repository-relative target before launching the viewer:

• File: src/app.rs
• One source line: src/app.rs:42
• Inclusive source range: src/app.rs:42-58

For a function or helper, locate its definition and use its definition line, not a call site. If there are materially different matches and context does not identify one, ask a short question instead of guessing. For a suspected bug line, distinguish an observed failure location from a hypothesis; do not present a guessed location as certain.

Open it in Herdr (Linux, macOS, or WSL)

Launch a fresh Files pane:

herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split --direction right --focus --env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"

Replace the example target with the resolved file, line, or range. The viewer loads the file and scrolls to the requested location. A range receives a brief highlight.

Do not add --cwd, and do not inject HERDR_PLUGIN_CONTEXT_JSON. herdr resolves the relative pane command against --cwd, so the launch fails everywhere except inside a built plugin checkout, where it silently runs THAT checkout's binary instead of the installed one. An injected context value is regenerated by herdr and discarded.

The viewed root comes from the focused herdr pane's working directory (resolved to that repository's worktree top level), so cd-ing in your own process does not move it — your tool calls run outside that pane's shell, and the viewer roots wherever that pane happens to be. When it may not be in the target repository, give the launch a pane whose cwd IS that repository, then drop it; the root is captured at launch:

# `$repo` is the target repository or worktree (any directory inside it), shell-escaped when assigned.
helper=$(herdr pane split --current --direction right --cwd "$repo" --focus \
  | python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')
# Or with jq: ... | jq -r '.result.pane.pane_id'
[ -n "$helper" ] || exit 1   # the split failed: stop, or the launch below roots at the wrong pane

herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer \
  --placement split --direction right --focus \
  --env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"

herdr pane close "$helper"   # run this even if the launch failed, so no helper is left behind

Confirm you targeted the right repository from the rendered tree (root row, and the branch in the tree border), not from the opened pane's reported cwd — that is the plugin's own directory, which looks wrong but is expected. If the tree shows the wrong repository, close the pane you just opened and relaunch with the helper recipe above.

Treat the target as data, never shell source. Prefer a structured argv or process API that passes HERDR_FILE_VIEWER_OPEN=<target> as one argument. In a shell, do not interpolate a raw path into command text: shell-escape it when assigning it, then expand the variable only inside double quotes.

Do not key-script the TUI. Do not close, focus, or try to retarget a Files pane you did not just open: launch open targets are applied only when a new viewer starts, and a pane that was already there may contain the user's annotations or navigation state.

Native Windows preview

The Windows launcher can open Files, but it does not accept an open target, and herdr plugin pane open cannot start the manifest entrypoint on native Windows. For a targeted request, use WSL with the command above. If the binary is already on PATH, run herdr-file-viewer.exe --open "<target>" in a terminal you intend to devote to the viewer. Do not say a generic Windows Files action opened the requested location.

Outside Herdr, if the binary is on PATH, run it directly:

herdr-file-viewer --open src/app.rs:42

Conversation behavior

When the user directly asks to see a location, open it after resolving the target. When you have identified a likely location while explaining a diagnosis or change, offer a short question such as "Want me to show you where to change that setting?" Open it after the user confirms.

After launching, state the exact target you opened. If the target cannot be resolved to a real file under the viewer root, explain that rather than opening an arbitrary or outside-root path.