agentihooks

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

Full documentation: the-cloud-clockwork.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,anton     # chain profiles
agentihooks settings-profile admin          # swap permissions without touching persona

• 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)
• Live rule refresh — agentihooks refresh-rules pushes rule updates into every running Claude session without restart. One-shot per session, session-snapshotted so new sessions don't re-consume.

Full docs: Identity

Pillar 2: Guardrails — What keeps them safe

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

Full docs: Guardrails

Pillar 3: Context Intelligence — What keeps them sharp

LLMs lose focus on early instructions as conversations grow. AgentiHooks keeps the highest-signal context live in the recent window.

• Token compression — 4 levels (off/light/standard/aggressive) with safety-preserving protection mask, applied to injected banners and tool output
• Tool memory — past errors injected so agents don't repeat mistakes
• Brain adapter — pluggable source that pumps knowledge (hot arcs, operational memory) into agents via broadcast channels
• 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. Now with channels for targeted delivery — subscribe agents to topics, and only the right sessions hear the right messages.

# 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"

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-Clockwork/agentihooks
cd agentihooks

# 1. Create a venv next to the repo (or its parent) and install everything
uv venv .venv
uv pip install --python .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, and installs the CLI globally. Re-run any time — it is idempotent.

Architecture

Claude Code
  |
  |-- Hook Events (stdin JSON) --> python -m hooks --> hook_manager.py
  |     SessionStart, PreToolUse,       |
  |     PostToolUse, Stop, ...         |-- brain + enforcement drumbeat
  |     (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
        channels, enforcement                --> hooks/mcp/*
        stdio by default; sse / streamable-http for clients
        that filter stdio MCP servers out -- see docs/hooks/mcp-transport.md

CLI Reference

# Install / configure
agentihooks init                             # global install with default profile
agentihooks init --profile coding,anton       # chain profiles
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 --dangerously-skip-permissions
agentihooks claude                           # bypassPermissions + your extra args
agenti                                       # alias (after source ~/.bashrc)

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

# Link an external profile dir into the chain.
# Chain edits span EVERY installed target (claude + codex + copilot) so they
# cannot silently diverge; --for-target narrows to one. unlink is always global —
# it de-registers the profile, so leaving another target naming it would
# make that chain unresolvable.
agentihooks link-profile link ~/dev/brain-profile     # auto-appends to chain + re-installs
agentihooks link-profile link ~/dev/brain --name br   # disambiguate name on collision
agentihooks link-profile link ~/dev/x --for-target copilot  # copilot's chain only
agentihooks link-profile list                         # show all linked external profiles
agentihooks link-profile unlink brain-profile         # remove from chain + sweep symlinks

# Broadcast channels — subscriptions are env-driven via AGENTIHOOKS_BASE_CHANNELS
# (set in profile's settings.overrides.json env block; override per-repo via
# .claude/settings.local.json env, or per-container via launch ENV)
agentihooks channel publish brain "msg"      # publish to a channel
agentihooks channel list                     # active channels + message counts

# Brain adapter (knowledge injection)
agentihooks brain status                     # source type, entries, refresh state
agentihooks brain refresh                    # force re-read + republish

# Live rule refresh (push rule updates into running sessions)
agentihooks refresh-rules --dry-run          # preview payload + target session IDs
agentihooks refresh-rules                    # one-shot push to all alive sessions
agentihooks refresh-rules --clear            # cancel a pending marker

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

# hooks-utils daemon (network transport only — see docs/hooks/mcp-transport.md)
agentihooks mcp status                       # config vs. reality; 0 ok, 1 stopped, 2 diverged
agentihooks mcp start                        # once per boot where there is no systemd
agentihooks mcp restart
agentihooks mcp stop

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

# Self-update — upgrades the install this command runs from
agentihooks update                           # compare against PyPI, upgrade if newer
agentihooks update --check                   # report only, install nothing
agentihooks update --source <index-url>      # upgrade from a custom package index

update resolves how this copy was installed — venv/pip, uv tool, pipx, or an editable checkout — and upgrades that one. An editable install is left alone; update it with git pull in the checkout.

What init Does

1. Links bundle (if --bundle provided)
2. Merges settings in the target's own format: _base/<target base> -> bundle overrides -> profile overrides -> settings-profile overlay
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. Reconciles MCP servers — removes ones agentihooks installed on a prior run but that are no longer in any profile/bundle source (servers you added by hand are preserved)
7. Installs CLI globally via uv tool
8. Writes bashrc block (agentienv shell function + agenti alias)

Under a network MCP_TRANSPORT, step 5 also renders the systemd unit and starts the hooks-utils daemon — restarting it unconditionally, since init has just rewritten the url and possibly the port and a running process carries neither. That interrupts every Claude Code session on the machine for about a second, because the install is global. On a stdio install no daemon exists and none of this runs.

Per-repo init (--repo / --local) and .agentihooks.json were removed 2026-05-07. agentihooks init is global-only.

Profiles

Profiles mirror the Claude Code project structure:

profiles/<name>/
|-- CLAUDE.md                    # system prompt (-> ~/.claude/CLAUDE.md)
|-- .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/
|-- .codex/                      # optional, codex-native
|   +-- config.overrides.toml    # merged into ~/.codex/config.toml
+-- .copilot/                    # optional, copilot-native
    |-- settings.overrides.json  # merged into ~/.copilot/settings.json
    +-- mcp-config.overrides.json

Content (skills/agents/commands/rules/CLAUDE.md) is authored once in `.claude/`
and re-projected to every target. SETTINGS and MCP are authored per target, in
that target's own file format — a profile ships only the target dirs it cares
about.

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,anton 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 anton --settings-profile admin
agentihooks settings-profile admin           # quick-switch (every installed target)
agentihooks settings-profile admin --for-target codex   # one target only
agentihooks settings-profile --clear         # revert

Each target reads settings authored in its OWN format: claude settings.overrides.json, codex config.overrides.toml, copilot settings.overrides.json (plus mcp-config.overrides.json). An earlier design translated one Claude document into each target, but that could carry only permissions.defaultMode and left every target-native capability — codex's model_reasoning_effort, copilot's effortLevel and per-server MCP tool allowlists — unreachable from a bundle. The settings layer is meaningful on all three targets, so settings-profile applies to all of them by default.

Install Targets

AgentiHooks installs into three agent CLIs. One bundle, three projections:

agentihooks init --profile anton --target claude    # ~/.claude   (default)
agentihooks init --profile anton --target codex     # ~/.codex
agentihooks init --profile anton --target copilot   # ~/.copilot
agentihooks doctor --target copilot                 # per-target health check

The bundle only ever ships Claude-shaped content; each target's adapter (scripts/targets/<name>_target.py) re-projects it. Details, including each CLI's hook contract and the evidence behind it: CODEX-COMPAT, COPILOT-COMPAT.

Hook Events

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

Configuration

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

Complete table: Configuration Reference

Hook output and the 10K cap

Claude Code injects hook stdout (and any hookSpecificOutput.additionalContext) into the model's context up to a documented 10,000-character hard cap. Beyond the cap, the harness silently writes the body to a temp file and the model receives a filepath instead of the content. If your SessionStart or UserPromptSubmit injection accumulates above 10K, it is silently lost.

AgentiHooks does not enforce a default cap — full content ships through so agents have the most context possible. To audit what each event actually emits and whether anything is over the limit, run:

agentihooks doctor --debug-hook

If you stack many injections (CI manifesto + brain feed + amygdala + custom overlays + tool memory), use the *_MAX_BYTES knobs above to cap the biggest contributors and leave headroom for the rest.

Remote brain quickstart

Nothing to copy by hand. agentihooks reads the brain's own config file — $AGENTIBRAIN_HOME/.env, default ~/.agentibrain/.env, the same file that feeds the kernel's docker compose — and adopts BRAIN_URL, KB_ROUTER_TOKEN and the brain settings agentibrain install writes there (BRAIN_ENABLED, BRAIN_SOURCE_PATH, AMYGDALA_ENABLED, AMYGDALA_SIGNAL_PATH, BRAIN_WRITER_ENABLED, BRAIN_WRITER_MAX_MARKERS, BRAIN_WRITER_OUTBOX) from it. One home each, so nothing goes stale in a copy. Only those keys are adopted; that file's database, object-store and provider credentials never enter a session's environment.

On the machine hosting the brain, agentibrain install writes that file. On a machine that only talks to one:

agentibrain install --brain-url http://<your-brain-api-host>:8103 --token <bearer>

That writes the same file locally and skips the stack and the vault, since both belong to the brain's own machine. To repoint it later, edit ~/.agentibrain/.env — there is nothing to reinstall.

Restart your Claude Code session. The hook stack fetches hot arcs and active signals on every prompt and injects them as broadcast banners. No profile install required — works alongside any profile, or none.

Overriding still works the way it always did: a value set in ~/.agentihooks/*.env outranks the discovery, and the process environment outranks both. AMYGDALA_ENABLED remains an opt-in you set yourself.

Portability

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

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

Related Projects

License

See LICENSE for details.