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:
- One source line:
- Inclusive source range:
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:
bash
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
, and do not inject
HERDR_PLUGIN_CONTEXT_JSON
. herdr resolves the relative pane
command against
, 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
-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:
bash
# `$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
— 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
cannot start the manifest entrypoint on native Windows. For a targeted request, use WSL with
the command above. If the binary is already on
, 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
, run it directly:
bash
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.