Hooks

Hooks are commands that the desktop app runs on your computer at certain events of an agent run in Code and Cowork. A hook can, for example, start a formatter after a file was edited, or check a command before it runs and stop it.

You see and manage hooks under Settings → Desktop app → Hooks.

Where hooks are defined

Hooks live in the hooks section of the same files that also hold the permission rules:

Structure

Each event holds a list of entries, each with a matcher and the commands to run. This example formats every file the agent edits or creates:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.file_path | xargs npx prettier --write",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

matcher selects the tools. Empty or * matches all of them. Besides the app's own names, the short names Bash, Edit, Write and Read work as well. Tools of MCP servers start with mcp__.

A command can also carry these fields:

• if: the command only runs when the call matches this rule. You write it as in the permissions, for example runCommand(git *).
• async: with true the command runs alongside, and the agent does not wait for it.
• onFailure: with "block" a failed command counts as a block.

How a command runs

The command receives the event data as JSON on standard input and runs in the project folder. After 60 seconds the app stops it. Use timeout to set a different limit, at most 600 seconds.

What happens next depends on the exit code:

When a hook allows an action, it works like an allow rule: the app no longer asks about it. Deny rules, ask rules, dangerous commands, plan mode and paths outside the shared folder still lead to a question or a block.

Events

Approval

Hooks from project files only run once you have approved them. You do that per file under Settings → Desktop app → Hooks. If the hooks section of a file changes, for example after a git pull or because the agent edited the file, it waits for your approval again. You confirm your own settings in ~/.deutschlandgpt/settings.json once when they were changed outside the app.

Project hooks and local hooks also only run in a folder you explicitly trust. The same applies to the permission rules from these files. You mark a folder as trusted in the file tree: right-click the folder and choose Trust this folder.

The Hooks page shows for each file the event, matcher and command verbatim, and its status: approved, waiting for approval or blocked. Below that are the latest runs with exit code and duration. Revoke approval stops the hooks of a file again. When hooks are waiting for approval, the app also shows a notice above the input field.

Diagnostics after changes

With Diagnostics after changes on the Hooks page you set up, per shared folder, a type check that runs on your computer after every file change the agent makes. If the folder has a tsconfig.json, that is npx --no-install tsc --noEmit -p .; with a Cargo.toml it is cargo check --quiet --message-format short; with both files, both. Before setting it up, the app shows the commands verbatim. Set up adds a PostToolUse hook to .deutschlandgpt/settings.local.json, which stays on this computer, and approves it at the same time. If the check finds errors, the agent sees the first 40 lines in the result of its change and can fix them right away. Without errors it sees nothing. Like every local hook, this one only runs in a folder you trust.

Your organization's rules

Your organization's administrators can switch off hooks from project folders and plugins with their own commands. Then even hooks you have already approved no longer run, and the Hooks page shows them as blocked. In organizations bound by professional secrecy (§ 203 StGB), hooks from project folders are off at first.