Hooks

Hooks are shell commands that Qualia runs at fixed points in an agent’s turn. Use them to check a command before it runs, format files after the agent edits them, or run your tests before the agent says it is done. Open them from the gear menu in the titlebar: Customize agent > Hooks. Getting started explains the flow and offers three templates that need only python3, so they work on desktop and on Qualia Cloud: block rm -rf in shell commands, log shell commands and file edits to .quadrillion/hook-log.jsonl, and check Python syntax before the agent finishes. Using a template adds its hooks to Workspace hooks as an unsaved draft and keeps the hooks already in the file. The Templates menu in the editor adds the same ones to the file you are editing. If the file is not valid JSON, Qualia asks before replacing it with the template. To format code or run your tests, see Examples.

Workspace and personal hooks

Workspace hooks are stored with the project in .quadrillion/hooks.json, so collaborators get the same file.
Personal hooks apply across all your workspaces. On desktop they live in Qualia’s configuration directory; on Qualia Cloud they are stored with your account.

All hooks that match an event run at the same time.

Review before hooks run

A hook file does nothing until you enable it. After saving, click Enable reviewed hooks. Qualia remembers the exact version you enabled, separately for each person. If the file changes afterwards, for example because a collaborator edited it, its hooks stop running until you review and enable the new version. The agent notes in chat when hooks were skipped for this reason, and also warns in chat when a hook file you had enabled has been deleted. If hooks.json changes on disk while you are editing it, Save fails and asks you to reload. The error offers Copy edits so you can keep your draft; Reload asks before it discards unsaved edits.

Enabling covers hooks.json only, not the scripts it calls. Review those scripts too, and keep them somewhere you control.

Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .quadrillion/hooks/check_command.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Each event holds a list of groups. Each group has an optional matcher and one or more commands.

Event	Runs
`PreToolUse`	Before a tool runs. Can block it.
`PostToolUse`	After a tool succeeds.
`PostToolUseFailure`	After a tool fails.
`Stop`	When the agent is about to finish. Can ask it to keep working.

Command options:

Option	Default	Meaning
`command`	required	Shell command to run from the workspace folder.
`timeout`	`10`	Seconds before the command is stopped (1–120).
`loop_limit`	`5`	`Stop` only: how many times this hook can send the agent back to work in one turn (1–5). After that, the agent is allowed to finish.
`fail_closed`	`false`	`PreToolUse` only: block the tool if this command fails, times out, or returns output Qualia cannot read.

A file can hold up to 32 commands.

Matchers

A matcher selects tools by name. Separate alternatives with | and use * as a wildcard. An empty matcher, *, or .* matches every tool. The agent’s replies to you are not tool calls, so no matcher selects them and they always stream; use a Stop hook to act when the agent finishes. You can use Qualia’s tool names (such as bash_command or edit_cell) or these common names: Bash/Shell for shell commands, Read, Write, and Edit for file tools, and mcp__<server>__<tool> for MCP tools. Stop groups take no matcher.

While a PreToolUse hook matches a tool, that tool’s output does not stream live. It appears once the hook has allowed it, so the hook runs before anything changes. A PreToolUse group that matches every tool (an empty matcher, *, or .*) holds back every cell, edit, and write until the hook approves it, and the Hooks editor shows a note when your file has one. Narrow the matcher to keep live streaming for the other tools.

What your command receives

Each command gets a JSON object on standard input with hook_event_name, session_id, cwd, tool_name, tool_input, and, after a tool runs, tool_response. Shell and file tools also include tool_input.command or tool_input.file_path. tool_name uses the common name when a tool has one (Bash, Read, Write, Edit, or mcp__<server>__<tool>), and qualia_tool_name always holds Qualia’s own name, such as bash_command. Tool events also include tool_use_id, which identifies the call. stop_hook_active is true once a Stop hook has already sent the agent back to work in this turn. The environment variables QUALIA_PROJECT_DIR and CLAUDE_PROJECT_DIR hold the workspace folder. Qualia does not provide a transcript_path, so scripts that read the conversation transcript will not work unchanged. The input is capped at 96 KiB. When a tool’s input or response is larger, Qualia shortens its long strings and adds "truncated": true at the top level, so check that field before trusting the full content.

Responding

