How to Use OMC_SKIP_HOOKS and OMC_PARALLEL_EXECUTION to Control oh-my-claudecode Behavior

Set OMC_SKIP_HOOKS to a comma-separated list of hook names to bypass specific logic, and set OMC_PARALLEL_EXECUTION to "false" to force sequential agent execution instead of parallel background tasks.

The oh-my-claudecode (OMC) CLI reads runtime configuration from environment variables to enable flexible deployment across CI pipelines and development environments. Two critical flags—OMC_SKIP_HOOKS and OMC_PARALLEL_EXECUTION—control whether hook logic executes and whether independent agents run concurrently. Understanding these variables allows you to create deterministic, debuggable workflows while maintaining access to OMC's advanced orchestration features.

How OMC_SKIP_HOOKS Disables Specific Hooks

The OMC_SKIP_HOOKS variable accepts a comma-separated list of hook identifiers that OMC will ignore for the current process. When a hook name appears in this list, the dispatcher short-circuits that hook and pretends it succeeded, effectively disabling the associated behavior without modifying source code.

Common hook names include keyword-detector, pre-tool-use, and persistent-mode.

Implementation in the Hook Dispatcher

According to the source code in templates/hooks/keyword-detector.mjs (line 73) and the generic dispatcher in src/hooks/bridge.ts, OMC parses the variable once at startup and caches the result in _cachedSkipHooks:

// templates/hooks/keyword-detector.mjs (excerpt)
const _skipHooks = (process.env.OMC_SKIP_HOOKS || '')
  .split(',')
  .map(s => s.trim());

if (_skipHooks.includes('keyword-detector')) {
  console.log(JSON.stringify({ continue: true }));
  return;
}

Any hook that finds its own name in the parsed array bypasses its logic entirely. This pattern appears consistently across the hook bridge in src/hooks/bridge.ts, ensuring the skip list applies globally after the initial parse.

Practical Usage Examples

Disable the keyword-detector to prevent magic-keyword shortcuts like ultrawork or search from triggering:

export OMC_SKIP_HOOKS=keyword-detector
omc ask "Analyze this codebase"

Disable multiple hooks for a completely non-interactive run:

export OMC_SKIP_HOOKS=keyword-detector,pre-tool-use
omc ask "Generate unit tests"

How OMC_PARALLEL_EXECUTION Controls Agent Concurrency

The OMC_PARALLEL_EXECUTION variable toggles the parallel execution optimization that runs independent agent calls simultaneously via run_in_background=true tasks. By default, this feature is enabled ("true"), but you can force sequential execution for debugging or resource-constrained environments.

Configuration Loading Process

As implemented in src/config/loader.ts (lines 248-252), the variable overrides the built-in default during configuration initialization:

// src/config/loader.ts (excerpt)
if (process.env.OMC_PARALLEL_EXECUTION !== undefined) {
  config.features.parallelExecution = process.env.OMC_PARALLEL_EXECUTION === "true";
}

The boolean value is then propagated through the runtime bridge files (bridge/cli.cjs and bridge/runtime-cli.cjs) to determine how agent tasks are scheduled.

Impact on Background Execution

When OMC_PARALLEL_EXECUTION is set to "false" or "0", OMC disables the run_in_background=true flag on agent tasks. This forces the orchestrator to spawn each sub-agent sequentially rather than simultaneously.

Turning off parallel execution simplifies log output and eliminates race conditions on low-resource machines, though it significantly slows down operations that naturally split into many independent agents (such as ultrawork or search workflows).

# Powershell example

$env:OMC_PARALLEL_EXECUTION = "false"
omc ask "Refactor the authentication module"

In this scenario, the console shows each agent step finishing before the next starts, creating a predictable, single-threaded pipeline.

Combining Environment Variables for Deterministic Runs

You can set both variables simultaneously to create fully deterministic, reproducible executions ideal for CI pipelines:

# POSIX sh

OMC_SKIP_HOOKS="keyword-detector,pre-tool-use" \
OMC_PARALLEL_EXECUTION="0" \
omc ask "Run the test suite and report failures"

This configuration disables interactive hooks and forces sequential processing, ensuring the run produces identical output on every invocation regardless of system load.

Summary

• OMC_SKIP_HOOKS: Set to a comma-separated list (e.g., keyword-detector,pre-tool-use) to bypass specific hooks parsed in src/hooks/bridge.ts and individual hook files like templates/hooks/keyword-detector.mjs.
• OMC_PARALLEL_EXECUTION: Set to "false" or "0" to disable parallel agent execution, forcing sequential task scheduling as configured in src/config/loader.ts (lines 248-252).
• Both variables combine to create deterministic, debug-friendly runs in automation environments.
• Changes take effect immediately at runtime without requiring source code modifications or rebuilds.

Frequently Asked Questions

What happens if I set OMC_SKIP_HOOKS to an empty string?

Setting the variable to an empty string or unsetting it entirely results in an empty skip list, meaning OMC executes all registered hooks normally. The parsing logic in templates/hooks/keyword-detector.mjs treats an empty string as an array with no elements to match against.

Does OMC_PARALLEL_EXECUTION affect all background tasks?

Yes, as implemented in the runtime bridge (bridge/cli.cjs and bridge/runtime-cli.cjs), this flag controls the run_in_background parameter for all agent tasks. When disabled, every sub-agent that would normally spawn in parallel instead executes synchronously, one after another.

Can I use OMC_SKIP_HOOKS to disable all hooks at once?

No, OMC_SKIP_HOOKS requires explicit comma-separated hook names; there is no wildcard value. To completely disable hook functionality, you must enumerate every hook you wish to skip, such as keyword-detector,pre-tool-use,persistent-mode, or set DISABLE_OMC=1 (if supported by your OMC version) to bypass the system entirely.

Where are these environment variables officially documented?

The official reference documentation in docs/REFERENCE.md contains the complete environment variables table, including defaults and accepted values for OMC_SKIP_HOOKS and OMC_PARALLEL_EXECUTION. The functional implementation resides in src/config/loader.ts for the parallel flag and src/hooks/bridge.ts for the skip hooks logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}