Five steps, in order. By the end you will have seen what AIWatcher found on your machine, held a prompt before it ran, and printed what your last commit cost and how much of it is still there.
Python 3.9 or newer, on macOS, Linux or Windows. No account, no API key.
pipx install aiwatcher-local
pipx ensurepath
Open a new terminal afterwards so the aiwatcher command resolves.
The pip-in-a-virtualenv route, the Windows variants, the fixes for externally-managed-environment and friends, and the update commands all live on the AIWatcher Local page. They are kept in one place on purpose.
Nothing here needs configuration. AIWatcher reads history your tools already wrote, so step one already has something to show you.
aiwatcher setup
aiwatcher doctor
setup detects your tools and prints copy-paste next steps — it is a readout, not a menu, so there is no number to type. doctor is the honest one: it grades every surface it knows about and names the ones it cannot reach.
Expect some rows to say not detected. That is the point — AIWatcher lists what it cannot see rather than quietly dropping it. The full coverage grid explains the four marks.
aiwatcher start --open-ui
This starts three things: the Console in your browser at 127.0.0.1:8765, the background Companion, and the small floating control on macOS and Windows. The Console binds loopback only and walks to the next free port if 8765 is busy.
No floating control on macOS? It needs the Swift runtime, which ships with the Xcode Command Line Tools: xcode-select --install. The Console and Companion work either way.
Start on Home. It shows active AI work, context pressure and update status. If you would rather not have a background process yet, aiwatcher ui starts the Console alone.
A gate reviews a prompt before your agent spends context on it. Try it without installing anything first:
aiwatcher preflight "Refactor the checkout flow and delete old auth secrets" \
--tool codex --cwd "$(pwd)"
Then install the hooks for the tools you actually use. Each installer prints the change it would make and only edits files when you pass --write:
aiwatcher install-claude-hook --write --scope user --gate
aiwatcher install-codex-hook --write --scope user --gate
aiwatcher install-cursor-hook --write --scope user --gate
# Claude Code only: review risky shell commands as well
aiwatcher install-claude-command-gate --write --scope user
Now send a small test prompt in that tool and prove the hook fired:
aiwatcher hook-status
If a surface shows nothing, it may not expose a hook point at all — Claude Desktop chat and claude.ai in a browser do not. Use the Console’s Plan tab to preflight those by hand. AIWatcher does not claim silent protection on a surface it cannot verify.
This is the part nothing else does. Run it in a repo where you have been working with an agent:
aiwatcher commit-receipt
aiwatcher changes --days 30
commit-receipt reports what your latest commit cost, per line, against your own 30-day median. changes does it for every commit and adds the column that matters, Alive — how much of each one is still in the tree.
To get one automatically on every commit:
aiwatcher install-commit-hook --write
Two things to read correctly. A dash in the Alive column (Still standing in the Console) means not measured, not “did not last” — reformatting moves git blame, so every figure is a floor. And today’s work will read as not yet measurable, because a commit has to be about a week old before the question means anything. See real output.
AIWatcher can measure what stayed, but only you know whether a session was worth it. One word, whenever you finish something:
aiwatcher outcome useful
aiwatcher outcome rework --note "tests still failing after three prompts"
And when a session has grown bloated, do not re-explain the work from scratch:
| Command | What it does |
|---|---|
| aiwatcher handoff | Write a compact Fresh Start brief for a new session |
| aiwatcher resume | Find an earlier session and build a continuation brief |
| aiwatcher journal | Your own record of what you and your agents worked on |
| aiwatcher watch | Which live session needs you, ranked |
AIWatcher reads files your tools already wrote to your disk. It does not instrument anything new, and it does not call a model to produce any of these numbers.
Read from each tool’s own history, your git log and the process table. Session totals are cached in ~/.aiwatcher/cache/ so the dashboard loads fast; delete it and it rebuilds.
Connection strings, env-var secrets and token-like values become [redacted], alongside a sha256 of the original.
What AIWatcher records lives under ~/.aiwatcher/ — decisions and receipts in local-state.json, plus a cache it can rebuild and a Companion log. Hooks and autostart, the things you install with --write, live in each tool’s own settings instead, and every installer has a matching uninstall — aiwatcher uninstall-claude-hook, aiwatcher companion autostart uninstall. aiwatcher export writes summaries with privacy-safe event hashes for your own analysis.
Optional AI Assist is the single exception, and it is off until you turn it on: it sends bounded context, only for a workflow you picked. The full trust boundary spells out what that means.
Every dollar figure AIWatcher prints is an API-equivalent value: your token counts priced at published per-token rates.
That is the honest unit for comparing two sessions, or two commits, against each other. It is not necessarily what you were billed: on a Claude or ChatGPT subscription the same work may not be incremental spend at all. AIWatcher marks plan-limited usage separately rather than quietly folding it into a total.
Rates change often enough that a table on this page would be wrong within a month, so there isn’t one. The rates AIWatcher actually uses are a dictionary in aiwatcher_cli/pricing.py — readable, and the only source of truth.
Two commands answer most of it: doctor says what AIWatcher can see, hook-status says whether a tool actually called it.
| Symptom | What to do |
|---|---|
| No sessions at all | Run aiwatcher doctor. If history says not detected, AIWatcher never found that tool’s files — check the tool has actually been run on this machine. |
| Gate never fires | aiwatcher hook-status. Empty means the tool is not invoking the hook; confirm you passed --write, and that the surface exposes hooks at all. |
| Costs look too low | Subscription usage is counted in tokens but not priced: those models have no list price, so they come out at $0. Check the plan/limited token count before reading anything into a low total. |
| Alive column shows a dash | Not measured, not zero. Commits need to be roughly a week old, and commits that arrived by fetch are excluded because none of your local spend belongs to them. |
| Port 8765 in use | It falls forward automatically. Pick one with aiwatcher ui --port 9000, and add --no-port-fallback to fail instead of moving on. --restart is for the other case: an AIWatcher already holding that port. |
| Companion too chatty | aiwatcher companion stop, or restart it with --presence-visibility nudges-only. |
Local is the whole loop for one developer on one machine, and it always will be. Enterprise is the same loop for an organization.
Team policy and budgets, approvals before an agent acts, audit evidence, SSO and RBAC, managed deployment, central retention, org dashboards, and governance for agents running in production.
Raw prompts and source stay on your machine. Anything an organization sees is an explicit, minimized export you can preview, disable and revoke.
Enterprise is in active development with a small number of design partners, so there is no self-serve install yet — and rather than publish setup steps for something you cannot install, this page says so. Enterprise features are additive; Local is not a locked demo and is never gated behind signup.
AIWatcher Local is an early release. The local workflow is usable today, but hook coverage depends on what each AI tool exposes, and the UI is moving quickly.
We’re working with a small number of design partners on AIWatcher Enterprise in 2026.
We reply within 48 hours