# How to Configure OMC_STATE_DIR for Centralized State Across Git Worktrees

> Configure OMC_STATE_DIR to centralize oh-my-claudecode state across git worktrees. Ensure persistent mode syncing with a single directory setting.

- Repository: [Bellman/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- Tags: how-to-guide
- Published: 2026-03-27

---

**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`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/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:

```bash
{worktree}/.omc/

```

If the variable is **set**, OMC resolves state to:

```bash
$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:

```bash

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

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

```

Reload your shell configuration:

```bash
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:

```bash
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:

```bash
mkdir -p "$OMC_STATE_DIR"

```

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

```bash
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()`):

```bash
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:

```bash
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`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/lib/worktree-paths.ts).