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. Rate limit 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-Clockwork/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 hierarchy-aware MCP blacklist across all projects (respects per-project .agentihooks.json whitelists)
  9. Prunes orphaned MCP servers from ~/.claude.json
  10. Installs the agentihooks CLI globally via uv tool install --editable .
  11. Restarts sync daemon (always — picks up code changes)
  12. 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. Rate limit display

The statusline automatically shows your Claude Code rate limits on line 3 using native data from Claude Code:

session:53% [1h35m] | weekly:35%

No configuration required – this works out of the box. Color-coded by usage: green < 60%, yellow < 80%, red above.

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    # target a specific path
agentihooks init --local                     # shorthand for --repo . (current directory)
agentihooks init --local --profile coding    # override profile for this project

This reads .agentihooks.json from the project root and generates:

  • .claude/settings.local.json — permissions, env vars, MCP whitelist

Auto-gitignored. The profile chain’s system prompt is rendered into the global ~/.claude/CLAUDE.md; per-project .claude/CLAUDE.local.md is not generated. See Per-Project Configuration for the full guide.

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 the sync daemon, 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.