# Install ranwhat

> Run ranwhat once with uvx, or install it with pipx or pip. Python 3.9+, no dependencies, no account needed. Start with ranwhat check and read the result.

Canonical: https://ranwhat.com/install

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

## 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](https://docs.astral.sh/uv/guides/tools/), and `uvx ranwhat@latest check` asks for the newest release. `pipx run ranwhat check` works the same way.

## Or put it on your path.

```
pipx install ranwhat
uv tool install ranwhat     upgrade with: uv tool upgrade ranwhat
pip install ranwhat
```

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

## 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](https://ranwhat.com/guides/claude-code-history) covers what else is in that directory. The [watch page](https://ranwhat.com/watch) 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.

## 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.