Thirteen lifecycle events
React to SessionStart, UserPromptSubmit, Stop, StopFailure, TurnStopped, WaitingForUser, PermissionRequest, ToolUse, ToolResult, ValidationStarted, ValidationPassed, ValidationFailed, and SessionEnd.
Run your own shell commands on AI agent events in Flame IDE: prompt submitted, tool use, waiting for you, validation failed, and more, for every provider.
Once agents run in the background, you want things to happen without watching them: post to a channel when a run fails validation, play a sound when an agent waits for approval, log every tool call to a file. Flame's agent hooks run your shell commands on agent lifecycle events, for Claude Code, Codex, Gemini, Copilot, and local providers alike, through Flame's shared chat runtime.
React to SessionStart, UserPromptSubmit, Stop, StopFailure, TurnStopped, WaitingForUser, PermissionRequest, ToolUse, ToolResult, ValidationStarted, ValidationPassed, ValidationFailed, and SessionEnd.
Configure hooks in Settings → AI → Agent hooks, or in a group's or project's settings. Commands combine across scopes, and a project can override or turn off an inherited hook.
Each command receives the event as JSON on stdin and environment variables such as AGENT_HOOK_EVENT. Recent runs show stdout, stderr, exit code, and timeouts.
Hooks are inspired by Claude Code command hooks, but they work for every provider in Flame and include Flame's own events, such as agent work validation.
SessionStart runs when a conversation is created; UserPromptSubmit when a prompt is accepted, including queued prompts and automatic validation repairs; Stop, StopFailure, and TurnStopped when a response completes, fails, or is interrupted; SessionEnd when a conversation is deleted or its session is finished.
WaitingForUser fires when a question, permission request, or plan review needs you, and PermissionRequest when Flame presents a permission prompt. Use them for desktop notifications or chat messages.
ToolUse and ToolResult report normalized tool calls with their input and result. ValidationStarted, ValidationPassed, and ValidationFailed carry a snapshot of the validation report.
Hooks run with the system shell, cmd.exe on Windows and /bin/sh on macOS and Linux, in the chat's checkout, including its worktree. Invoke node, python, pwsh, or bash explicitly when you need them.
The payload includes the event name, conversation and project IDs, working directory, worktree path, provider, and event data such as the prompt, tool input, or validation checks. Event data is never substituted into the command text.
Flame's internal environment and credentials are stripped. Hooks from a repository's .flame.json stay inert until you explicitly import and confirm them.
Timeouts default to 60 seconds and can be set from 1 to 600. Output keeps the last 32,000 characters per stream. A failing hook never blocks the agent or later hooks.
Go to Settings → AI → Agent hooks for every project, or open Agent hooks in a group's or project's Settings tab.
Give it a name, pick an event such as Validation failed, and enter the command, for example node scripts/on-agent-event.mjs. Optionally set a working subdirectory and timeout.
node scripts/on-agent-event.mjsIn the script, read JSON from stdin, check hook_event_name, and use the data, such as the failed checks and their logs.
Save hooks and trigger the event. Recent runs shows each command's output, exit code, and any timeout or startup failure.