Installation

Table of contents

  1. 1. Install uv
  2. 2. Clone the repository
  3. 3. Create the dedicated venv
  4. 4. Run the global install
  5. 5. Verify
  6. 6. Configure ~/.agentihooks/.env
  7. 7. (Optional) Console quota display
    1. Install Playwright’s browser
    2. Authenticate and start the daemon
    3. Multi-account quota
    4. Daemon management
    5. Enable the statusline display
  8. Using a specific profile
  9. Using a bundle
  10. Install into a specific project
  11. Standalone MCP server
  12. Custom Claude config directory
  13. Uninstall

1. Install uv

AgentiHooks uses uv for dependency management.

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

2. Clone the repository 

git clone https://github.com/The-Cloud-Clock-Work/agentihooks
cd agentihooks

3. Create the dedicated venv

AgentiHooks uses a fixed venv at ~/.agentihooks/.venv as its canonical Python environment. All hook commands written into ~/.claude/settings.json point to this venv’s Python, so every hook subprocess finds the right packages regardless of which shell, activated venv, or terminal Claude Code is launched from.

uv venv ~/.agentihooks/.venv
uv pip install --python ~/.agentihooks/.venv/bin/python -e ".[all]"

The [all] extra pulls in every optional dependency: boto3, psycopg2, redis, pyyaml, playwright, and others.

Verify:

~/.agentihooks/.venv/bin/python -c "import hooks; print('OK')"

4. Run the global install

Always run the installer from the ~/.agentihooks/.venv Python – the installer bakes sys.executable into every hook command it writes.

agentihooks init

This single command:

  1. Reads profiles/_base/settings.base.json (the canonical settings source)
  2. Merges settings: base -> profile .claude/settings.overrides.json -> OTEL
  3. Substitutes /app placeholders with the real repo path and __PYTHON__ with ~/.agentihooks/.venv/bin/python
  4. Writes ~/.claude/settings.json with hook wiring and tool permissions
  5. Symlinks skills, agents, commands, and rules via 3-layer merge (agentihooks built-in -> bundle global -> profile-specific)
  6. Symlinks ~/.claude/CLAUDE.md to the chosen profile’s CLAUDE.md (at profile root)
  7. Installs MCPs (hooks-utils + bundle .claude/.mcp.json + profile .claude/.mcp.json)
  8. Applies MCP blacklist across all projects
  9. Installs the agentihooks CLI globally via uv tool install --editable .
  10. Auto-starts quota and sync daemons
  11. Writes a managed bashrc block (agentienv function + agenti alias)

The install is idempotent – re-running is safe. Settings are only backed up on the first run.

If you ever recreate the venv or change its location, re-run the installer from the new Python. The hook commands in settings.json will be updated automatically.

5. Verify

Confirm hook commands point to the venv:

grep -o '"command": "[^"]*"' ~/.claude/settings.json | head -3
# Should show: ~/.agentihooks/.venv/bin/python -m hooks

Confirm the MCP server is registered:

cat ~/.claude.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(list(d.get('mcpServers',{}).keys()))"

Start a Claude Code session and verify by asking:

What MCP tools do you have available?

The agent should list tools from agentihooks (e.g., hooks_list_tools, get_env, etc.).

6. Configure ~/.agentihooks/.env

On first install, ~/.agentihooks/.env is seeded from .env.example. Edit it to configure integrations. Minimum recommended settings:

# Redis -- enables burn rate tracking, file read cache, warning edge-triggers
REDIS_URL=redis://:PASSWORD@host:port/0

# Token control
TOKEN_CONTROL_ENABLED=true
TOKEN_WARN_PCT=60
TOKEN_CRITICAL_PCT=80
BASH_FILTER_ENABLED=true
FILE_READ_CACHE_ENABLED=true
MCP_HYGIENE_ENABLED=true
MEMORY_AUTO_SAVE=true

