agentihooks 1.6.1

Hook system and MCP tool server for Claude Code agents

agentihooks

The production harness for Claude Code. Turn Claude Code into a managed fleet — with profiles, guardrails, context intelligence, and real-time broadcast messaging across every active session.

Full documentation: the-cloud-clock-work.github.io/agentihooks

---

The Four Pillars

graph LR
    A["Identity<br/>Who your agents are"] --> E["AgentiHooks"]
    B["Guardrails<br/>What keeps them safe"] --> E
    C["Context Intelligence<br/>What keeps them sharp"] --> E
    D["Fleet Command<br/>Talk to your entire fleet"] --> E

Pillar 1: Identity — Who your agents are

One command transforms your agent's entire personality, permissions, and toolset.

agentihooks init --profile coding,colt     # chain profiles
agentihooks settings-profile admin          # swap permissions without touching persona
agentihooks init --local --profile infra    # per-repo identity

• Profile chaining — comma-separated profiles merge left-to-right (rules accumulate, settings deep-merge, CLAUDE.md concatenates)
• Two-axis model — persona (rules/CLAUDE.md) and settings (permissions/MCP) are independent layers
• Bundle system — external repos of profiles, auto-discovered via agentihooks bundle link
• Built-in profiles: default (auto mode), coding (acceptEdits), admin (bypassPermissions)

Full docs: Identity

Pillar 2: Guardrails — What keeps them safe

8+ guardrails active by default. Your fleet operates within boundaries you set.

Guardrail	What it does
Secrets scanning	Detects credentials in prompts and tool inputs
Retry breaker	Soft warning → hard block on repeated failures
Branch guard	Protects main/master from accidental pushes
Version guard	Blocks AI from editing version fields in manifests
CLAUDE.md sanity	Prevents bloat past configurable line limit
MCP surface area	Warns when too many tools are loaded
Bash output filter	Truncates verbose output to save tokens
File read dedup	Blocks redundant re-reads of unchanged files

Full docs: Guardrails

Pillar 3: Context Intelligence — What keeps them sharp

LLMs lose focus on early instructions as conversations grow. AgentiHooks defeats attention decay.

• Context refresh — re-injects rules every 20 turns and CLAUDE.md every 40 turns
• Priority frontmatter — critical rules load first within the 8000-char budget
• Token compression — 4 levels (off/light/standard/aggressive) with safety-preserving protection mask
• Tool memory — past errors injected so agents don't repeat mistakes
• Context audit — tracks what's being injected and how much budget is used

# In ~/.agentihooks/.env
CONTEXT_REFRESH_COMPRESSION=standard    # default
CONTEXT_COMPRESSION_SCOPE=all           # compress all injections

Full docs: Context Intelligence

Pillar 4: Fleet Command — Talk to your entire fleet

No other tool does this. Send messages to every active Claude Code session simultaneously — like a PA system for your AI workforce.

# Manual — full control
agentihooks broadcast "Deploy freeze until 3am" -s alert -t 8h
agentihooks broadcast "STOP ALL WRITES" -s critical -t 15m

# AI-assisted — describe intent in plain English
agentihooks broadcast emit "production incident, all agents stop deploying"
agentihooks broadcast emit "clear all broadcasts"

Severity	Delivery	Default TTL	Use case
info	Once per session	4 hours	Reminders, FYI notices
alert	Every user turn	1 hour	Deploy freezes, degraded services
critical	Every turn + every tool call	30 min	Incidents, immediate stops

emit is sandboxed: Claude Haiku can only run agentihooks broadcast commands — all other tools are disallowed.

Full docs: Fleet Command

---

Quick Start

Requirement: uv must be installed.

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

# 1. Create the dedicated venv and install everything
uv venv ~/.agentihooks/.venv
uv pip install --python ~/.agentihooks/.venv/bin/python -e ".[all]"

# 2. Install hooks + settings + MCP into ~/.claude
agentihooks init

agentihooks init wires hooks into ~/.claude/settings.json, symlinks skills/agents/commands/rules, merges MCP servers into ~/.claude.json, installs the CLI globally, and auto-starts background daemons. Re-run any time — it is idempotent.

Architecture

