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.
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.jsonin your workspace, so collaborators get the same file. - Personal hooks apply across all your workspaces.
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.
Configuration
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
PreToolUsetool, or sends the agent back to work from aStophook. FromPostToolUseorPostToolUseFailure, 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.
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
python3and common shell tools, but not project tools such aspytestorruff. 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. Installruff 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:
pytest before the agent finishes and send it back with the last lines of output when tests fail:
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
MultiEditfromWrite|Edit|MultiEditand keeps the rest. - Renamed tools: Claude Code names map to Qualia’s names:
Greptoripgrep,Globtolist,WebFetchtoweb_fetch,WebSearchtoweb_search, andNotebookEdittoedit_cell|append_cell. These tools take different input fields, so check scripts that readtool_input. - Timeouts: a missing timeout, or one above 120 seconds, becomes 120 seconds.
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 aPreToolUse 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.