All hooks and the MCP server auto-load this file at import time (plus any ~/.agentihooks/*.env companion files).

7. (Optional) Console quota display

The statusline can show your Anthropic console usage on line 3. Example output:

session:53% [1h] | all:35% resets fri 10:00 am | sonnet:5% resets mon 12:00 am | extra: $40/99 (40%) resets apr 1

This uses a background daemon (scripts/claude_usage_watcher.py) that scrapes claude.ai/settings/usage headlessly via Playwright. Auth uses your real system browser – no Chromium login required.

Install Playwright’s browser 

~/.agentihooks/.venv/bin/python -m playwright install chromium

Authenticate and start the daemon

The quota auth command opens YOUR real browser (Chrome on Windows/WSL via cmd.exe /c start, Safari/Chrome on Mac via open) to claude.ai. You then copy the sessionKey cookie from Chrome DevTools (F12 -> Application -> Cookies -> claude.ai -> sessionKey), paste it when prompted, and the daemon starts automatically.

agentihooks quota auth

The cookie is saved as a Playwright storage state file at ~/.agentihooks/quota-accounts/<name>.json. Headless Chromium is only used for background scraping – your login happens in your real browser.

Multi-account quota

You can authenticate multiple accounts and switch between them:

agentihooks quota auth work          # authenticate as "work"
agentihooks quota auth personal      # authenticate as "personal"
agentihooks quota list               # show all accounts
agentihooks quota switch personal    # switch active account
agentihooks quota restart            # restart daemon with current account
agentihooks quota remove personal    # remove an account

Account credentials are stored at ~/.agentihooks/quota-accounts/<name>.json.

Daemon management 

agentihooks quota            # start background daemon (auto-detaches, PID file, logs)
agentihooks quota status     # print last known quota JSON
agentihooks quota logs       # tail -f daemon log (~/.agentihooks/logs/quota-watcher.log)
agentihooks quota stop       # kill daemon

The daemon writes a PID file at ~/.agentihooks/quota-watcher.pid and logs to ~/.agentihooks/logs/quota-watcher.log.

Enable the statusline display

Add to ~/.agentihooks/.env:

CLAUDE_USAGE_FILE=~/.agentihooks/claude_usage.json
# CLAUDE_USAGE_STALE_SEC=300   # data older than this shows "stale" (default)
# CLAUDE_USAGE_POLL_SEC=60     # daemon poll interval (default)

The statusline will then display quota information on line 3, color-coded by usage thresholds.

Using a specific profile 

agentihooks init --profile coding

Or use the AGENTIHOOKS_PROFILE environment variable:

export AGENTIHOOKS_PROFILE=coding
agentihooks init

List available profiles:

agentihooks --list-profiles

Using a bundle

Link your external customization bundle on first install:

agentihooks init --bundle ~/dev/my-tools

After linking, future runs of agentihooks init will use the linked bundle automatically. See Bundles for details.

Install into a specific project

To wire the MCP server and profile config for a single project:

agentihooks init --repo ~/dev/my-project

This writes project-level configuration into the target project directory.

Standalone MCP server

Run the MCP server directly (useful for testing):

# All 26 tools
~/.agentihooks/.venv/bin/python -m hooks.mcp

# Specific categories only
MCP_CATEGORIES=aws,utilities ~/.agentihooks/.venv/bin/python -m hooks.mcp

Custom Claude config directory

By default the installer targets ~/.claude. If $HOME differs from where Claude Code actually stores its config, set CLAUDE_CODE_HOME_DIR to the correct home-directory root – agentihooks appends .claude automatically:

CLAUDE_CODE_HOME_DIR=/shared/home \
  agentihooks init
# installs into /shared/home/.claude/

The legacy AGENTIHOOKS_CLAUDE_HOME still works and points directly at the .claude directory (no .claude appended). Priority order:

  1. CLAUDE_CODE_HOME_DIR (home-dir root, .claude appended)
  2. AGENTIHOOKS_CLAUDE_HOME (direct .claude path, legacy)
  3. ~/.claude (default)

Uninstall

To remove everything agentihooks installed:

agentihooks uninstall

Add --yes to skip the confirmation prompt.

This removes: settings, all symlinks, CLAUDE.md, MCP server registrations, stops all daemons (quota + sync), removes the bashrc block, and uninstalls the CLI. User data in ~/.agentihooks/state.json is preserved.

To fully remove all user data, delete ~/.agentihooks manually with rm -rf ~/.agentihooks.