Exit code 0 allows the action. Output that is a JSON object can carry a decision (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; the tool has already run. Standard error becomes the reason shown to the agent.
Any other exit code counts as a hook error. Errors are reported in chat and do not stop the agent, unless the command sets fail_closed.

JSON responses can use these fields:

Field	Effect
`decision: "block"`	Block the tool (`PreToolUse`), send the agent back to work (`Stop`), or pass the reason to the agent after a tool ran (`PostToolUse`, `PostToolUseFailure`).
`hookSpecificOutput.permissionDecision: "deny"`	`PreToolUse` only: block the tool.
`reason`, `hookSpecificOutput.permissionDecisionReason`	Reason shown to the agent.
`continue: false` with `stopReason`	Hooks never end the agent’s turn. The reason is passed to the agent, and a `PreToolUse` hook also blocks the tool.
`hookSpecificOutput.additionalContext`	Context passed to the agent when no reason is given.
`systemMessage`	Extra message shown to the agent.

Qualia cannot ask for your approval from a hook or rewrite a tool’s input. A PreToolUse response that asks for approval (permissionDecision: "ask") or returns updatedInput blocks the tool rather than running it unchanged. Responses follow the Claude Code format; fields Qualia does not use, including Cursor’s permission and followup_message, are ignored.

Where hooks run

On desktop, hooks run on your computer inside the same sandbox as the agent’s shell commands when sandboxing is on (Settings > Agents > Sandboxing). 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 what 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. Web search and page fetches run as the web_search and web_fetch tools, so hooks can match them like any other tool.

Examples

These hooks call tools that Qualia does not install, so install ruff or pytest where hooks run first (see Where hooks run). If the tool is missing, each hook reports a hook error that names it and lets the agent carry on. Format Python files with ruff after the agent edits them:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, shutil, subprocess, sys; path = json.load(sys.stdin)['tool_input'].get('file_path') or ''; path.endswith('.py') or sys.exit(0); shutil.which('ruff') or sys.exit('ruff is not installed where hooks run, so ' + path + ' was not formatted.'); subprocess.run(['ruff', 'format', path], check=False)\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Run pytest before the agent finishes, and send it back with the last lines of the test output when tests fail. A project with no tests passes.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "command -v pytest > /dev/null || { echo 'pytest is not installed where hooks run, so the tests were not checked.' >&2; exit 1; }; output=$(pytest -q -x 2>&1); code=$?; [ $code -eq 0 ] || [ $code -eq 5 ] || { echo 'Tests are failing. Fix them before finishing.' >&2; printf '%s\\n' \"$output\" | tail -n 20 >&2; exit 2; }",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Importing from Claude Code or Codex

Click Import from Claude Code or Import from Codex to copy supported command hooks into the hooks you are editing. Workspace hooks read the project’s .claude/settings.json, .claude/settings.local.json, .codex/hooks.json, or .codex/config.toml. Personal hooks read only files in your home folder, and only on desktop: ~/.claude/settings.json, ~/.codex/hooks.json, and ~/.codex/config.toml. ~/.claude/settings.local.json is not read. Each source shows a preview first. Click Add hook(s) to draft, then save, review, and enable the result as usual. A file holds at most 32 commands, so when your draft is nearly full the preview says how many fit and the rest are skipped. Imports only copy commands; the scripts they call are not copied, and later changes in Claude Code or Codex are not synced. Unsupported events, options, and tools are skipped and listed in the preview. For example, MultiEdit in Write|Edit|MultiEdit is dropped and the rest of the matcher is kept. Claude Code tool names with a differently named Qualia tool are renamed: 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. Commands without a timeout, or with one above 120 seconds, get 120 seconds. The preview also lists the response fields Qualia honors (see Responding). Before enabling imported PreToolUse guards, check whether their scripts ask for approval or return updatedInput; Qualia blocks the tool in both cases.

Testing

With a hook file enabled, open Test a hook below the editor and click Run test to send a sample event, such as a PreToolUse event for bash_command. Test runs execute your hook commands for real but 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.

Welcome

Core Features

Research Workflow

Tools

Customization & Settings

Interface

Workspace and personal hooks

Review before hooks run

Configuration

Matchers

What your command receives

Responding

Where hooks run

Examples

Importing from Claude Code or Codex

Testing

​Workspace and personal hooks

​Review before hooks run

​Configuration

​Matchers

​What your command receives

​Responding

​Where hooks run

​Examples

​Importing from Claude Code or Codex

​Testing

Workspace and personal hooks

Review before hooks run

Configuration

Matchers

What your command receives

Responding

Where hooks run

Examples

Importing from Claude Code or Codex

Testing