AIWatcher Local

Private guardrails for AI coding work. AIWatcher helps you review risky prompts before they run, notice expensive or stuck sessions while they are active, and prove whether the work became useful code afterwards.

It works with local history from tools such as Claude Code, Codex, and Cursor. No account is required. No cloud upload happens by default. No LLM call happens unless you explicitly configure optional AI Assist.

Contents

• What You Get
• First Look
• Why Developers Use It
• Install
• If Install Fails
• First Useful Checks
• Optional Hooks
• Clone The Codebase
• Keep AIWatcher Updated
• What It Reads
• Common Commands
• Project Status
• AIWatcher Local and Enterprise
• Contributing
• License

What You Get

In the first few minutes, AIWatcher gives one developer a local control loop for AI coding work:

• Before the run: review risky or over-broad prompts before an agent spends context.
• During the run: notice loops, context pressure, idle sessions, and work waiting on you.
• After the run: connect AI sessions to commits, outcomes, receipts, and improvement signals.

No signup is required, and the default install keeps data on your machine.

First Look

The Home view shows active AI work, context pressure, update status, and the small Companion control. Plan helps narrow risky prompts before an agent spends context:

Why Developers Use It

• Catch expensive prompts early: preflight broad, vague, destructive, or high-context work before an AI agent starts spending tokens.
• Stay out of runaway sessions: get local nudges for context pressure, loops, long-running work, and sessions waiting on you.
• Start fresh without losing the plot: create a compact Fresh Start brief for continuing work in a new session.
• Prove what was worth it: connect local AI sessions to commits, outcomes, receipts, and API-equivalent usage.
• Keep trust visible: label what is automatic, what is inferred, and what the current tool surface cannot prove.

Install

Install AIWatcher Local as an isolated command-line application with pipx. Use Python 3.10+ for the recommended path. AIWatcher also supports Python 3.9 when installed from source. Python 2 is not supported.

Pick one path and ignore the rest.

One-Line Install

Use this when Python 3.10+ and pipx are already installed.

macOS or Linux:

pipx install aiwatcher-local && ~/.local/bin/aiwatcher setup && ~/.local/bin/aiwatcher start --open-ui

Windows PowerShell:

py -3 -m pipx install aiwatcher-local; & "$env:USERPROFILE\.local\bin\aiwatcher.exe" setup; & "$env:USERPROFILE\.local\bin\aiwatcher.exe" start --open-ui

Run pipx ensurepath later if you want to type aiwatcher without the full path in a new terminal.

Missing Prerequisites

Use this if you are not sure what is already installed. These commands check first and only install missing prerequisites.

macOS:

command -v brew >/dev/null || { echo "Install Homebrew first: https://brew.sh"; exit 1; }
command -v python3 >/dev/null || brew install python
command -v pipx >/dev/null || brew install pipx
if [ -x ~/.local/bin/aiwatcher ]; then
  pipx upgrade aiwatcher-local
else
  pipx install aiwatcher-local
fi
~/.local/bin/aiwatcher setup
~/.local/bin/aiwatcher start --open-ui

Ubuntu or Debian:

if ! command -v python3 >/dev/null || ! command -v pipx >/dev/null; then
  sudo apt update
fi
command -v python3 >/dev/null || sudo apt install -y python3 python3-pip
command -v pipx >/dev/null || sudo apt install -y pipx
if [ -x ~/.local/bin/aiwatcher ]; then
  pipx upgrade aiwatcher-local
else
  pipx install aiwatcher-local
fi
~/.local/bin/aiwatcher setup
~/.local/bin/aiwatcher start --open-ui

For other Linux distributions, install Python 3.10+ and pipx with your package manager, then use the one-line install.

Windows PowerShell:

if (-not (Get-Command py -ErrorAction SilentlyContinue)) {
  winget install Python.Python.3.12
  Write-Host "Open a new PowerShell after Python installs, then rerun these commands."
  exit
}
py -3 --version
py -3 -m pipx --version *> $null
if ($LASTEXITCODE -ne 0) { py -3 -m pip install --user pipx }
$aiwatcher = "$env:USERPROFILE\.local\bin\aiwatcher.exe"
if (Test-Path $aiwatcher) {
  py -3 -m pipx upgrade aiwatcher-local
} else {
  py -3 -m pipx install aiwatcher-local
}
& $aiwatcher setup
& $aiwatcher start --open-ui

To make the shorter command work in future terminals, run:

pipx ensurepath

Then open a new terminal and use:

aiwatcher setup
aiwatcher start --open-ui

setup detects local AI tools and prints copy/paste next steps. It is not an interactive menu, so you do not need to type a number. start --open-ui starts the browser Console, the background Companion, and the small floating control on macOS and Windows.

If Install Fails

Use the row matching the error you saw.

First Useful Checks

aiwatcher doctor
aiwatcher hook-status
aiwatcher preflight "Refactor the checkout flow and delete old auth secrets" --tool codex --cwd "$(pwd)"

• doctor shows which local tools AIWatcher can read.
• hook-status proves whether a tool actually invoked AIWatcher.
• preflight gives value immediately, even before hooks are installed.

Optional Hooks

Hooks let AIWatcher act before the AI tool spends context. Install only the ones you use:

aiwatcher install-claude-hook --write --scope user --gate
aiwatcher install-codex-hook --write --scope user --gate
aiwatcher install-cursor-hook --write --scope user --gate

For Claude Code CLI, AIWatcher can also review risky shell commands before they run:

aiwatcher install-claude-command-gate --write --scope user

Then send a small test prompt in your AI tool and verify:

aiwatcher hook-status

If a surface does not invoke hooks, use the Console or Companion Plan flow to preflight prompts manually. AIWatcher does not claim silent protection on tool surfaces that do not expose a verified lifecycle hook.

Clone The Codebase

Clone only if you want to contribute, inspect code locally, or use the dashboard's source-update flow. Most users should use the pipx path above.

The source clone path creates a project-local virtual environment, so it does not modify your Homebrew, system, or Windows Python packages.

macOS or Linux:

git clone https://github.com/ai-watcher/aiwatcher-local.git
cd aiwatcher-local
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m aiwatcher_cli setup
python -m aiwatcher_cli start --open-ui

Windows PowerShell:

git clone https://github.com/ai-watcher/aiwatcher-local.git
cd aiwatcher-local
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
python -m aiwatcher_cli setup
python -m aiwatcher_cli start --open-ui

The key detail is python -m pip inside the virtual environment. Do not use python -m pip3.

Keep AIWatcher Updated

For source clones, the top-bar update badge checks GitHub only when clicked unless you turn on automatic checks in Settings. Applying an update is a second explicit step from Settings.

The recommended install/update path is:

pipx install aiwatcher-local
pipx upgrade aiwatcher-local

Users of the original aiwatcher-cli 0.1.0 package should migrate once:

pipx uninstall aiwatcher-cli
pipx install aiwatcher-local

Maintainers should use docs/RELEASE.md before publishing.

What It Reads

AIWatcher reads local evidence that AI tools already store on your machine.

AIWatcher stores local receipts, hashes, decisions, outcomes, and metadata. It does not persist raw prompt text from Prompt Gate decisions. Optional AI Assist can send bounded prompt/source context only when you configure it and choose a workflow that uses it.

See docs/AIWATCHER_LOCAL.md for the full privacy and coverage boundary.

Laptop Footprint

AIWatcher is a Python package with static dashboard assets, not a native background daemon. It does nothing in the background until you run aiwatcher start, aiwatcher companion start, or install login autostart.

Measured from this repo on macOS with Python 3.14:

On the measured machine, a Companion startup scan over recent local AI history briefly used more CPU and memory, then settled back near idle. Larger local Claude/Codex/Cursor histories can make that scan peak higher. The default Companion interval is 30 seconds, and you can stop it any time:

aiwatcher companion stop

Common Commands

Full command reference: docs/CLI.md.

Project Status

AIWatcher Local is an early open-source release. The local-first workflow is usable today, but hook coverage depends on what each AI tool exposes on your machine. The UI is moving quickly, so screenshots and docs may change while the core privacy boundary stays stable.

Useful next reads:

• Product and validation notes
• CLI reference
• HTTP API reference
• Release checklist

AIWatcher Local and Enterprise

AIWatcher Local is the open-source, developer-controlled loop for one machine. It should be useful without signup, a cloud account, or a team admin.

AIWatcher Enterprise adds team policy, budgets, approvals, audit evidence, SSO/RBAC, managed deployment, central retention, org dashboards, and production-agent governance. Enterprise features are additive; Local is not a locked demo.

The Apache-2.0 license covers this code. It does not grant rights to the AIWatcher name, logo, hosted service, or Enterprise control plane. Learn more at https://www.getaiwatcher.com.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

For security reports, use SECURITY.md. Please follow the Code of Conduct.

License

Apache License 2.0