AgentiHooks

Lifecycle hooks and 26 MCP tools for Claude Code — install once, work everywhere.

Get Started Cost Management View on GitHub

Install

pip install agentihooks

Then wire everything into Claude Code in one command:

agentihooks init

That’s it. Hooks are active and 26 MCP tools are registered the next time you start claude.

Save tokens. Spend less. Ship more.

AgentiHooks targets 30–50% token reduction in agentic sessions. Every feature is on by default — zero configuration required.

What burns your tokens	How AgentiHooks fixes it	Savings
`docker logs` dumps 3000 lines into context	Bash output filtering — auto-truncates verbose output	5K–50K tokens/cmd
Claude re-reads the same file 4 times	File read dedup — blocks unchanged re-reads	2K–20K tokens/read
26 MCP tool schemas loaded every turn	Lazy loading — schemas expand only when used	~79K tokens/session
Context hits 100%, session resets, all work lost	Threshold warnings — alerts at 60% and 80%	Entire session
No visibility into spend	Live statusline — cost, burn rate, cache ratio every turn	Prevents waste
Hit weekly quota mid-task	Quota monitor — plan usage on your statusline	Prevents limit hits

The result: Your weekly quota lasts longer. Sessions run deeper before compaction. You see exactly where every token goes.

Full cost management guide →

Choose a profile

Profiles set the agent’s personality and tool permissions. The default profile works for most people.

# See what's available
agentihooks init --list-profiles

# Install with a specific profile
agentihooks init --profile coding

# Check which profile is active
agentihooks init --query

Load your secrets — the `agentienv` shell function

Claude Code expands ${VAR} in MCP configs from its own process environment. The cleanest way to get secrets into that environment is the agentienv shell function:

# One-time setup — writes a managed block to ~/.bashrc
agentihooks init

# Reload your shell
source ~/.bashrc

agentienv is now auto-called on every new shell — your vars load automatically. You only need to call it manually if you add new env files mid-session:

agentienv        # reload vars after adding a new *.env file
claude           # inherits all your vars

All ${VAR} placeholders in MCP server configs resolve automatically.

Restrict which tools load

By default all 26 tools across all 8 categories are active. Use environment variables in the MCP server’s env block (inside ~/.claude.json) to cut that down.

Restrict by category — only load the categories you need:

"env": {
  "MCP_CATEGORIES": "aws,utilities"
}

Valid category names (comma-separated, any order):

aws  email  messaging  storage
database  compute  observability  utilities

Restrict to specific tools — allowlist exact tool names within the loaded categories:

"env": {
  "MCP_CATEGORIES": "aws,utilities",
  "ALLOWED_TOOLS": "aws_get_profiles,aws_get_account_id,hooks_list_tools"
}

ALLOWED_TOOLS is an allowlist — only the tools you name will be active. Tools not in the list are removed at server startup.

Where to edit: open ~/.claude.json, find the hooks-utils server under mcpServers, and update its env block. Restart Claude Code for the change to take effect.

Verify what’s active: ask Claude Code to call hooks_list_tools() — it returns the exact set of loaded categories and tool names.

Per-project MCP tools

Don’t want a global install? Wire the MCP server into a single project instead:

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

This writes a .mcp.json directly into the project directory.

Add more MCP servers

Drop .json files with a mcpServers key into ~/.agentihooks/, then use the interactive MCP manager:

# List available MCP files
agentihooks mcp

# Two-stage install: pick a file, then pick which servers to install
agentihooks mcp install

# Two-stage uninstall: pick a file, then pick which servers to remove
agentihooks mcp uninstall

# Install a specific file directly (all servers, no prompting)
agentihooks mcp add /path/to/.mcp.json

# Re-apply all installed files after edits
agentihooks mcp sync

Registered files are tracked in ~/.agentihooks/state.json and re-applied automatically on every agentihooks init run.

Fork & extend

AgentiHooks is a platform, not just a tool. Fork the repo and you immediately inherit:

The full hook lifecycle (SessionStart → Stop) wired into Claude Code
26 MCP tools across 8 categories, ready to use or filter down
Profile system — swap agent personality and permissions with one flag
Install scripts, settings management, and credential loading

Add your own tools in three steps:

Create hooks/mcp/mytools.py with a register(server) function
Add "mytools": "hooks.mcp.mytools" to _registry.py
Run agentihooks init — your tools are live

Add your own profile:

Create a directory under profiles/<name>/ with profile.yml, .mcp.json, and .claude/CLAUDE.md. Run agentihooks init --profile <name>.

Stay merge-friendly:

Your additions live in new files and new directories. Existing files are untouched. When you pull upstream changes the diff is clean.

Full extension guide → Extending AgentiHooks

Uninstall

agentihooks uninstall        # prompts for confirmation
agentihooks uninstall --yes  # scripting / no prompt

User data in ~/.agentihooks/ (logs, memory, state) is left in place. Remove it manually if you want a full reset:

rm -rf ~/.agentihooks

What you get


Cost management	Output filtering, read dedup, lazy loading, burn rate tracking, quota monitoring — 30–50% fewer tokens
Lifecycle hooks	Auto-log transcripts, inject session context, save memory on stop
26 MCP tools	AWS, email, SQS, S3, DynamoDB, PostgreSQL, observability, and more
Profiles	Swap agent personality and permissions with one flag
`agentienv` shell function	Clean, shell-native secret loading — auto-called on every new shell, no wrapper scripts

Full details in the docs.

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

Built by The Cloud Clock Work · MIT License