omp-hooks

Claude Code-style command hooks for OMP (Oh My Pi).

omp-hooks lets OMP run Claude Code-style settings.json command hooks. It is useful when a Claude-native tool already writes hook config, but OMP only loads its MCP/skills/extension surfaces and does not execute Claude hook arrays.

OMP already has native extensions and hook APIs. Use those when you are writing a new OMP-only plugin. Use omp-hooks when you want to reuse Claude Code command hook workflows such as PreToolUse, SessionStart, or Stop scripts.

Install

omp install omp-hooks

Then restart OMP or run /reload.

Install from GitHub

omp install git:github.com/ZeR020/omp-hooks

Local development

git clone https://github.com/ZeR020/omp-hooks.git
omp plugin link ./omp-hooks

Quick start

Create ~/.omp/agent/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'agent finished'"
          }
        ]
      }
    ]
  }
}

Restart OMP. When the agent finishes a response, the command runs and stdout is injected as hidden context for the model.

Project-local config is also supported at:

<project>/.omp/settings.json

Project config is merged over global config. Override the settings path with:

OMP_HOOKS_SETTINGS=/path/to/settings.json

What this solves

Claude Code hooks are configured as JSON command handlers. OMP's native extension API can block tools and send custom context, but it does not execute Claude settings.json hook arrays directly. omp-hooks bridges that gap:

Claude-style hook config
        ↓
omp-hooks
        ↓
OMP extension events
        ↓
command stdout → hidden model context

This is especially useful for tools that augment context before tool calls, such as code graph or skill-discovery helpers.

Supported Claude hook subset

omp-hooks intentionally supports the command-hook subset. It does not try to implement every Claude Code hook feature.

Handler type

| Claude handler type | Status | | --- | --- | | command | Supported | | http | Not supported | | prompt | Not supported | | agent | Not supported | | mcp_tool | Not supported |

Command fields

| Field | Status | Notes | | --- | --- | --- | | command | Supported | Shell form by default. | | args | Supported | Exec form; no shell when present. | | timeout | Supported | Seconds. | | shell | Supported | bash by default; powershell supported for shell form. | | async | Supported | Runs in the background. Blocking decisions are ignored. | | asyncRewake | Best effort | Exit code 2 injects a hidden reminder and asks OMP to start another turn. | | if | Tool events only | Supports ToolName(pattern) with * wildcards. |

Events

| Claude event | OMP event | Status | | --- | --- | --- | | SessionStart.startup | session_start | Supported | | SessionStart.resume | session_before_switch(reason="resume") | Supported | | SessionStart.compact | session_compact | Supported | | SessionEnd.other | session_shutdown | Supported | | PreCompact | session_before_compact | Supported | | PostCompact | session_compact | Supported | | PreToolUse | tool_call | Supported | | PostToolUse | tool_result success | Supported | | PostToolUseFailure | tool_result error | Supported | | UserPromptSubmit | input / before-agent injection | Supported | | Stop | agent_end | Best effort |

Not supported yet: PostToolBatch, PermissionRequest, PermissionDenied, Notification, MessageDisplay, SubagentStart, SubagentStop, StopFailure, and newer Claude events that have no direct OMP mapping yet.

Matchers

matcher follows Claude Code-style matching:

• omitted, "", or "*" → match all
• plain names → exact match, for example "Bash"
• pipe/comma lists → exact alternatives, for example "Edit|Write" or "Edit, Write"
• regex syntax → JavaScript regex, for example "mcp__.*"

OMP raw tool names are normalized to Claude-style tool names before matching:

| OMP | Hook payload / matcher | | --- | --- | | bash | Bash | | read | Read | | write | Write | | edit | Edit | | grep | Grep | | glob | Glob | | ls | LS | | mcp__... | unchanged |

Lowercase matchers such as "bash" still work for existing configs.

Examples

Run a command before Bash tools

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'bash is about to run'"
          }
        ]
      }
    ]
  }
}

Block git push

Exit code 2 blocks synchronous tool hooks. Stderr becomes the reason.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push*)",
            "command": "echo 'git push is blocked from this agent' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

Use exec form with args

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob",
        "hooks": [
          {
            "type": "command",
            "command": "/home/me/.local/bin/codebase-memory-mcp",
            "args": ["hook-augment"]
          }
        ]
      }
    ]
  }
}

Inject structured additional context

A command can print Claude-style JSON:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "Relevant context for the next tool call."
  }
}

For simple hooks, plain stdout is also injected as hidden context.

Replace tool output (PostToolUse only)

A PostToolUse hook can replace what the model sees by returning updatedToolOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedToolOutput": "replacement content the model sees instead"
  }
}

The value is passed through as OMP-shaped content. For MCP tools, updatedMCPToolOutput is also accepted. The tool has already run — only what the model sees changes.

Hook input

Hook commands receive JSON on stdin. Common fields include:

{
  "session_id": "...",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse"
}

Tool events also include:

{
  "tool_name": "Bash",
  "tool_input": { "command": "git status" },
  "tool_use_id": "..."
}

Post-tool events include tool_response and, on failures, error.

Exit and output behavior

| Result | Behavior | | --- | --- | | exit 0, plain stdout | Inject stdout as hidden context. | | exit 0, JSON stdout | Parse Claude-style output fields. | | exit 2 in PreToolUse | Block the tool; stderr is the reason. | | other non-zero | Notify the user; do not block. | | async: true | Return immediately; inject JSON additionalContext when the process exits. |

Parallel execution

Matching hooks run in parallel (Claude Code behavior). When multiple hooks match the same event:

• All hooks fire concurrently via Promise.allSettled — total time is max(hook durations), not the sum.
• Identical handlers are deduplicated by command + args (so a hook defined in both global and project settings fires once).
• Deny wins: for PreToolUse, if any hook returns deny/exit-2, the tool is blocked regardless of allow from other hooks. stopProcessing wins over deny.
• updatedInput merges in config order (last wins per key).
• additionalContext concatenates in config order for stable output.
• PostToolUse patches: first non-undefined content/details/isError wins (by config order).

Development

bun install
bun run typecheck
bun run build

dist/ is build output only. OMP loads the TypeScript source entry directly:

src/omp-hooks.ts

Relationship to OMP native hooks

OMP native extensions are still the best choice for new OMP-specific plugins. They are more powerful and typed directly against OMP. omp-hooks exists for a different reason: compatibility with Claude Code-style command hook config.

If you control the plugin and only target OMP, write an OMP extension. If you are porting a Claude Code tool that already ships command hooks, use omp-hooks.

License

MIT