Install

Install ranwhat

Python 3.9 or newer. No dependencies, no account needed, and nothing built on your machine. Current version 0.8.0.

01 / Run once

Try it without installing anything.

Start with check: it reads what your agents ran and what they left on disk, and changes nothing.

$ uvx ranwhat check

$ uvx ranwhat demo

demo runs an authority scan on a bundled example. uvx runs a tool without installing it, and uvx ranwhat@latest check asks for the newest release. pipx run ranwhat check works the same way.

ranwhat check in a terminal: 5 critical and 4 high findings, such as a file piped to the network, a token in a tool call and docker system prune, each with time, agent and command — What ranwhat check prints: the risky actions, newest first. Made-up history; no real data.

02 / Keep it

Or put it on your path.

pipx install ranwhat
uv tool install ranwhat     upgrade with: uv tool upgrade ranwhat
pip install ranwhat
brew install MatijaMiki/ranwhat/ranwhat

Then ranwhat check, which runs two commands together: ranwhat watch for what your agents ran, and ranwhat clean for secrets in their transcripts. ranwhat scan is separate, and scores what their credentials allow. A bare ranwhat lists every command.

Inside your agent

In Claude Code, the plugin adds /ranwhat:check, /ranwhat:watch, /ranwhat:reach and /ranwhat:guard, and installs no hook:

/plugin marketplace add MatijaMiki/ranwhat
/plugin install ranwhat --marketplace MatijaMiki/ranwhat

For Codex, Cursor, Gemini CLI and other agents, the same skill is on skills.sh. It tells the agent when to run ranwhat and never to print a secret:

$ npx skills add MatijaMiki/ranwhat

03 / Files

What it reads, and what it writes.

Claude Code Reads ~/.claude/projects/*/*.jsonl and the subagent transcripts beside them, the last 30 days by default (--days N). If CLAUDE_CONFIG_DIR is set, it reads $CLAUDE_CONFIG_DIR/projects instead, and --root PATH points it at any other directory. Where Claude Code keeps its history covers what else is in that directory. The watch page lists every agent ranwhat reads.

Writes None of your files, unless you ask. clean masks secrets only on --apply or mask, after a backup to ~/.ranwhat/backups. --html writes the report you name, mode 600. check and watch keep an index of the secrets clean finds in ~/.ranwhat/known ($RANWHAT_HOME/known when that is set), so they can hide every one in what they print: salted fingerprints, never a secret, readable by you alone. update caches the catalogue under ~/.ranwhat/feed, and stores its token at ~/.ranwhat/token (0600) only with --save-token. login saves this machine’s token there, and login, whoami and update note the plan last heard for a token in ~/.ranwhat/account.json (0600); logout deletes both. hook install and hook uninstall add or remove one PreToolUse entry in the Claude Code settings file you choose, and leave the rest of it as it was.

04 / Network

What goes online.

No account needed. live, callers, --pull-usage and clean's revoke ask only the provider that issued each token, and update, login, whoami, logout and push talk only to ranwhat.com. push sends derived metadata only, and only when you run it. Everything else reads locally and sends nothing.

It runs on Linux, macOS and Windows, and CI runs every test on all three.