A collection of plug-and-play bash hook scripts for Claude Code to manage agent persistence, tool failure recovery, and output verification.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agent-hooks
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agent-hooks using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Agent Hooks?
Agent Hooks is a comprehensive suite of lifecycle scripts designed specifically for the Claude Code CLI environment. These scripts solve three critical problems in autonomous agent workflows: premature stopping during complex tasks, infinite loops caused by repeated tool failures, and speculative completion claims where the agent assumes a task is done without sufficient evidence. As a part of the Openclaw Skills ecosystem, these hooks allow developers to inject custom logic into the Stop, PreToolUse, and PostToolUse phases of an agent's lifecycle.
By utilizing these hooks, you can ensure that your AI agent remains persistent on long-running tasks while maintaining safety valves to prevent resource waste. The toolkit includes the Ralph engine for execution management, a doubt gate for linguistic verification, and automated diagnostic triggers that run immediately after code edits.
Agent Hooks Use Cases
- Preventing an agent from stopping early during multi-step refactoring projects.
- Breaking out of tool-retry death loops where the agent repeatedly attempts the same failing command.
- Enforcing evidence-based reporting when an agent uses speculative language like probably or might.
- Running automated linting or type-checking immediately after the agent modifies source files.
How Agent Hooks Works
- The user registers specific bash scripts within the Claude Code configuration file (~/.claude/settings.json).
- During execution, Claude Code triggers these scripts at specific lifecycle points, such as before a tool is used or when the agent attempts to stop.
- The script receives session data and tool context via stdin in JSON format.
- The script logic analyzes the input, such as checking for repeated errors or identifying speculative keywords in the agent's transcript.
- The script outputs a decision JSON to stdout, instructing Claude Code to either continue, block the action, or inject a specific prompt to redirect the agent.
Agent Hooks Setup
To install these Openclaw Skills, you must map the script paths in your Claude configuration file:
# Edit your ~/.claude/settings.json
# Example for adding the Ralph stop hook and tool tracker:
{
"hooks": {
"Stop": [{
"hooks": [{"type": "command", "command": "bash /path/to/scripts/ralph-stop-hook.sh"}]
}],
"PostToolUseFailure": [{
"hooks": [{"type": "command", "command": "bash /path/to/scripts/tool-error-tracker.sh", "async": true}]
}]
}
}
Ensure that the NC_SESSION environment variable is set to allow the scripts to track state across sessions.
Agent Hooks Data Schema & Taxonomy
The skill manages state using a structured file hierarchy within the user's home directory. This organization allows for crash recovery and session persistence.
| Data Type | Location / Format | Description |
|---|---|---|
| Session State | $HOME/.../shared-context/sessions/<id>/ |
Stores iteration counts, error logs, and cancel signals. |
| Input Schema | Standard JSON (stdin) | Contains tool_name, tool_input, and session_id. |
| Output Schema | Standard JSON (stdout) | Decisions like {"continue": true} or {"decision": "block", "reason": "..."}. |
| Diagnostic Logs | Script-specific logs | Captures linter and type-checker outputs for the post-edit hook. |
Agent Hooks Advanced Features
- Ralph Engine: A persistence layer with four safety valves to prevent infinite loops during auth failures or timeouts.
- Doubt Gate: A linguistic analysis hook that detects speculative language and forces the agent to provide proof of work.
- Tool Error Advisor: Blocks the same failing command after five attempts, forcing the agent to brainstorm a new approach.
- Async Post-Edit Checks: Automatically triggers diagnostics (like linters) in the background after file edits to catch errors early.
- Multi-Hook Support: Allows chaining multiple Openclaw Skills scripts within a single lifecycle event for complex workflows.
SKILL.md
Loading
Related Openclaw Skills
Young Post Downloader
Automates the retrieval of Young Post Club Spark articles, converting them into professionally formatted PDF documents and syncing them to cloud storage.
Paint Skill
A Python-based drawing utility that enables AI agents to generate and save PNG images using the Pillow library and interactive Tkinter windows.
Baidu Search Engine
A powerful search integration that allows AI agents to perform live web queries and research within the Openclaw Skills framework.
Report-gama
Report-gama is a professional market intelligence system that automates the generation of 15-chapter research reports with real-time data and PDF export capabilities.
Forecast & Valuation Skill
A professional financial forecasting and valuation engine that generates comprehensive 3-statement models, DCF analysis, and comparable company benchmarks.
Limited Info Subagent Skill Verify
A specialized testing utility to verify if an AI skill remains functional when provided with minimal context or sparse instructions.
Featured*
