How to Configure OMC_STATE_DIR for Centralized State Across Git Worktrees

Set the OMC_STATE_DIR environment variable to a persistent directory path (e.g., ~/.claude/omc) to store all oh-my-claudecode (OMC) state centrally, keyed by a deterministic project hash, enabling seamless mode persistence across multiple git worktrees.

When working with multiple git worktrees, OMC’s default behavior stores state locally in {worktree}/.omc/. This causes mode data, session logs, and agent plans to fragment or disappear when worktrees are deleted. Configuring OMC_STATE_DIR redirects all state to a single location outside your repository, preserving data across branch checkouts and worktree lifecycle changes.

How OMC_STATE_DIR Works

The state resolution logic lives in src/lib/worktree-paths.ts. When OMC_STATE_DIR is set, the function getOmcRoot() bypasses the default local .omc/ directory and constructs a centralized path instead.

If the variable is unset, OMC resolves state to:

{worktree}/.omc/

If the variable is set, OMC resolves state to:

$OMC_STATE_DIR/{project-identifier}/

Project Identifier Generation

The getProjectIdentifier() function generates a stable, deterministic directory name to ensure all worktrees pointing to the same repository share one state folder. It executes the following logic:

1. Attempts to read the git remote URL (git remote get-url origin)
2. Falls back to the absolute worktree path if no remote exists
3. Computes a SHA256 hash of the source string, truncated to 16 characters
4. Sanitizes the worktree directory name (replacing non-alphanumeric characters with underscores)
5. Concatenates them as {dirname}-{hash}

This identifier remains constant regardless of which worktree you are in, enabling automatic state synchronization across branches.

Fallback and Migration Behavior

When OMC detects both a legacy {worktree}/.omc/ folder and a new centralized folder exist simultaneously, it emits a single warning message and prefers the centralized location. This allows you to migrate data manually, verify functionality, and safely delete the old local folder without data loss.

Setting Up Centralized State

Permanent Configuration in Shell Profile

Add the export to your shell initialization file to enable centralized state for all future OMC invocations:

# ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish

export OMC_STATE_DIR="${HOME}/.claude/omc"

Reload your shell configuration:

source ~/.bashrc

All subsequent OMC commands will read and write state to ~/.claude/omc/{project-identifier}/.

Per-Command Usage

For one-off invocations without modifying your profile, prefix the command inline:

OMC_STATE_DIR="$HOME/.claude/omc" omc team 2:executor "implement login flow"

The environment variable is evaluated at process startup before any filesystem paths are resolved.

Migrating from Legacy Worktree-Local State

To move existing state from a local .omc/ folder to the centralized directory:

1. Ensure the central base directory exists:

mkdir -p "$OMC_STATE_DIR"

2. Trigger OMC to create the new project-specific directory structure:

omc ask claude "test state creation"

3. If OMC warns about dual directory existence, manually copy the legacy contents. Replace the hash portion with your actual project identifier (visible in the warning or via getOmcRoot()):

cp -a ./.omc/* "$OMC_STATE_DIR/$(basename $(pwd))-$(git rev-parse --show-toplevel | sha256sum | cut -c1-16)/"

4. Verify the copy succeeded, then remove the old local folder:

rm -rf ./.omc

Benefits of Centralized State

Scenario	Without OMC_STATE_DIR	With OMC_STATE_DIR
Worktree deletion	All OMC state, modes, and plans are permanently lost	State persists in the central directory and survives worktree removal
Parallel worktrees	Each branch has isolated, fragmented state making cross-tree coordination impossible	All worktrees share identical state, enabling seamless team, ralph, and ultrawork coordination across branches
CI/CD environments	Requires copying .omc/ directories between build steps or ephemeral workspaces	Point all agents at the same $OMC_STATE_DIR mount for persistent, shared state

Summary

• Set OMC_STATE_DIR to a persistent path (e.g., ~/.claude/omc) to enable centralized state storage.
• Project identifiers are deterministic hashes based on the git remote URL or worktree path, ensuring stable paths across worktrees.
• Implementation resides in src/lib/worktree-paths.ts, specifically the getOmcRoot() and getProjectIdentifier() functions.
• Migration is safe: OMC warns when dual directories exist but prefers the centralized location, allowing manual data transfer.
• Usage supports both permanent shell profile configuration and per-command environment variable injection.

Frequently Asked Questions

What happens if I switch between worktrees without setting OMC_STATE_DIR?

Without OMC_STATE_DIR, each worktree maintains its own isolated .omc/ directory. Switching branches via worktrees results in fresh OMC state for each tree, meaning modes, agent memory, and session history do not transfer between them.

How is the project identifier calculated if my repository has no remote origin?

If git remote get-url origin fails (for example, in a local-only repository), getProjectIdentifier() uses the absolute filesystem path of the worktree root as the hash source instead. While this makes the identifier specific to that exact path, it remains stable for that location.

Can I share OMC_STATE_DIR between different machines or users?

The directory path must be accessible to the OMC process, but sharing the actual directory between machines (via network mounts or dotfiles sync) is supported. Ensure the directory permissions allow read/write access for all intended users or agents, and be aware that concurrent writes from multiple machines may cause conflicts unless file locking is handled by your storage layer.

Where is OMC_STATE_DIR documented in the official reference?

According to the oh-my-claudecode reference documentation in docs/REFERENCE.md (Configuration section), the variable is documented with its default behavior, migration notes, and interaction with git worktrees. The source of truth for the runtime behavior is implemented in src/lib/worktree-paths.ts.

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