Use this file to discover all available pages before exploring further.
Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior.With hooks, you can:
Create a hooks.json file. You can create it at the project level (<project>/.firebender/hooks.json) or in your home directory (~/.firebender/hooks.json). Project-level hooks apply only to that specific project, while home directory hooks apply globally.
User hooks (~/.firebender/)
Project hooks (.firebender/)
For user-level hooks that apply globally, create ~/.firebender/hooks.json:
Note: Project hooks run from the project root, so use .firebender/hooks/format.sh (not ./hooks/format.sh).Create your hook script at <project>/.firebender/hooks/format.sh:
#!/bin/bash# Read input, do something, exit 0cat > /dev/nullexit 0
Make it executable:
chmod +x .firebender/hooks/format.sh
Restart your IDE. Your hook now runs after every file edit.
This example shows a user-level hooks file (~/.firebender/hooks.json). For project-level hooks, change paths like ./hooks/script.sh to .firebender/hooks/script.sh:
beforeShellExecution: The matcher runs against the shell command string. Use it to run hooks only when the command matches a pattern (e.g. network calls, file deletions). The example above runs approve-network.sh only when the command contains curl, wget, or nc .Available matchers by hook:
preToolUse (and other tool hooks): Filter by tool type — Shell, Read, Write, Grep, Delete, MCP, Task, etc.
beforeShellExecution: Filter by the shell command text; the matcher is matched against the full command string.
Called when a chat session becomes active. Useful for session analytics, per-session bookkeeping, and initializing any per-conversation state you want to aggregate later.
Called when the Task tool spawns a subagent. Useful for subagent analytics, auditing by agent type, or injecting additional context into the subagent before it begins.
Called before any tool execution. This is a generic hook that fires for all tool types (Shell, Read, Write, MCP, Task, etc.). Use matchers to filter by specific tools.
Called before any shell command or MCP tool is executed. Return a permission decision.beforeMCPExecution uses fail-closed behavior. If the hook script fails to execute (crashes, times out, or returns invalid JSON), the MCP tool call will be blocked. This ensures MCP operations cannot bypass configured hooks.
// beforeShellExecution input{ "command": "<full terminal command>", "cwd": "<current working directory>", "timeout": 30}// beforeMCPExecution input{ "tool_name": "<tool name>", "tool_input": "<json params>"}// Plus either:{ "url": "<server url>" }// Or:{ "command": "<command string>" }// Output{ "permission": "allow" | "deny" | "ask", "user_message": "<message shown in client>", "agent_message": "<message sent to agent>"}
Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model.This hook uses fail-closed behavior. If the hook script fails to execute (crashes, times out, or returns invalid JSON), the file read will be blocked. This provides security guarantees for sensitive file access.
Called before context window compaction/summarization occurs. This is an observational hook that cannot block or modify the compaction behavior. Useful for logging when compaction happens or notifying users.
// Input{ "trigger": "auto" | "manual", "context_usage_percent": 85, "context_tokens": 120000, "context_window_size": 128000, "message_count": 45, "messages_to_compact": 30, "is_first_compaction": true | false}// Output{ "user_message": "<message to show when compaction occurs>"}
Input Field
Type
Description
trigger
string
What triggered the compaction: “auto” or “manual”
context_usage_percent
number
Current context window usage as a percentage (0-100)
context_tokens
number
Current context window token count
context_window_size
number
Maximum context window size in tokens
message_count
number
Number of messages in the conversation
messages_to_compact
number
Number of messages that will be summarized
is_first_compaction
boolean
Whether this is the first compaction for this conversation
Output Field
Type
Description
user_message
string (optional)
Message to show to the user when compaction occurs
The optional followup_message is a string. When provided and non-empty, Firebender will automatically submit it as the next user message. This enables loop-style flows (e.g., iterate until a goal is met).The loop_count field indicates how many times the stop hook has already triggered an automatic follow-up for this conversation (starts at 0). To prevent infinite loops, a maximum of 5 auto follow-ups is enforced.
There is a Hooks tab in Firebender Settings to debug configured and executed hooks, as well as the Hooks output in ~/.firebender/hooks-logs to see errors.
