AgentiHooks: Hook System and MCP Tool Server for Claude Code Agents

Core Points: AgentiHooks provides a complete hook event system and 26 MCP tools for Claude Code, achieving 30-50% token consumption optimization via the Token Control Layer, making it a powerful infrastructure for building complex AI workflows.

This thread will cover the following in separate floors: Background Challenges, Architecture Design, Token Optimization, Detailed Hook Events, MCP Tool Ecosystem, Installation & Configuration, Security Design, and Summary & Outlook.

With the popularity of AI coding assistants like Claude Code, developers face many challenges when relying on AI to complete complex tasks: How to monitor token consumption to avoid cost overruns? How to prevent repeated reading of the same file? How to block dangerous operations?

The traditional single-interaction mode cannot meet the fine-grained control needs of multi-step complex tasks (file reading/writing, command execution, tool calls, etc.). AgentiHooks was created to solve these problems, providing a hook system and MCP tool server to deeply customize Claude Code's behavior and build safer, more efficient AI workflows.

AgentiHooks' architecture consists of three layers:

1. Hook Event Layer: Intercepts 10 lifecycle events of Claude Code (e.g., SessionStart, PreToolUse, PostToolUse) and executes custom logic (sensitive information scanning, output truncation, etc.).
2. Status Bar Layer: Displays session status in real time (context fill rate, token consumption rate, cumulative cost, cache hit rate, Git branch, etc.).
3. MCP Tool Layer: Provides 26 reusable tools across 8 categories (AWS services, email sending, message queues, etc.) to expand the boundaries of AI capabilities.

The Token Control Layer reduces token consumption by 30-50% through multiple strategies:

• Output Truncation: Automatically truncates lengthy output from bash commands, retaining key information.
• File Reading Deduplication: Records read files to avoid repeated reading in the same session.
• Context Window Monitoring: Issues warnings when approaching the token limit.

In practical use, each session can save 100,000 to 250,000 tokens, significantly reducing costs for teams with high-frequency usage.

AgentiHooks' 10 hook events cover the entire lifecycle of a Claude Code session:

• SessionStart: Injects context and reminds users of MCP tool usage notes.
• PreToolUse: Scans for sensitive information (passwords, API keys), blocks dangerous operations; injects memory of previous tool errors.
• PostToolUse: Truncates overly long output, records read files, and captures execution errors.
• Stop: Scans for session errors, parses performance metrics, and saves important memories.
• SessionEnd: Saves session records and cleans up temporary states.

Other events (SubagentStop, UserPromptSubmit, etc.) provide extension points for specific scenarios.

AgentiHooks provides 26 MCP tools across 8 categories (selectively loadable via environment variables):

• AWS: 4 tools (configuration management, account discovery).
• Email: 2 tools (SMTP sending of text/HTML/Markdown emails).
• Messaging: 3 tools (AWS SQS operations, Webhook calls).
• Storage: S3 upload functionality.
• Database: 3 tools (DynamoDB write, PostgreSQL insert/execute).
• Computation: Lambda function calls (synchronous/asynchronous).
• Observability: 7 tools (timer, metric collection, log tracing, etc.).
• General: 3 tools (Markdown writing, environment variable query, tool list display).

Installation: Use the uv package manager. Steps include cloning the repository, creating a virtual environment, installing dependencies, and running an idempotent installation script (writing hook configurations, creating symbolic links, merging MCP configurations).

Configuration: Supports global configuration (affects all sessions) and project-level configuration (only applies to specific projects).

Security:

• Secrets Scanning: Detects sensitive information during the PreToolUse phase and blocks dangerous tool calls.
• Tool Restrictions: Fine-grained control over resource access scope via the MCP permission system.
• Audit Logs: Records events such as tool calls, configuration changes, and errors for auditing and troubleshooting.

AgentiHooks provides Claude Code users with a powerful and customizable agent infrastructure, solving practical pain points through the hook system, Token Control Layer, and MCP tools.

As part of the agenticore ecosystem, AgentiHooks evolves in synergy with agenticore, allowing developers to fork and customize workflows.

With the popularity of AI coding assistants, such infrastructure tools will become increasingly important, making AI usage safer, more controllable, and efficient—an ideal choice for teams and developers who use Claude Code deeply.