GitHub - siliroid/whereruns: Before you reason about a file, find out where it actually executes. Provenance for the reader, not the deploy. Zero dependencies. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
siliroid
whereruns
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>4 Commits<br>4 Commits
LICENSE
LICENSE
README.md
README.md
mcp.js
mcp.js
package.json
package.json
whereruns.js
whereruns.js
View all files
Repository files navigation
whereruns
Before you reason about a file, find out where it actually executes.
npx whereruns src/handler.js
No dependencies. One file. Exits non-zero on drift, so it works as a CI gate or as a<br>precondition an agent can call before it starts thinking.
For agents — the actual customer
A coding agent does not shell out and read stdout. It calls tools. So the check has a<br>second front door:
claude mcp add whereruns -- node /path/to/whereruns/mcp.js
One tool, described so the model knows when to reach for it: before reasoning about or<br>editing a file that might have a deployed copy. It returns isError: true on drift — an<br>agent that only checks the flag still stops; one that reads the text gets paths and byte<br>counts.
The failure it prevents is specific and expensive. An agent reads a file, reasons about<br>it correctly, edits it correctly — against bytes that are not the bytes running in<br>production. Nothing throws. Every tool call in the transcript is real and succeeds. A<br>guardrail that audits tool calls signs off on all of it, because the mistake was made<br>before the first call: choosing which file to open.
That used to be cheap, because the reader of a file was usually the person who deployed it<br>and carried the map in their head. The primary reader now has no ambient deploy context, no<br>memory of Tuesday staging, very high confidence, and write access.
The question
I am about to reason about this file. Where does it actually execute — and are those<br>the same bytes?
Nothing answers this. Everything adjacent is writer-side :
tool<br>question it answers
Terraform / Pulumi drift<br>does the deployed environment match my configuration?
SLSA, sigstore, in-toto<br>did the pipeline build what it claims?
source maps<br>which source produced this bundle?
All three protect the deploy . None protect the person — or the agent — about to read a<br>file and act on what it says.
Why it didn't need to exist before
For most of software history the person reading a file was the person who deployed it.<br>They carried the map in their head: that's the working copy, the live one is on the other<br>box. The knowledge lived in ambient human context, so a tool would have solved a problem<br>nobody had.
That changed. A large share of code reading is now done by agents, which have no ambient<br>deployment context, no memory of the staging step someone did on Tuesday, high confidence,<br>and a tendency to act immediately rather than squint.
A silent wrong-file failure used to cost an engineer an afternoon. It now costs a<br>production change made against source that was never running.
What it does
Hashes the file you point at, finds same-named copies across candidate roots, and tells you<br>which of them differ.
/mnt/deploy (ENOENT)
ok /srv/app/handler.js<br>18,442 bytes · 9c1e77ab40f2<br>DRIFT /opt/legacy/app/handler.js<br>7,110 bytes · 48535f8e23cc ⚠ 18 days older
⛔ 1 copy on disk differs from what you are reading.<br>Find out which one executes before you reason about this file."> reading /home/me/app/handler.js<br>18,442 bytes · 9c1e77ab40f2
⚠ roots that could NOT be searched — results below are incomplete:<br>/mnt/deploy -> /mnt/deploy (ENOENT)
ok /srv/app/handler.js<br>18,442 bytes · 9c1e77ab40f2<br>DRIFT /opt/legacy/app/handler.js<br>7,110 bytes · 48535f8e23cc ⚠ 18 days older
⛔ 1 copy on disk differs from what you are reading.<br>Find out which one executes before you reason about this file.
search sensible default roots<br>whereruns --roots /srv,/opt search these instead<br>whereruns --json machine-readable, for agents and...