Claude Code
  |
  |-- Hook Events (stdin JSON) --> python -m hooks --> hook_manager.py
  |     SessionStart, PreToolUse,       |
  |     PostToolUse, Stop, ...         |-- context refresh + compression
  |     (10 events total)              |-- guardrails pipeline
  |                                    |-- broadcast delivery
  |                                    |-- transcript logging
  |
  |-- statusLine (native setting) --> python -m hooks.statusline
  |     pipes JSON on every turn       --> 2-3 line status bar
  |
  +-- MCP Tools --> python -m hooks.mcp --> category modules
        aws, email, messaging,               --> hooks/integrations/*
        database, compute, ...

CLI Reference

# Install / configure
agentihooks init                             # global install with default profile
agentihooks init --profile coding,colt       # chain profiles
agentihooks init --local --profile infra     # per-repo config
agentihooks settings-profile admin           # quick-switch settings layer

# Fleet messaging
agentihooks broadcast "msg"                  # send info broadcast
agentihooks broadcast "msg" -s critical      # critical severity
agentihooks broadcast emit "natural lang"    # AI-assisted
agentihooks broadcast --list                 # active broadcasts
agentihooks broadcast --clear                # clear all

# Launch claude with profile flags
agentihooks claude                           # reads profile.yml -> CLI flags
agenti                                       # alias (after source ~/.bashrc)

# Bundle management
agentihooks bundle link ~/dev/my-tools       # link a bundle
agentihooks bundle pull                      # update linked bundle

# Diagnostics
agentihooks status                           # full system health
agentihooks lint-claude [path]               # CLAUDE.md token cost analysis
agentihooks mcp report                       # MCP surface area

# Daemons
agentihooks daemon start|stop|status|logs
agentihooks quota auth|list|switch|status|stop

# Utilities
agentihooks ignore [path]                    # create .claudeignore
agentihooks --list-profiles                  # available profiles
agentihooks --query                          # active profile name
agentihooks uninstall [--yes]                # remove everything

What init Does

1. Links bundle (if --bundle provided)
2. Merges settings: settings.base.json -> profile overrides -> settings-profile overlay -> OTEL config
3. Symlinks skills, agents, commands, and rules (3-layer merge, additive across chain)
4. Writes CLAUDE.md to ~/.claude/CLAUDE.md
5. Installs MCP servers (hooks-utils + bundle + profile)
6. Applies hierarchy-aware MCP blacklist to all registered projects
7. Prunes orphaned MCP servers
8. Installs CLI globally via uv tool
9. Restarts sync daemon
10. Writes bashrc block (agentienv shell function + agenti alias)

Profiles

Profiles mirror the Claude Code project structure:

profiles/<name>/
|-- CLAUDE.md                    # system prompt (-> ~/.claude/CLAUDE.md)
|-- profile.yml                  # agentihooks metadata + claude flags
+-- .claude/
    |-- settings.overrides.json  # merged into ~/.claude/settings.json
    |-- .mcp.json                # profile MCP servers
    |-- skills/                  # -> ~/.claude/skills/
    |-- agents/                  # -> ~/.claude/agents/
    |-- commands/                # -> ~/.claude/commands/
    +-- rules/                   # -> ~/.claude/rules/

Built-in profiles: default (auto), coding (acceptEdits), admin (bypassPermissions). Bundle profiles are discovered automatically.

3-layer merge: agentihooks built-in -> bundle global .claude/ -> profile-specific .claude/. Applies to skills, agents, commands, rules, and MCP servers.

Profile chaining: agentihooks init --profile coding,colt applies each profile sequentially — hooks append, CLAUDE.md concatenates, rules/skills accumulate additively.

Settings profiles (two-axis model): Control settings independently from persona:

agentihooks init --profile colt --settings-profile admin
agentihooks settings-profile admin           # quick-switch
agentihooks settings-profile --clear         # revert

Hook Events

10 lifecycle events, all handled by python -m hooks:

Event	Key behavior
SessionStart	Register session, inject context, deliver broadcasts, MCP warnings
PreToolUse	Secrets scan, branch/version guard, retry breaker, critical broadcasts
PostToolUse	Bash output filtering, file dedup, tool error recording
UserPromptSubmit	Secrets scan, context refresh, broadcast delivery
Stop	Transcript scan, auto-memory, cost metrics
SessionEnd	Deregister session, clear caches, log summary
SubagentStop	Subagent transcript logging
Notification	Log notifications
PreCompact	Log before compaction
PermissionRequest	Log permission requests

Configuration

All configuration in .env files in ~/.agentihooks/. Key variables:

Variable	Default	Description
CONTEXT_REFRESH_COMPRESSION	standard	Token compression level
CONTEXT_COMPRESSION_SCOPE	refresh	Scope: refresh or all
CONTEXT_REFRESH_INTERVAL	20	Re-inject rules every N turns
BROADCAST_ENABLED	true	Fleet messaging master switch
BROADCAST_CRITICAL_ON_PRETOOL	true	Critical alerts on every tool call
TOKEN_CONTROL_ENABLED	true	Token control layer master switch
BASH_FILTER_ENABLED	true	Truncate verbose bash output
FILE_READ_CACHE_ENABLED	true	Block redundant file re-reads

Complete table: Configuration Reference

Per-Repo Config

agentihooks init --local                     # per-repo config for current directory
agentihooks init --local --profile coding    # override profile for this project

Reads .agentihooks.json from repo root and generates .claude/settings.local.json + .claude/CLAUDE.local.md.

Portability

Everything user-specific lives in ~/.agentihooks/. To move to a new machine:

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

Related Projects

Project	Description
agenticore	Claude Code runner and orchestrator
agentibridge	MCP server for session persistence and remote control

License

See LICENSE for details.