← All featuresAI Agent Hooks

Let your own scripts react when an agent starts, stops, or needs you.

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.

A failed validation in AI Chat. A ValidationFailed hook can forward this report to your own script. Select the image to enlarge.
WHY IT HELPS

Automation around the agent, not inside it.

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.

Thirteen lifecycle events

React to SessionStart, UserPromptSubmit, Stop, StopFailure, TurnStopped, WaitingForUser, PermissionRequest, ToolUse, ToolResult, ValidationStarted, ValidationPassed, ValidationFailed, and SessionEnd.

Global, group, or project scope

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.

JSON in, logs out

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.

AI AGENT HOOKS IN PRACTICE

Pick the moment that matters.

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.

Turn and conversation events

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.

Attention events

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.

Tool and validation events

ToolUse and ToolResult report normalized tool calls with their input and result. ValidationStarted, ValidationPassed, and ValidationFailed carry a snapshot of the validation report.

AI AGENT HOOKS IN PRACTICE

Any command your shell can run.

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.

Event data as JSON

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.

Safe defaults

Flame's internal environment and credentials are stripped. Hooks from a repository's .flame.json stay inert until you explicitly import and confirm them.

Bounded runs

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.

HOW TO USE IT

Add a hook in a minute.

  1. Open Agent hooks

    Go to Settings → AI → Agent hooks for every project, or open Agent hooks in a group's or project's Settings tab.

  2. Add a command

    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.mjs
  3. Read the event

    In the script, read JSON from stdin, check hook_event_name, and use the data, such as the failed checks and their logs.

  4. Check recent runs

    Save hooks and trigger the event. Recent runs shows each command's output, exit code, and any timeout or startup failure.

REQUIREMENTS & LIMITS

Know what the tool depends on.

  • Hooks observe. They cannot block a prompt, approve permissions, change tool results, or add model context.
  • Commands run on the machine running the Flame backend with that process's access. Treat prompts, tool output, and event data as untrusted input in your scripts.
  • Recent runs reset when the backend restarts. Each conversation queues at most 100 hook events; extra events are dropped if commands cannot keep up.
  • Flame's hook format is its own lifecycle contract, not a drop-in importer for Claude Code hook settings.
FAQ

AI Agent Hooks: common questions