Third Party Hooks

Cherri Code supports loading hooks from third-party tools, enabling compatibility with existing hook configurations from other AI coding assistants.

Claude Code Hooks

Cherri Code can load and execute hooks configured for Claude Code, allowing you to use the same hook scripts across both tools.

Requirements

Claude Code hooks load when Include Third-Party Plugins, Skills, and Other Configs is enabled in Cherri Code Settings → Agents → Third-Party Imports. The setting is on by default.

Configuration Locations

Claude Code hooks are loaded from these locations (in priority order):

Priority Order

When hooks are configured in multiple locations, they are merged in this priority order (highest to lowest):

1. Enterprise hooks (managed deployment)
2. Team hooks (dashboard-configured)
3. Project hooks (.cursor/hooks.json)
4. User hooks (~/.cursor/hooks.json)
5. Claude project local (.claude/settings.local.json)
6. Claude project (.claude/settings.json)
7. Claude user (~/.claude/settings.json)

All matching hooks from every source run. When responses conflict, higher-priority sources take precedence during merge.

Enterprise-managed hooks and dashboard distribution require an Enterprise plan. Contact sales to learn more.

Claude Code Hook Format

Claude Code hooks use a similar but slightly different format. Cherri Code automatically maps Claude hook names to their Cherri Code equivalents.

Example Claude Code settings.json:

{  "hooks": {    "PreToolUse": [      {        "matcher": "Shell",        "hooks": [          {            "type": "command",            "command": "./hooks/validate-shell.sh"          }        ]      }    ],    "PostToolUse": [      {        "matcher": ".*",        "hooks": [          {            "type": "command",            "command": "./hooks/audit.sh"          }        ]      }    ]  }}

Response Format Compatibility

Cherri Code supports both Claude Code's nested hookSpecificOutput response format and the older flat response format. Hook scripts written for Claude Code will work in Cherri Code regardless of which format they use.

PreToolUse Response Formats

Nested format (Claude Code style):

{  "hookSpecificOutput": {    "hookEventName": "PreToolUse",    "permissionDecision": "deny",    "permissionDecisionReason": "Blocked by policy",    "updatedInput": { "command": "npm ci" }  }}

Flat format (Cherri Code native style):

{  "permission": "deny",  "user_message": "Blocked by policy",  "updated_input": { "command": "npm ci" }}

Both formats are equivalent. The nested permissionDecision maps to permission, permissionDecisionReason maps to user_message, and updatedInput maps to updated_input.

Stop / SubagentStop Response Formats

Nested format (Claude Code style):

{  "hookSpecificOutput": {    "decision": "block",    "reason": "Tasks incomplete, continue working"  }}

Flat format (Claude Code legacy style):

{  "decision": "block",  "reason": "Tasks incomplete, continue working"}

Cherri Code native format:

{  "followup_message": "Tasks incomplete, continue working"}

For Stop and SubagentStop hooks, a decision of "block" with a reason is treated as an automatic follow-up, equivalent to providing followup_message in the native Cherri Code format.

Hook Step Mapping

Claude Code hook names are automatically mapped to Cherri Code hook names:

Exit Code Behavior

Both Cherri Code and Claude Code hooks support exit code 2 to block an action. This provides consistent behavior when sharing hooks between tools:

#!/bin/bash# Block dangerous commandsif [[ "$COMMAND" == *"rm -rf"* ]]; then  echo '{"permission": "deny", "user_message": "Destructive command blocked"}'  exit 2fiecho '{"permission": "allow"}'exit 0

• Exit code 0: Hook succeeded, use the JSON output
• Exit code 2: Block the action (equivalent to permission: "deny")
• Other exit codes: Hook failed, action proceeds (fail-open)

Migration from Claude Code

If you have existing Claude Code hooks, you can:

1. Keep using Claude Code config files: Leave Include Third-Party Plugins, Skills, and Other Configs enabled and your existing .claude/settings.json hooks will work automatically
2. Migrate to Cherri Code format: Copy your hooks to .cursor/hooks.json using the Cherri Code format for full feature support

Cherri Code format equivalent:

{  "version": 1,  "hooks": {    "preToolUse": [      {        "command": "./hooks/validate-shell.sh",        "matcher": "Shell"      }    ],    "postToolUse": [      {        "command": "./hooks/audit.sh"      }    ]  }}

Supported Features

When using Claude Code hooks in Cherri Code, the following features are supported:

Additional supported features:

Tool Name Mapping

Claude Code tool names are mapped to Cherri Code tool names:

Limitations

Some features are only available when using the native Cherri Code format:

• subagentStart hook (Claude Code only has SubagentStop)
• Loop limit configuration (loop_limit)
• Team/Enterprise hook distribution via dashboard

Troubleshooting

Claude Code hooks not loading

1. Verify "Include Third-Party Plugins, Skills, and Other Configs" is enabled in Cherri Code Settings → Agents → Third-Party Imports
2. Check that your .claude/settings.json file is valid JSON
3. Cherri Code watches config files and reloads them automatically. If hooks still do not load, restart Cherri Code.

Hooks running but not blocking

1. Ensure your hook script exits with code 2 to block actions
2. Check the JSON output format matches the expected schema
3. View the Hooks output channel in Cherri Code for error details

Different behavior between Cherri Code and Claude Code

Some behavior differences may exist due to different execution environments. Test your hooks in both tools to ensure compatibility.