Skip to main content
Add a hook to check, log, or test the agent’s work automatically. A hook is a shell command that Qualia runs at a fixed point in an agent’s turn. For example, a hook can refuse a dangerous shell command, format a file the agent edited, or run your tests before the agent finishes. Unlike rules, which are instructions the agent reads, a hook runs whether or not the agent remembers it.

Open the Hooks editor

Open the gear menu in the titlebar, choose Customize agent, then choose Hooks. From there you can:
  • Choose Add, then Create workspace hook or Create personal hook, to edit a hook file.
  • Pick a template under Start with a template.
The three templates need only python3, so they work on desktop and on Qualia Cloud: A template adds its hooks to Workspace hooks as an unsaved draft and keeps the hooks already in the file. Inside the editor, the Templates menu adds the same hooks to the file you have open. To format code or run tests, adapt one of the examples.

Workspace and personal hooks

  • Workspace hooks live in .quadrillion/hooks.json in your workspace, so collaborators get the same file.
  • Personal hooks apply across all your workspaces.
When several hooks match the same event, Qualia runs them all at the same time.

Enable reviewed hooks

A hook file does nothing until you enable it. After you save, choose Enable reviewed hooks. Enabling applies to you only, and to that exact version of the file. If the file changes afterwards, its hooks stop running until you review and enable the new version. For example, a collaborator’s edit to .quadrillion/hooks.json turns the workspace hooks off for you. The agent tells you in chat when it skipped hooks for this reason, or when an enabled hook file was deleted. If hooks.json changes on disk while you are editing it, Save fails. Choose Copy edits on the error to keep your draft, then Reload. Qualia asks before Reload discards unsaved edits.
Enabling covers hooks.json only, not the scripts it calls. Review those scripts too, and keep them somewhere you control, because a later change to a script never asks for review.

Configuration

Each event holds a list of groups. Each group has an optional matcher and one or more commands. A file holds at most 32 commands.

Matchers

A matcher selects tools by name. Separate alternatives with | and use * as a wildcard, such as Edit|Write or mcp__github__*. An empty matcher, *, or .* matches every tool. Stop groups ignore the matcher. You can use Qualia’s tool names, such as bash_command or edit_cell, or these common names: Web search and page fetches are the web_search and web_fetch tools, so a matcher can select them too. The agent’s replies to you are not tool calls, so no matcher selects them. To act when the agent finishes, use a Stop hook.
While a PreToolUse hook matches a tool, that tool’s output does not stream live. It appears once the hook allows it. A PreToolUse group that matches every tool holds back every cell, edit, and write, and the Hooks editor warns you about it. Narrow the matcher to keep live streaming for the other tools.

What your command receives

Qualia sends each command a JSON object on standard input: Check truncated before you trust the full content of a large input or response. The QUALIA_PROJECT_DIR and CLAUDE_PROJECT_DIR environment variables hold the workspace folder. Qualia does not provide transcript_path, so scripts that read the conversation transcript won’t work unchanged.

Respond to Qualia

Your command tells Qualia what to do through its exit code:
  • Exit code 0 allows the action. If the command prints a JSON object, Qualia reads it as a response (see below).
  • Exit code 2 blocks a PreToolUse tool, or sends the agent back to work from a Stop hook. From PostToolUse or PostToolUseFailure, it passes the reason to the agent and keeps it working, but the tool has already run. Qualia shows the agent standard error as the reason.
  • Any other exit code is a hook error. Qualia reports it in chat and the agent carries on, unless the command sets fail_closed.
A JSON response can use these fields: Hooks can’t ask you for approval or rewrite a tool’s input. A PreToolUse response with permissionDecision: "ask" or updatedInput blocks the tool, so that it never runs unreviewed. Responses follow the Claude Code format. Qualia ignores fields it does not use, such as Cursor’s permission and followup_message.

Where hooks run

On desktop, hooks run on your computer. When the sandbox is on, they run inside the same sandbox as the agent’s shell commands (Settings > Agents > Permissions). On Qualia Cloud, hooks run in your workspace’s cloud sandbox. Hooks can use the same programs as the agent’s shell commands:
  • On desktop, that is whatever your shell finds on its PATH.
  • On Qualia Cloud, the sandbox has python3 and common shell tools, but not project tools such as pytest or ruff. Install them in the sandbox, or point the hook at a copy inside your project, such as .venv/bin/pytest.

Examples

These hooks call tools that Qualia does not install. Install ruff or pytest where hooks run first. If the tool is missing, the hook reports an error that names it, and the agent carries on. To format Python files with ruff after the agent edits them:
To run pytest before the agent finishes and send it back with the last lines of output when tests fail:
A project with no tests passes, because pytest exits with code 5 when it collects none.

Import from Claude Code or Codex

Choose Import from Claude Code or Import from Codex to copy supported command hooks into the file you are editing. Qualia reads these files: Each source shows a preview first. Choose Add [N] hook(s) to draft, then save, review, and enable the result as usual. If your draft is nearly full, the preview says how many hooks fit within the 32-command limit and skips the rest. Imports copy commands only. Qualia does not copy the scripts they call, and later changes in Claude Code or Codex don’t sync. The preview lists everything it skips or changes:
  • Unsupported events, options, and tools: Qualia skips them. For example, it drops MultiEdit from Write|Edit|MultiEdit and keeps the rest.
  • Renamed tools: Claude Code names map to Qualia’s names: Grep to ripgrep, Glob to list, WebFetch to web_fetch, WebSearch to web_search, and NotebookEdit to edit_cell|append_cell. These tools take different input fields, so check scripts that read tool_input.
  • Timeouts: a missing timeout, or one above 120 seconds, becomes 120 seconds.
Before you enable an imported PreToolUse guard, check whether its script asks for approval or returns updatedInput. Qualia blocks the tool in both cases (see Respond to Qualia).

Test a hook

Enable the hook file, open Test a hook below the editor, and choose Run test. The sample event is a PreToolUse call to bash_command, and you can edit it. Test runs execute your hook commands for real, so they can change files, but they never run the agent tool. Each result shows why a hook failed, such as a timeout, a nonzero exit status, or a response Qualia could not read.