Factory Droid Hooks: hooks.json, PreToolUse Matchers and Exit Codes
How do I set up hooks in Factory Droid?
Put hooks in ~/.factory/hooks.json for yourself or .factory/hooks.json in the repo for your team, keyed by event name such as PreToolUse. Each entry has a matcher and a list of command hooks. A hook that exits with code 2 blocks the tool call in PreToolUse.
Compare: hooks in every AI coding agent →
Hook events
- PreToolUse
- PostToolUse
- UserPromptSubmit
- Notification
- Stop
- SubagentStop
- PreCompact
- SessionStart
- SessionEnd
Where to put hooks
- User: ~/.factory/hooks.json. Applies to all your projects.
- Project: .factory/hooks.json. Commit it for teammates.
- Enterprise: org managed settings.
- Legacy: .factory/hooks/hooks.json still loads, and the next save moves it to .factory/hooks.json.
If there is no hooks.json, Droid reads a hooks key in the matching settings.json. In settings.json the same event map sits under a top level "hooks" key.
Example: audit every git command
.factory/hooks.json
{
"PreToolUse": [
{
"matcher": "Execute",
"commandRegex": "^git ",
"hooks": [
{
"type": "command",
"command": "/usr/local/bin/audit-git-command.sh",
"timeout": 30
}
]
}
]
}How matchers work
- An empty, missing or * matcher matches everything.
- An exact string matches one tool.
- Regex is supported and is case sensitive.
- commandRegex filters Execute calls by the shell command text. Invalid regex is skipped.
- MCP tools are named mcp__<server>__<tool>, so mcp__.* matches all of them.
Exit codes
- 0: success. For UserPromptSubmit and SessionStart, stdout can add context.
- 2: blocking feedback. PreToolUse blocks the tool call. PostToolUse and Stop send stderr back to Droid. UserPromptSubmit blocks the prompt.
- Any other non zero code: a non blocking error. Droid records stderr and continues.
Check what is active with /hooks
Run /hooks inside Droid to open the hooks manager. It has User, Project, Plugins and Effective tabs. Plugins and Effective are read only.
Sources
More Factory Droid guides
Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →