## File: README.md

English | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md) | [Tiếng Việt](README.vi.md) | [Português](README.pt.md)

# oh-my-claudecode

[](https://www.npmjs.com/package/oh-my-claude-sisyphus)
[](https://www.npmjs.com/package/oh-my-claude-sisyphus)
[](https://github.com/Yeachan-Heo/oh-my-claudecode/stargazers)
[](https://opensource.org/licenses/MIT)
[](https://github.com/sponsors/Yeachan-Heo)
[](https://discord.gg/jq6jnSGABY)

> **For Codex users:** Check out [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) — the same orchestration experience for OpenAI Codex CLI.

**Multi-agent orchestration for Claude Code. Zero learning curve.**

_Don't learn Claude Code. Just use OMC._

[Get Started](#quick-start) • [Documentation](https://yeachan-heo.github.io/oh-my-claudecode-website) • [CLI Reference](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#cli-reference) • [Workflows](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#workflows) • [Migration Guide](docs/MIGRATION.md) • [Discord](https://discord.gg/jq6jnSGABY)

---

## Core Maintainers

| Role           | Name        | GitHub                                         |
| -------------- | ----------- | ---------------------------------------------- |
| Creator & Lead | Yeachan Heo | [@Yeachan-Heo](https://github.com/Yeachan-Heo) |

## Ambassadors

| Name       | GitHub                                           |
| ---------- | ------------------------------------------------ |
| Sigrid Jin | [@sigridjineth](https://github.com/sigridjineth) |

## Document Specialists

| Name    | GitHub                                 |
| ------- | -------------------------------------- |
| devswha | [@devswha](https://github.com/devswha) |

## Top Collaborators

| Name           | GitHub                                         | Commits |
| -------------- | ---------------------------------------------- | ------- |
| JunghwanNA     | [@shaun0927](https://github.com/shaun0927)     | 65      |
| riftzen-bit    | [@riftzen-bit](https://github.com/riftzen-bit) | 52      |
| Seunggwan Song | [@Nathan-Song](https://github.com/Nathan-Song) | 20      |
| BLUE           | [@blue-int](https://github.com/blue-int)       | 20      |
| Junho Yeo      | [@junhoyeo](https://github.com/junhoyeo)       | 15      |

## Quick Start

**Step 1: Install**

Marketplace/plugin install (recommended for most Claude Code users).
These are Claude Code slash commands — enter them **one at a time** (pasting both lines at once will fail):

```bash
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
```

Then:

```bash
/plugin install oh-my-claudecode
```

If you prefer the npm CLI/runtime path instead of the marketplace flow:

```bash
npm i oh-my-claude-sisyphus@latest
```

> **Known npm warning:** npm may print `deprecated prebuild-install@7.1.3` during the CLI install.
> This currently comes from the upstream `better-sqlite3` native-addon dependency
> (`better-sqlite3 -> prebuild-install`); `prebuild-install@7.1.3` is still the latest
> published version, so there is no safe repo-side dependency bump or override to remove
> the warning yet. The warning is tracked in [#2913](https://github.com/Yeachan-Heo/oh-my-claudecode/issues/2913)
> and does not by itself mean the OMC CLI install failed.

**Step 2: Setup**

```bash
# Inside a Claude Code / OMC session
/setup
/omc-setup

# From your terminal
omc setup
```

If you run OMC via `omc --plugin-dir ` or `claude --plugin-dir `, add `--plugin-dir-mode` to `omc setup` (or export `OMC_PLUGIN_ROOT` before running it) so the installer doesn't duplicate skills/agents that the plugin already provides at runtime. See the [Plugin directory flags section in REFERENCE.md](./docs/REFERENCE.md#plugin-directory-flags) for a complete decision matrix and all available flags.

**Step 3: Build something**

```bash
# Inside a Claude Code / OMC session
/autopilot "build a REST API for managing tasks"

# Natural-language in-session shortcut
autopilot: build a REST API for managing tasks
```

#### Named autopilot stage profiles (v1)

Select a configured stage profile only through `/autopilot --workflow <name> <task>`:

```text
/autopilot --workflow plan-build-qa "build a REST API for managing tasks"
```

Profiles are configured under `autopilot.workflows` in `.claude/omc.jsonc` (project) or `~/.config/claude-omc/config.jsonc` (user). A v1 profile contains only `version: 1` and `stages`:

```jsonc
{
  "autopilot": {
    "workflows": {
      "plan-build-qa": {
        "version": 1,
        "stages": ["ralplan", "execution", "qa"]
      }
    }
  }
}
```

The admitted sequences are `[ralplan, execution]`, `[ralplan, execution, ralph]`, `[ralplan, execution, qa]`, and `[ralplan, execution, ralph, qa]`. A project profile of the same name wholly replaces the user profile; different names coexist. Environment variables cannot define profiles. Profiles remain within autopilot's existing state, cancel, resume, Stop, and HUD lifecycle; legacy invocations without `--workflow` remain compatible.

Named profiles currently require Linux with the `flock` utility because their transcript evidence boundary uses Linux no-follow file-descriptor traversal and their recoverable mutation lock uses kernel advisory locking. Unsupported environments reject explicit `--workflow` invocation before creating or changing autopilot state; legacy autopilot remains available.

V1 intentionally excludes model fields or routing (`stageModels`), inline execution, dynamic commands/modes/state, arbitrary stages or plugins, and the separate custom-skill frontmatter parser mismatch. See [Named Autopilot Stage Profiles ADR](docs/adr/03487-named-autopilot-stage-profiles.md) and [Reference](docs/REFERENCE.md#named-autopilot-stage-profiles-v1).


That's it. Everything else is automatic.

### CLI Commands vs In-Session Skills

OMC exposes two different surfaces:

- **Terminal CLI commands**: run `omc ...` from your shell after installing the npm/runtime path (`npm i oh-my-claude-sisyphus@latest`) or from a local checkout.
- **In-session skills**: run `/...` inside a Claude Code session after installing the plugin/setup flow.

| Feature                                        | Terminal CLI                                  | In-session skill                                                        | Notes                                                                                                                                |
| ---------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Setup                                          | `omc setup`                                   | `/setup` or `/omc-setup`                                                | Both are real entrypoints. `/setup` is the easiest plugin-first path.                                                                |
| Ask providers                                  | `omc ask codex "review this patch"`           | `/ask codex "review this patch"`                                        | Both route through the same advisor flow. Providers: `claude`, `codex`, `gemini`, `antigravity`, `grok`, `cursor`.                                            |
| Team orchestration                             | `omc team 2:codex "review auth flow"`         | `/team 3:executor "fix all TypeScript errors"`                          | Both exist, but they are different runtimes: `omc team` launches tmux CLI workers; `/team` runs the in-session native team workflow. |
| Autopilot / Ralph / Ultrawork / Deep Interview | —                                             | `/autopilot ...`, `/ralph ...`, `/ultrawork ...`, `/deep-interview ...` | These are in-session skills. There is no `omc autopilot` / `omc ralph` / `omc ultrawork` CLI subcommand in this repo.                |
| Autoresearch                                   | `omc autoresearch` (**hard-deprecated shim**) | `/deep-interview --autoresearch ...` + `/oh-my-claudecode:autoresearch` | Setup stays in deep-interview; execution now belongs to the stateful skill.                                                          |

### VS Code, Agent SDK, and automation scope

- **VS Code / IDE extension**: OMC does not ship a VS Code extension and does not document extension-specific install or automation flows. Use the Claude Code plugin or terminal CLI surfaces above; IDE integrations are only an optional way to access Claude Code itself.
- **Agent SDK / programmatic usage**: the npm package exports TypeScript helpers such as `createOmcSession()` and prompt expansion utilities for local Node.js programs using `@anthropic-ai/claude-agent-sdk`. This is a library surface, not a replacement for the Claude Code plugin UI.
- **CI/CD and headless automation**: prefer deterministic terminal commands (`omc setup`, `omc ask`, `omc session search`, repository scripts such as `npm run sync-metadata:verify`) and set `ANTHROPIC_API_KEY` or provider-specific CLI auth in the runner environment. Do not rely on interactive slash commands (`/autopilot`, `/ralph`, `/team`) in CI; they require an active Claude Code session.

### Not Sure Where to Start?

If you're uncertain about requirements, have a vague idea, or want to micromanage the design:

```
/deep-interview "I want to build a task management app"
```

The deep interview uses Socratic questioning to clarify your thinking before any code is written. It exposes hidden assumptions and measures clarity across weighted dimensions, ensuring you know exactly what to build before execution begins.

## Team Mode (Recommended)

Starting in **v4.1.7**, **Team** is the canonical orchestration surface in OMC. The legacy `swarm` keyword/skill has been removed; use `team` directly.

```bash
/team 3:executor "fix all TypeScript errors"
```

Use `/team ...` when you want Claude Code's in-session native team workflow. Use `omc team ...` when you want terminal-launched tmux CLI workers (`claude` / `codex` / `gemini` panes).

Team runs as a staged pipeline:

`team-plan → team-prd → team-exec → team-verify → team-fix (loop)`

Enable Claude Code native teams in `~/.claude/settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

> If teams are disabled, OMC will warn you and fall back to non-team execution where possible.

### tmux CLI Workers — Codex, Gemini & Antigravity (v4.4.0+)

**v4.4.0 removes the Codex/Gemini MCP servers** (`x`, `g` providers). Use the CLI-first Team runtime (`omc team ...`) to spawn real tmux worker panes:

```bash
omc team 2:codex "review auth module for security issues"
omc team 2:gemini "redesign UI components for accessibility"
omc team 2:antigravity "redesign UI components for accessibility"
omc team 1:claude "implement the payment flow"
omc team 1:cursor "implement the payment flow"
omc team status auth-review
omc team shutdown auth-review
```

`/omc-teams` remains as a legacy compatibility skill and now routes to `omc team ...`.

For mixed Codex + Antigravity work in one command, use the **`/ccg`** skill (routes via `/ask codex` + `/ask antigravity`, then Claude synthesizes; Gemini remains available as an enterprise/API-key fallback):

```bash
/ccg Review this PR — architecture (Codex) and UI components (Antigravity)
```

| Surface                         | Workers                       | Best For                                     |
| ------------------------------- | ----------------------------- | -------------------------------------------- |
| `omc team N:codex "..."`        | N Codex CLI panes             | Code review, security analysis, architecture |
| `omc team N:gemini "..."`       | N Gemini CLI panes            | UI/UX design, docs, large-context tasks (enterprise/API-key) |
| `omc team N:antigravity "..."`  | N Antigravity (`agy`) panes   | UI/UX design, docs, large-context tasks                      |
| `omc team N:grok "..."`         | N Grok Build CLI panes        | Code review, analysis cross-check            |
| `omc team N:cursor "..."`       | N Cursor agent panes          | Executor-style implementation tasks          |
| `omc team N:claude "..."`       | N Claude CLI panes            | General tasks via Claude CLI in tmux         |
| `/ccg`                          | /ask codex + /ask antigravity | Tri-model advisor synthesis                  |

Workers spawn on-demand and die when their task completes — no idle resource usage. Requires the selected CLI (`codex`, `gemini`, `agy` (antigravity), `grok`, or `cursor-agent`) installed/authenticated and an active tmux session.

Autopilot can prefer Cursor executor workers during team execution via `.claude/omc.jsonc`:

```jsonc
{
  "autopilot": {
    "execution": "team",
    "team": { "agentTypes": ["cursor"] }
  }
}
```

This config makes the autopilot execution stage use `omc team 1:cursor "..."` or `/omc-teams 1:cursor "..."` for executor-style implementation work. Reviewer, critic, security-review, validation verdict, and final approval roles remain native Claude/OMC reviewer roles; Cursor requires an installed/authenticated `cursor-agent`.

Native team worker worktrees are being added behind an opt-in/config gate. See [Native Team Worktree Mode](docs/TEAM-WORKTREE-MODE.md) for the workspace contract, canonical state-root rules, dirty-worktree preservation policy, and verification checklist.

> **Note: Package naming** — The project is branded as **oh-my-claudecode** (repo, plugin, commands), but the npm package is published as [`oh-my-claude-sisyphus`](https://www.npmjs.com/package/oh-my-claude-sisyphus). If you install or upgrade the CLI tools via npm/bun, use `npm i oh-my-claude-sisyphus@latest`; the package installs both `oh-my-claudecode` and the short `omc` command aliases.

### Updating

If you installed OMC via npm, upgrade with the published package name:

```bash
npm i oh-my-claude-sisyphus@latest
```

> **Package naming note:** the repo, plugin, and commands are branded **oh-my-claudecode**, but the published npm package name remains `oh-my-claude-sisyphus`. npm installs expose both `oh-my-claudecode` and `omc`; examples prefer `omc` for brevity.

If you installed OMC via the Claude Code marketplace/plugin flow, update with:

```bash
# 1. Update the marketplace clone
/plugin marketplace update omc

# 2. Re-run setup to refresh configuration
/setup
```

If you are developing from a local checkout or git worktree, update the checkout first, then re-run setup from that worktree so the active runtime matches the code you are testing.

> **Note:** If marketplace auto-update is not enabled, you must manually run `/plugin marketplace update omc` to sync the latest version before running setup.

If you experience issues after updating, clear the old plugin cache:

```bash
/omc-doctor
```

<h1 align="center">Your Claude Just Have been Steroided.</h1>



---

## Why oh-my-claudecode?

- **Zero configuration required** - Works out of the box with intelligent defaults
- **Team-first orchestration** - Team is the canonical multi-agent surface
- **Natural language interface** - No commands to memorize, just describe what you want
- **Automatic parallelization** - Complex tasks distributed across specialized agents
- **Persistent execution** - Won't give up until the job is verified complete
- **Cost optimization** - Smart model routing saves 30-50% on tokens
- **Learn from experience** - Automatically extracts and reuses problem-solving patterns
- **Real-time visibility** - HUD statusline shows what's happening under the hood

---

## Features

### Orchestration Modes

Multiple strategies for different use cases — from Team-backed orchestration to token-efficient refactoring. [Learn more →](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#execution-modes)

| Mode                        | What it is                                                                              | Use For                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Team (recommended)**      | Canonical staged pipeline (`team-plan → team-prd → team-exec → team-verify → team-fix`) | Coordinated Claude agents on a shared task list                         |
| **omc team (CLI)**          | tmux CLI workers — real `claude`/`codex`/`gemini`/`antigravity`/`grok`/`cursor-agent` processes in split-panes       | Codex/Gemini/Antigravity/Grok/Cursor CLI tasks; on-demand spawn, die when done             |
| **ccg**                     | Tri-model advisors via `/ask codex` + `/ask antigravity`, Claude synthesizes             | Mixed backend+UI work needing both Codex and Antigravity                     |
| **Autopilot**               | Autonomous execution (single lead agent)                                                | End-to-end feature work with minimal ceremony                           |
| **Ultrawork**               | Maximum parallelism (non-team)                                                          | Burst parallel fixes/refactors where Team isn't needed                  |
| **Ralph**                   | Persistent mode with verify/fix loops                                                   | Tasks that must complete fully (no silent partials)                     |
| **UltraQA**                 | QA cycling until tests/build/lint/typecheck goals pass                                  | Quality gates that need repeat diagnose/fix cycles                      |
| **Claude Code `/goal`**     | Native Claude Code cross-turn goal loop                                                 | One measurable session completion condition; not an OMC evidence ledger |
| **Artifact-only Ultragoal** | Durable goal/checkpoint/evidence artifacts without starting a loop                      | Handoffs, audits, or unavailable/conflicting loop runtimes              |
| **Pipeline**                | Sequential, staged processing                                                           | Multi-step transformations with strict ordering                         |
| **Ultrapilot (legacy)**     | Deprecated compatibility mode (autopilot pipeline alias)                                | Existing workflows and older docs                                       |

### Goal Workflow Guidance

Use only one primary loop authority in a session. Claude Code `/goal` is useful for a native cross-turn completion condition, while Ralph owns single-agent verified completion, Team owns parallel staged execution, and UltraQA owns repeated quality-gate cycling. Artifact-only Ultragoal is the safe fallback when you need durable goal artifacts and evidence without starting another loop.

For `/goal` behavior, rely on Claude Code/Anthropic sources: the [Claude Code `/goal` docs](https://code.claude.com/docs/en/goal) and [Anthropic Claude Code changelog](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md). Do **not** claim the `/goal` evaluator independently runs commands or reads files; surface test output, diffs, and review evidence in the conversation before treating a goal as proven.

### Intelligent Orchestration

- **19 specialized agents** (with tier variants) for architecture, research, design, testing, data science
- **Smart model routing** - Haiku for simple tasks, Opus for complex reasoning
- **Automatic delegation** - Right agent for the job, every time
- **[Model × Agent Compatibility Matrix](docs/agents/model-compatibility.md)** - Which model to pair with each agent, with premium/balanced/budget presets

### Developer Experience

- **Magic keywords** - `ralph`, `ulw`, `ralplan`; Team stays explicit via `/team`
- **HUD statusline** - Real-time orchestration metrics in your status bar
  - If you launch Claude Code directly with `claude --plugin-dir ` (bypassing the `omc` shim), export `OMC_PLUGIN_ROOT=` in your shell so the HUD bundle resolves to the same checkout as the plugin loader. See the [Plugin directory flags section in REFERENCE.md](./docs/REFERENCE.md#plugin-directory-flags) for details.
- **Skill learning** - Extract reusable patterns from your sessions
- **Analytics & cost tracking** - Understand token usage across all sessions

### Contributing

Want to contribute to OMC? See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full developer guide, including how to fork, set up a local checkout, link it as your active plugin, run tests, and submit PRs.

### Custom Skills

Learn once, reuse forever. OMC extracts hard-won debugging knowledge into portable skill files that auto-inject when relevant.

|                 | Project Scope                                            | User Scope        |
| --------------- | -------------------------------------------------------- | ----------------- |
| **Path**        | `.omc/skills/`                                           | `~/.omc/skills/`  |
| **Shared with** | Team (commit the skill file to keep it across worktrees) | All your projects |
| **Priority**    | Higher (overrides user)                                  | Lower (fallback)  |

```yaml
# .omc/skills/fix-proxy-crash.md
---
name: Fix Proxy Crash
triggers: ["proxy", "aiohttp", "disconnected"]
source: extracted
---
Wrap handler at server.py:42 in try/except ClientDisconnectedError...
```

**Manage skills:** `/skill list | add | remove | edit | search`
**Skillify:** `/skillify` extracts reusable patterns with strict quality gates
**Auto-inject:** Matching skills load into context automatically — no manual recall needed

Project-scoped OMC-authored skills are stored in `.omc/skills/` and are intended to be committed when you want them shared. During slash/skill execution OMC also reads Claude Code workspace skills from `.claude/skills/` and compatibility skills from `.agents/skills/`, so existing workspace-local `SKILL.md` packages remain callable without copying them into user-global skills. If you create project-local skills inside a linked git worktree and do not commit them, they disappear when that worktree is removed.

### `.omc/` state and git

OMC writes runtime state, session data, plans, logs, handoffs, research notes, and local artifacts under `.omc/` by default. The repository `.gitignore` keeps that runtime data local with one intentional exception: `.omc/skills/**` remains committable for project-scoped skills you want to share with the team. Treat everything else under `.omc/` as local operational state that may contain prompts, transcripts, or machine-specific paths.

For linked git worktrees, the default `.omc/` directory lives inside that worktree, so deleting the worktree deletes its local OMC state. Set `OMC_STATE_DIR` if you want state to survive worktree deletion, or add a `.omc-workspace` marker when several independent repos should share one parent-level state root. See [OMC state, gitignore, worktree, and workspace contract](docs/REFERENCE.md#omc-state-gitignore-worktree-and-workspace-contract).

[Full feature list →](docs/REFERENCE.md)

### Multi-repo workspaces

When several independent git repos share a parent directory, drop a `.omc-workspace` marker at the parent so all sub-repos share one `.omc/` state root:

```bash
cd /path/to/parent-dir-with-many-repos
echo '{"id":"my-workspace"}' > .omc-workspace
# Sessions inside any sub-repo now share /path/.omc/
# For parallel ultragoal runs:
cd repo-A && omc ultragoal create-goals --auto-plan-id --brief "..."
cd ../repo-B && omc ultragoal create-goals --auto-plan-id --brief "..."
```

See [Multi-repo workspaces in REFERENCE.md](docs/REFERENCE.md#multi-repo-workspaces-with-omc-workspace) for resolution order, `OMC_STATE_DIR`, and workspace identifier options.

---

## In-session shortcuts

These shortcuts run **inside a Claude Code / OMC session**, not as terminal CLI commands. For shell commands, use the `omc ...` forms shown above. Team mode is explicit: use `/team ...` in-session or `omc team ...` from your shell rather than expecting a bare `team` keyword trigger.

| In-session form            | Kind                   | Effect                                 | Example                                        |
| -------------------------- | ---------------------- | -------------------------------------- | ---------------------------------------------- |
| `/team`                    | Slash skill            | Canonical Team orchestration           | `/team 3:executor "fix all TypeScript errors"` |
| `/ccg`                     | Slash skill            | `/ask codex` + `/ask antigravity` synthesis | `/ccg review this PR`                          |
| `/autopilot` / `autopilot` | Skill / prompt trigger | Full autonomous execution              | `/autopilot "build a todo app"`                |
| `/ralph` / `ralph`         | Skill / prompt trigger | Persistence mode                       | `/ralph "refactor auth"`                       |
| `/ultrawork` / `ulw`       | Skill / prompt trigger | Maximum parallelism                    | `/ultrawork "fix all errors"`                  |
| `/ralplan` / `ralplan`     | Skill / prompt trigger | Iterative planning consensus           | `/ralplan "plan this feature"`                 |
| `/deep-interview`          | Slash skill            | Socratic requirements clarification    | `/deep-interview "vague idea"`                 |
| `deepsearch`               | Prompt trigger         | Codebase-focused search routing        | `deepsearch for auth middleware`               |
| `ultrathink`               | Prompt trigger         | Deep reasoning mode                    | `ultrathink about this architecture`           |
| `cancelomc`, `stopomc`     | Prompt trigger         | Stop active OMC modes                  | `stopomc`                                      |

**Notes:**

- **ralph includes ultrawork**: when you activate ralph mode, it automatically includes ultrawork's parallel execution.
- `swarm` compatibility alias has been removed; migrate existing prompts to `/team` syntax.
- `plan this` / `plan the` keyword triggers were removed; use `ralplan` or explicit `/oh-my-claudecode:plan`.

## Utilities

### Provider Advisor (`omc ask` / `/ask`)

Run local provider CLIs and save a markdown artifact under `.omc/artifacts/ask/`.

```bash
# Terminal CLI
omc ask claude "review this migration plan"
omc ask codex --prompt "identify architecture risks"
omc ask gemini --prompt "propose UI polish ideas"
omc ask antigravity --prompt "propose UI polish ideas"
omc ask grok --prompt "cross-check this code review"
omc ask cursor --prompt "apply this implementation plan"
omc ask claude --agent-prompt executor --prompt "draft implementation steps"

# Inside a Claude Code / OMC session
/ask claude "review this migration plan"
/ask codex "identify architecture risks"
/ask antigravity "propose UI polish ideas"
/ask cursor "apply this implementation plan"
```

Canonical env vars:

- `OMC_ASK_ADVISOR_SCRIPT`
- `OMC_ASK_ORIGINAL_TASK`

Phase-1 aliases `OMX_ASK_ADVISOR_SCRIPT` and `OMX_ASK_ORIGINAL_TASK` are accepted with deprecation warnings.

### Autoresearch (stateful skill)

`omc autoresearch` is now a **hard-deprecated shim**. The authoritative workflow is:

```bash
/deep-interview --autoresearch improve startup performance
/oh-my-claudecode:autoresearch
```

- `deep-interview --autoresearch` generates/sets up the mission and evaluator
- `autoresearch` runs the bounded, single-mission stateful loop
- each iteration records evaluation JSON plus markdown decision logs
- non-passing iterations continue
- strict stopping is controlled by an explicit max-runtime ceiling

### Rate Limit Wait

Auto-resume Claude Code sessions when rate limits reset.

```bash
omc wait          # Check status, get guidance
omc wait --start  # Enable auto-resume daemon
omc wait --stop   # Disable daemon
```

**Requires:** tmux (for session detection)

### Monitoring & Observability

Use the HUD for live observability and the current session/replay artifacts for post-session inspection:

- HUD preset: `/oh-my-claudecode:hud setup` then use a supported preset such as `"omcHud": { "preset": "focused" }`
- Session summaries: `.omc/sessions/*.json`
- Replay logs: `.omc/state/agent-replay-*.jsonl`
- Live HUD rendering: `omc hud`
- Local friction reports: `omc session friction report --since 24h` summarizes context-bloat and operator-friction signals from local session artifacts without printing raw prompts or tool output; add `--json` for automation.

### Notification Tags (Telegram/Discord/Slack)

You can configure who gets tagged when stop callbacks send session summaries.

```bash
# Set/replace tag list
omc config-stop-callback telegram --enable --token  --chat <chat_id> --tag-list "@alice,bob"
omc config-stop-callback discord --enable --webhook  --tag-list "@here,123456789012345678,role:987654321098765432"
omc config-stop-callback slack --enable --webhook  --tag-list "<!here>,<@U1234567890>"

# Incremental updates
omc config-stop-callback telegram --add-tag charlie
omc config-stop-callback discord --remove-tag @here
omc config-stop-callback discord --clear-tags
```

Tag behavior:

- Telegram: `alice` becomes `@alice`
- Discord: supports `@here`, `@everyone`, numeric user IDs, and `role:`
- Slack: supports `<@MEMBER_ID>`, `<!channel>`, `<!here>`, `<!everyone>`, `<!subteam^GROUP_ID>`
- `file` callbacks ignore tag options

### OpenClaw Integration

Forward Claude Code session events to an [OpenClaw](https://openclaw.ai/) gateway to enable automated responses and workflows via your OpenClaw agent.

**Quick setup (recommended):**

```bash
/oh-my-claudecode:configure-notifications
# → When prompted, type "openclaw" → choose "OpenClaw Gateway"
```

**Manual setup:** create `~/.claude/omc_config.openclaw.json`:

```json
{
  "enabled": true,
  "gateways": {
    "my-gateway": {
      "url": "https://your-gateway.example.com/wake",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "method": "POST",
      "timeout": 10000
    }
  },
  "hooks": {
    "session-start": {
      "gateway": "my-gateway",
      "instruction": "Session started for {{projectName}}",
      "enabled": true
    },
    "stop": {
      "gateway": "my-gateway",
      "instruction": "Session stopping for {{projectName}}",
      "enabled": true
    }
  }
}
```

**Environment variables:**

| Variable                                   | Description               |
| ------------------------------------------ | ------------------------- |
| `OMC_OPENCLAW=1`                           | Enable OpenClaw           |
| `OMC_OPENCLAW_DEBUG=1`                     | Enable debug logging      |
| `OMC_OPENCLAW_CONFIG=/path/to/config.json` | Override config file path |

**Supported hook events (6 active in bridge.ts):**

| Event               | Trigger                                 | Key template variables                                |
| ------------------- | --------------------------------------- | ----------------------------------------------------- |
| `session-start`     | Session begins                          | `{{sessionId}}`, `{{projectName}}`, `{{projectPath}}` |
| `stop`              | Claude response completes               | `{{sessionId}}`, `{{projectName}}`                    |
| `keyword-detector`  | Every prompt submission                 | `{{prompt}}`, `{{sessionId}}`                         |
| `ask-user-question` | Claude requests user input              | `{{question}}`, `{{sessionId}}`                       |
| `pre-tool-use`      | Before tool invocation (high frequency) | `{{toolName}}`, `{{sessionId}}`                       |
| `post-tool-use`     | After tool invocation (high frequency)  | `{{toolName}}`, `{{sessionId}}`                       |

**Reply channel environment variables:**

| Variable                 | Description                    |
| ------------------------ | ------------------------------ |
| `OPENCLAW_REPLY_CHANNEL` | Reply channel (e.g. `discord`) |
| `OPENCLAW_REPLY_TARGET`  | Channel ID                     |
| `OPENCLAW_REPLY_THREAD`  | Thread ID                      |

See `scripts/openclaw-gateway-demo.mjs` for a reference gateway that relays OpenClaw payloads to a custom HTTPS automation endpoint.

---

## Documentation

- **[Full Reference](docs/REFERENCE.md)** - Complete feature documentation
- **[CLI Reference](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#cli-reference)** - All `omc` commands, flags, and tools
- **[Notifications Guide](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#notifications)** - Discord, Telegram, Slack, and webhook setup
- **[Recommended Workflows](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#workflows)** - Battle-tested skill chains for common tasks
- **[Release Notes](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#release-notes)** - What's new in each version
- **[Website](https://yeachan-heo.github.io/oh-my-claudecode-website)** - Interactive guides and examples
- **[Migration Guide](docs/MIGRATION.md)** - Upgrade from v2.x
- **[Architecture](docs/ARCHITECTURE.md)** - How it works under the hood
- **[Performance Monitoring](docs/PERFORMANCE-MONITORING.md)** - Agent tracking, debugging, and optimization
- **[Model × Agent Compatibility Matrix](docs/agents/model-compatibility.md)** - Which model to pair with each agent (premium / balanced / budget presets)
- **[Security Guide](SECURITY.md)** - Enterprise deployment and hardening

---

## Requirements

- [Claude Code](https://docs.anthropic.com/claude-code) CLI
- Claude Max/Pro subscription OR Anthropic API key

### Platform & tmux

OMC features like `omc team` and rate-limit detection require **tmux**:

| Platform       | tmux provider                                         | Install                 |
| -------------- | ----------------------------------------------------- | ----------------------- |
| macOS          | [tmux](https://github.com/tmux/tmux)                  | `brew install tmux`     |
| Ubuntu/Debian  | tmux                                                  | `sudo apt install tmux` |
| Fedora         | tmux                                                  | `sudo dnf install tmux` |
| Arch           | tmux                                                  | `sudo pacman -S tmux`   |
| Windows        | [psmux](https://github.com/marlocarlo/psmux) (native) | `winget install psmux`  |
| Windows (WSL2) | tmux (inside WSL)                                     | `sudo apt install tmux` |

> **Windows users:** [psmux](https://github.com/marlocarlo/psmux) provides a native `tmux` binary for Windows with 76 tmux-compatible commands. No WSL required.

### Optional: Multi-AI Orchestration

OMC can optionally orchestrate external AI providers for cross-validation and design consistency. These are **not required** — OMC works fully without them.

| Provider                                                                | Install                                                      | What it enables                                                           |
| ----------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- |
| [Antigravity CLI](https://antigravity.google) (`agy`)                   | Install per the [official instructions](https://antigravity.google) (provides the `agy` binary) | Design review, UI consistency — Google's successor to the Gemini CLI |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli)               | `npm install @google/gemini-cli`                          | Design review, UI consistency (1M token context) — enterprise/API-key access unaffected |
| [Codex CLI](https://github.com/openai/codex)                            | `npm install @openai/codex`                               | Architecture validation, code review cross-check                          |
| [Grok Build](https://build.grok.com)                                    | Download from build.grok.com (`grok` at `~/.grok/bin/grok`) | Code review, analysis cross-check                                         |

> **Migrating from Gemini CLI:** Per Google's announcement, the Gemini CLI is being superseded by the Antigravity CLI (`agy`); see the [official Antigravity docs](https://antigravity.google). Use `omc team N:antigravity` and `omc ask antigravity` wherever you previously used `gemini`. Windows headless support for `agy` is unknown/untested — report issues upstream.

**Cost:** 3 Pro plans (Claude + Antigravity/Gemini + ChatGPT) cover everything for ~$60/month.

---

## License

MIT

---




## Featured by OmC Contributors

Top personal non-fork, non-archived repos from all-time OMC contributors (100+ GitHub stars).

- [@Yeachan-Heo](https://github.com/Yeachan-Heo) — [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) (⭐ 38k)
- [@junhoyeo](https://github.com/junhoyeo) — [tokscale](https://github.com/junhoyeo/tokscale) (⭐ 4.8k)
- [@psmux](https://github.com/psmux) — [psmux](https://github.com/psmux/psmux) (⭐ 3.2k)
- [@MeroZemory](https://github.com/MeroZemory) — [ida-multi-mcp](https://github.com/MeroZemory/ida-multi-mcp) (⭐ 375)
- [@devswha](https://github.com/devswha) — [patina](https://github.com/devswha/patina) (⭐ 312)
- [@BowTiedSwan](https://github.com/BowTiedSwan) — [buildflow](https://github.com/BowTiedSwan/buildflow) (⭐ 295)
- [@J-Pster](https://github.com/J-Pster) — [Psters_AI_Workflow](https://github.com/J-Pster/Psters_AI_Workflow) (⭐ 291)
- [@alohays](https://github.com/alohays) — [awesome-visual-representation-learning-with-transformers](https://github.com/alohays/awesome-visual-representation-learning-with-transformers) (⭐ 271)
- [@jcwleo](https://github.com/jcwleo) — [random-network-distillation-pytorch](https://github.com/jcwleo/random-network-distillation-pytorch) (⭐ 263)
- [@HaD0Yun](https://github.com/HaD0Yun) — [Doyunha-Gopeak](https://github.com/HaD0Yun/Doyunha-Gopeak) (⭐ 238)
- [@shaun0927](https://github.com/shaun0927) — [openchrome](https://github.com/shaun0927/openchrome) (⭐ 231)
- [@emgeee](https://github.com/emgeee) — [mean-tutorial](https://github.com/emgeee/mean-tutorial) (⭐ 200)
- [@anduinnn](https://github.com/anduinnn) — [HiFiNi-Auto-CheckIn](https://github.com/anduinnn/HiFiNi-Auto-CheckIn) (⭐ 171)
- [@changeroa](https://github.com/changeroa) — [StyleGallery](https://github.com/changeroa/StyleGallery) (⭐ 154)
- [@Znuff](https://github.com/Znuff) — [consolas-powerline](https://github.com/Znuff/consolas-powerline) (⭐ 145)



## Star History

[](https://www.star-history.com/#Yeachan-Heo/oh-my-claudecode&type=date&legend=top-left)

## 💖 Support This Project

If Oh-My-ClaudeCode helps your workflow, consider sponsoring:

[](https://github.com/sponsors/Yeachan-Heo)

### Why sponsor?

- Keep development active
- Priority support for sponsors
- Influence roadmap & features
- Help maintain free & open source

### Other ways to help

- ⭐ Star the repo
- 🐛 Report bugs
- 💡 Suggest features
- 📝 Contribute code

## GEO visibility benchmark

OmC includes a [`geobench`](https://github.com/NomaDamas/geobench) product spec for measuring LLM hit rate, MRR, share of voice, and citations.

- Spec: [`geobench/oh-my-claudecode.yaml`](geobench/oh-my-claudecode.yaml)
- Runbook: [`docs/geobench.md`](docs/geobench.md)

---

## File: benchmark/results/README.md

# SWE-bench Verified Results

## Summary

| Mode | Pass Rate | Avg Tokens | Avg Time | Total Cost |
|------|-----------|------------|----------|------------|
| Vanilla | -% | - | -m | $- |
| OMC | -% | - | -m | $- |

**Delta:** - percentage points improvement

## Methodology

### Dataset

- **Benchmark:** SWE-bench Verified (500 instances)
- **Source:** princeton-nlp/SWE-bench_Verified
- **Selection:** Curated subset of real GitHub issues with verified solutions

### Evaluation Setup

- **Model:** Claude Sonnet 5 (claude-sonnet-5)
- **Max Tokens:** 16,384 output tokens per instance
- **Timeout:** 30 minutes per instance
- **Workers:** 4 parallel evaluations
- **Hardware:** [Specify machine type]

### Vanilla Configuration

Standard Claude Code with default settings:
- No OMC extensions loaded
- Default system prompt
- Single-agent execution

### OMC Configuration

Oh-My-ClaudeCode enhanced with:
- Multi-agent orchestration
- Specialist delegation (architect, executor, etc.)
- Ralph persistence loop for complex tasks
- Ultrawork parallel execution
- Automatic skill invocation

### Metrics Collected

1. **Pass Rate:** Percentage of instances where generated patch passes all tests
2. **Token Usage:** Input + output tokens consumed per instance
3. **Time:** Wall-clock time from start to patch generation
4. **Cost:** Estimated API cost based on token usage

## Results Breakdown

### By Repository

| Repository | Vanilla | OMC | Delta |
|------------|---------|-----|-------|
| django | -/- | -/- | - |
| flask | -/- | -/- | - |
| requests | -/- | -/- | - |
| ... | ... | ... | ... |

### By Difficulty

| Difficulty | Vanilla | OMC | Delta |
|------------|---------|-----|-------|
| Easy | -% | -% | - |
| Medium | -% | -% | - |
| Hard | -% | -% | - |

### Failure Analysis

Top failure categories for each mode:

**Vanilla:**
1. Category: N failures (N%)
2. ...

**OMC:**
1. Category: N failures (N%)
2. ...

## Improvements

Instances that OMC solved but vanilla failed:

| Instance ID | Category | Notes |
|-------------|----------|-------|
| ... | ... | ... |

## Regressions

Instances that vanilla solved but OMC failed:

| Instance ID | Category | Notes |
|-------------|----------|-------|
| ... | ... | ... |

## Reproduction

### Prerequisites

```bash
# Install SWE-bench
pip install swebench

# Install oh-my-claudecode (if testing OMC)
# Follow setup instructions in main README
```

### Running Vanilla Baseline

```bash
# Generate predictions
python run_benchmark.py --mode vanilla --dataset swe-bench-verified --output results/vanilla/

# Evaluate
python evaluate.py --predictions results/vanilla/predictions.json --output results/vanilla/
```

### Running OMC

```bash
# Generate predictions with OMC
python run_benchmark.py --mode omc --dataset swe-bench-verified --output results/omc/

# Evaluate
python evaluate.py --predictions results/omc/predictions.json --output results/omc/
```

### Comparing Results

```bash
python compare_results.py --vanilla results/vanilla/ --omc results/omc/ --output comparison/
```

### Analyzing Failures

```bash
python analyze_failures.py --vanilla results/vanilla/ --omc results/omc/ --compare --output analysis/
```

## Files

```
results/
├── vanilla/
│   ├── predictions.json      # Generated patches
│   ├── summary.json          # Evaluation summary
│   ├── report.md             # Human-readable report
│   └── logs/                 # Per-instance logs
├── omc/
│   ├── predictions.json
│   ├── summary.json
│   ├── report.md
│   └── logs/
├── comparison/
│   ├── comparison_*.json     # Detailed comparison data
│   ├── comparison_*.md       # Comparison report
│   └── comparison_*.csv      # Per-instance CSV
└── analysis/
    ├── failure_analysis_*.json
    └── failure_analysis_*.md
```

## Notes

- Results may vary based on API model version and temperature
- Some instances may have non-deterministic test outcomes
- Cost estimates are approximate based on published pricing

## References

- [SWE-bench Paper](https://arxiv.org/abs/2310.06770)
- [SWE-bench Repository](https://github.com/princeton-nlp/SWE-bench)
- [Oh-My-ClaudeCode Documentation](../README.md)

---

*Last updated: [DATE]*

---

## File: benchmark/README.md

# SWE-bench Benchmark Suite

Automated benchmark comparison between vanilla Claude Code and OMC-enhanced Claude Code.

## Quick Start

```bash
# 1. One-time setup
./setup.sh

# 2. Quick sanity test (5 instances)
./quick_test.sh

# 3. Full comparison
./run_full_comparison.sh
```

## Scripts

### setup.sh
One-time setup and verification:
- Installs Python dependencies
- Builds Docker image for SWE-bench
- Downloads and caches dataset
- Verifies API key
- Builds OMC project
- Runs sanity checks

**Usage:**
```bash
./setup.sh
```

### quick_test.sh
Quick sanity test with limited instances (default: 5):
- Tests both vanilla and OMC modes
- Fast verification before full runs
- Recommended before production benchmarks

**Usage:**
```bash
./quick_test.sh [--limit N] [--model MODEL] [--timeout SECS]
```

**Examples:**
```bash
./quick_test.sh                    # Test 5 instances
./quick_test.sh --limit 10         # Test 10 instances
./quick_test.sh --timeout 300      # 5 minutes per instance
```

### run_vanilla.sh
Run vanilla Claude Code benchmark:
- Standard Claude Code without OMC
- Saves predictions to `predictions/vanilla/`
- Logs to `logs/vanilla_*.log`

**Usage:**
```bash
./run_vanilla.sh [OPTIONS]
```

**Options:**
- `--limit N` - Limit to N instances (default: all)
- `--skip N` - Skip first N instances (default: 0)
- `--model MODEL` - Claude model to use (default: claude-sonnet-5)
- `--timeout SECS` - Timeout per instance (default: 300)

**Examples:**
```bash
./run_vanilla.sh                           # Full benchmark
./run_vanilla.sh --limit 100               # First 100 instances
./run_vanilla.sh --skip 100 --limit 100    # Instances 101-200
./run_vanilla.sh --timeout 600             # 10 minutes per instance
```

### run_omc.sh
Run OMC-enhanced benchmark:
- Claude Code with oh-my-claudecode orchestration
- Saves predictions to `predictions/omc/`
- Logs to `logs/omc_*.log`

**Usage:**
```bash
./run_omc.sh [OPTIONS]
```

**Options:** Same as `run_vanilla.sh`

**Examples:**
```bash
./run_omc.sh                    # Full benchmark
./run_omc.sh --limit 100        # First 100 instances
```

### run_full_comparison.sh
Complete benchmark suite:
- Runs vanilla benchmark
- Runs OMC benchmark
- Evaluates both runs
- Generates comparison report

**Usage:**
```bash
./run_full_comparison.sh [OPTIONS]
```

**Options:**
- `--limit N` - Limit to N instances
- `--skip N` - Skip first N instances
- `--model MODEL` - Claude model to use
- `--timeout SECS` - Timeout per instance
- `--skip-vanilla` - Skip vanilla benchmark run
- `--skip-omc` - Skip OMC benchmark run
- `--skip-eval` - Skip evaluation step

**Examples:**
```bash
./run_full_comparison.sh                    # Full comparison
./run_full_comparison.sh --limit 100        # Test 100 instances
./run_full_comparison.sh --skip-vanilla     # Only run OMC (reuse vanilla results)
```

## Directory Structure

```
benchmark/
├── setup.sh                    # One-time setup
├── quick_test.sh              # Quick sanity test
├── run_vanilla.sh             # Run vanilla benchmark
├── run_omc.sh                 # Run OMC benchmark
├── run_full_comparison.sh     # Full comparison suite
├── run_benchmark.py           # Main Python benchmark runner
├── Dockerfile                 # Docker image for SWE-bench
├── docker-compose.yml         # Docker compose config
├── requirements.txt           # Python dependencies
├── predictions/
│   ├── vanilla/              # Vanilla predictions
│   └── omc/                  # OMC predictions
├── logs/
│   ├── vanilla_*.log         # Vanilla run logs
│   └── omc_*.log            # OMC run logs
├── results/
│   ├── vanilla_results.json  # Vanilla evaluation
│   ├── omc_results.json      # OMC evaluation
│   └── comparison_report.md  # Comparison report
├── data/                      # Test data
└── cache/                     # Dataset cache
```

## Prerequisites

- Docker
- Python 3.8+
- Node.js and npm
- ANTHROPIC_API_KEY environment variable

```bash
export ANTHROPIC_API_KEY=your_key_here
```

## Workflow

1. **Setup** (one-time):
   ```bash
   ./setup.sh
   ```

2. **Quick Test** (recommended):
   ```bash
   ./quick_test.sh
   ```

3. **Full Benchmark**:
   ```bash
   # Option A: Run full comparison
   ./run_full_comparison.sh

   # Option B: Run individually
   ./run_vanilla.sh
   ./run_omc.sh
   ```

4. **Review Results**:
   - Check `results/comparison_report.md`
   - Inspect predictions in `predictions/vanilla/` and `predictions/omc/`
   - Review logs in `logs/`

## Troubleshooting

### Setup Issues
```bash
./setup.sh
# Check output for specific errors
```

### API Key Issues
```bash
# Verify API key is set
echo $ANTHROPIC_API_KEY

# Export if missing
export ANTHROPIC_API_KEY=your_key_here
```

### Docker Issues
```bash
# Check Docker is running
docker ps

# Rebuild image
docker build -t swe-bench-runner .
```

### Python Dependencies
```bash
# Reinstall dependencies
pip install -r requirements.txt
```

## Advanced Usage

### Custom Model
```bash
./run_vanilla.sh --model claude-opus-4-6-20260205
./run_omc.sh --model claude-opus-4-6-20260205
```

### Longer Timeout
```bash
# 15 minutes per instance
./run_full_comparison.sh --timeout 900
```

### Subset Testing
```bash
# Test instances 50-150
./run_full_comparison.sh --skip 50 --limit 100
```

### Resume Failed Run
```bash
# If vanilla failed at instance 42, skip to 42 and continue
./run_vanilla.sh --skip 42
```

## Performance Tips

1. **Start Small**: Use `quick_test.sh` to verify setup
2. **Parallel Runs**: Don't run vanilla and OMC in parallel (share API rate limits)
3. **Monitor Logs**: Use `tail -f logs/vanilla_*.log` to watch progress
4. **Timeout Tuning**: Increase timeout for complex instances
5. **Disk Space**: Ensure sufficient space for predictions and Docker containers

## Interpreting Results

### Metrics
- **Solve Rate**: Percentage of instances successfully resolved
- **Token Usage**: Average tokens per instance
- **Time**: Average time per instance
- **Error Rate**: Percentage of instances that errored

### Comparison Report
The `results/comparison_report.md` includes:
- Side-by-side metrics
- Statistical significance tests
- Instance-level comparisons
- Qualitative analysis

## License

Same as parent project (MIT)

---

## File: docs/agent-templates/base-agent.md

# {{AGENT_NAME}}

## Role
{{ROLE_DESCRIPTION}}

## Tier-Specific Instructions
{{TIER_INSTRUCTIONS}}

## Worker Preamble Protocol

When orchestrators delegate to this agent, they should wrap task descriptions with the Worker Preamble to ensure:
- Agent executes tasks directly without spawning sub-agents
- Agent uses tools directly (Read, Write, Edit, Bash, etc.)
- Agent reports results with absolute file paths

See `src/agents/preamble.ts` for the `wrapWithPreamble()` utility.

## Common Protocol

### Verification Before Completion
Before claiming "done", "fixed", or "complete":
1. **IDENTIFY**: What command proves this claim?
2. **RUN**: Execute verification (test, build, lint)
3. **READ**: Check output - did it actually pass?
4. **ONLY THEN**: Make the claim with evidence

Red flags that require verification:
- Using "should", "probably", "seems to"
- Expressing satisfaction before running verification
- Claiming completion without fresh test/build output

### Tool Usage
- Use Read tool for examining files (NOT cat/head/tail)
- Use Edit tool for modifying files (NOT sed/awk)
- Use Write tool for creating new files (NOT echo >)
- Use Grep for content search (NOT grep/rg commands)
- Use Glob for file search (NOT find/ls)
- Use Bash tool ONLY for git, npm, build commands, tests

### File Operations
- Always read a file before editing it
- Preserve exact indentation when editing
- Verify edits with fresh reads after changes

### Communication
- Report findings clearly and concisely
- Include file paths (absolute) and line numbers
- Show evidence for all claims
- Escalate when encountering blockers

### Error Handling
- Never ignore errors or warnings
- Investigate root causes before fixing
- Document workarounds if needed
- Ask for help when stuck

## Task Execution

{{TASK_SPECIFIC_INSTRUCTIONS}}

## Deliverables

{{EXPECTED_DELIVERABLES}}

---

## File: docs/agent-templates/README.md

# Agent Prompt Templates

This directory contains reusable templates for creating agent prompts, reducing duplication across tiers.

## Files

- **base-agent.md**: Core template structure with injection points
- **tier-instructions.md**: Tier-specific behavioral instructions (LOW/MEDIUM/HIGH)
- **README.md**: This file - usage guide

## Template System

### Injection Points

The template uses the following placeholders:

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{AGENT_NAME}}` | Agent identifier | `executor-low`, `architect-medium` |
| `{{ROLE_DESCRIPTION}}` | What this agent does | "You execute simple code changes..." |
| `{{TIER_INSTRUCTIONS}}` | Tier-specific behavior | LOW/MEDIUM/HIGH instructions |
| `{{TASK_SPECIFIC_INSTRUCTIONS}}` | Agent-specific protocols | "When fixing bugs, always add tests" |
| `{{EXPECTED_DELIVERABLES}}` | What to output | "Modified files + test results" |

### Usage

1. **Copy the base template**:
   ```bash
   cp agents/templates/base-agent.md agents/my-new-agent.md
   ```

2. **Replace placeholders**:
   - Set `{{AGENT_NAME}}` to your agent name
   - Write `{{ROLE_DESCRIPTION}}` specific to your agent
   - Copy appropriate tier instructions from `tier-instructions.md`
   - Add any `{{TASK_SPECIFIC_INSTRUCTIONS}}` unique to this agent
   - Define `{{EXPECTED_DELIVERABLES}}`

3. **Review common protocol**:
   - The base template includes shared verification and tool usage protocols
   - These apply to ALL agents and don't need modification
   - Only extend if your agent needs additional protocols

### Example: Creating executor-low

```markdown
# executor-low

## Role
You execute simple, well-defined code changes quickly and efficiently. Handle single-file modifications, small bug fixes, and straightforward feature additions.

## Tier-Specific Instructions
**Tier: LOW (Haiku) - Speed-Focused Execution**

- Focus on speed and direct execution
- Handle simple, well-defined tasks only
- Limit exploration to 5 files maximum
- Escalate to executor (MEDIUM) if:
  - Task requires analyzing more than 5 files
  - Complexity is higher than expected
  - Architectural decisions needed
- Prefer straightforward solutions over clever ones
- Skip deep investigation - implement what's asked

## Common Protocol
[... standard protocol from base-agent.md ...]

## Task Execution
- Read the target file first
- Make the requested changes
- Run lsp_diagnostics on changed files
- Verify changes compile/pass basic checks

## Deliverables
- Modified file(s)
- lsp_diagnostics output showing no new errors
- Brief summary of changes made
```

## Benefits

1. **Consistency**: All agents follow the same verification protocol
2. **Maintainability**: Update common protocols in one place
3. **Clarity**: Clear separation of tier vs. role-specific instructions
4. **Scalability**: Easy to add new agents or tiers

## Best Practices

- **Don't override common protocol** unless absolutely necessary
- **Be specific in role descriptions** - avoid vague terms like "handle tasks"
- **Document escalation paths** - when should this agent call another?
- **Include examples** in task-specific instructions when helpful
- **Keep tier instructions pure** - only capability/scope guidance, not role-specific behavior

## Tier Selection Guide

| Tier | Model | Token Cost | Use When |
|------|-------|------------|----------|
| LOW | Haiku | $ | Task is simple, well-defined, <5 files |
| MEDIUM | Sonnet | $$ | Task needs investigation, <20 files |
| HIGH | Opus | $$$ | Task is complex, architectural, unlimited files |

## Future Enhancements

Potential additions to the template system:

- Domain-specific templates (frontend, backend, data, etc.)
- Composition templates for specialized agents
- Automated template validation
- Template generation CLI tool

---

## File: docs/agent-templates/tier-instructions.md

# Tier-Specific Instructions

This document defines the behavioral differences between agent tiers (LOW/MEDIUM/HIGH).

## LOW Tier (Haiku)
**Model**: claude-haiku-4-5
**Focus**: Speed and efficiency for simple, well-defined tasks

```markdown
**Tier: LOW (Haiku) - Speed-Focused Execution**

- Focus on speed and direct execution
- Handle simple, well-defined tasks only
- Limit exploration to 5 files maximum
- Escalate to MEDIUM tier if:
  - Task requires analyzing more than 5 files
  - Complexity is higher than expected
  - Architectural decisions needed
- Prefer straightforward solutions over clever ones
- Skip deep investigation - implement what's asked
```

## MEDIUM Tier (Sonnet)
**Model**: claude-sonnet-4-5
**Focus**: Balance between thoroughness and efficiency

```markdown
**Tier: MEDIUM (Sonnet) - Balanced Execution**

- Balance thoroughness with efficiency
- Can explore up to 20 files
- Handle moderate complexity tasks
- Consult architect agent for architectural decisions
- Escalate to HIGH tier if:
  - Task requires deep architectural changes
  - System-wide refactoring needed
  - Complex debugging across many components
- Consider edge cases but don't over-engineer
- Document non-obvious decisions
```

## HIGH Tier (Opus)
**Model**: claude-opus-4-8
**Focus**: Correctness and quality for complex tasks

```markdown
**Tier: HIGH (Opus) - Excellence-Focused Execution**

- Prioritize correctness and code quality above all
- Full codebase exploration allowed
- Make architectural decisions confidently
- Handle complex, ambiguous, or system-wide tasks
- Consider:
  - Long-term maintainability
  - Edge cases and error scenarios
  - Performance implications
  - Security considerations
- Thoroughly document reasoning
- No escalation needed - you are the top tier
```

## Selection Guide

| Task Type | Tier | Rationale |
|-----------|------|-----------|
| Simple bug fix in known file | LOW | Well-defined, single file |
| Add validation to existing function | LOW | Straightforward addition |
| Implement feature across 3-5 files | MEDIUM | Moderate scope |
| Debug integration issue | MEDIUM | Requires investigation |
| Refactor module architecture | HIGH | Architectural decision |
| Design new system component | HIGH | Complex design needed |
| Fix subtle race condition | HIGH | Deep debugging required |
| Optimize performance bottleneck | HIGH | Requires deep analysis |

## Template Usage

When creating an agent prompt, replace `{{TIER_INSTRUCTIONS}}` with the appropriate tier block above.

Example for executor-low:
```markdown
# executor-low

## Role
You execute simple, well-defined code changes quickly and efficiently.

## Tier-Specific Instructions
**Tier: LOW (Haiku) - Speed-Focused Execution**

- Focus on speed and direct execution
- Handle simple, well-defined tasks only
- Limit exploration to 5 files maximum
- Escalate to MEDIUM tier if complexity exceeds expectations
...
```

---

## File: docs/design/CONSOLIDATION_PHASE3_ROADMAP.md

# Consolidation Phase 3+ Roadmap

## Context

Phase 2 landed alias-based consolidation and Tier-0 contract protection for:

- `ralplan`
- `team`
- `ralph`
- `ultrawork`
- `autopilot`

This roadmap defines the next wave: agent utilization cleanup, routing simplification, and migration governance.

## Goals

1. Reduce agent surface area without breaking compatibility.
2. Improve routing quality (right agent, right tier, less idle/duplicate delegation).
3. Formalize deprecation policy and rollout safety gates.

## Scope

### 1) Agent Catalog Consolidation

- Build canonical lanes:
  - discovery
  - planning/analysis
  - implementation
  - verification/review
- Mark legacy/overlapping roles as compatibility aliases.
- Keep stable compatibility map for old names.

### 2) Routing and Utilization

- Add explicit routing matrix from skill families -> canonical agent lanes.
- Add telemetry signals for:
  - invocation count
  - completion rate
  - retry rate
  - escalation rate
- Define thresholds for “keep / merge / deprecate”.

### 3) Migration Governance

- Tier classes:
  - Tier-0: immutable public contracts (already enforced)
  - Tier-1: stable core
  - Tier-2: consolidation candidates
- Two-release minimum deprecation window for non-Tier-0 names.
- Rollback guardrails via routing manifest toggles.

## Acceptance Criteria

- Canonical agent matrix documented and linked from `docs/REFERENCE.md`.
- Compatibility aliases remain functional for existing names.
- Regression tests cover:
  - alias fidelity
  - protected mode invariants
  - docs/runtime parity checks
- No regression to Tier-0 behavior.

## Proposed Delivery Plan

### Milestone A — Discovery + Metrics

- Inventory current agent usage and overlap.
- Propose keep/merge/deprecate candidates with evidence.

### Milestone B — Runtime Routing Cleanup

- Implement routing table changes + compatibility aliases.
- Add targeted tests for agent resolution behavior.

### Milestone C — Docs + Migration Policy

- Publish deprecation schedule and migration notes.
- Update AGENTS/docs consistency checks.

### Milestone D — Validation Gate

- Run full verification:
  - `npm test`
  - `npm run build`
  - `npm run lint`
- Validate no Tier-0 regressions.

## Risks

- Over-pruning specialized agents can reduce quality on edge tasks.
- Hidden coupling between hooks and specific agent names.
- Docs drift if naming changes are not synchronized.

## Risk Controls

- Alias-first migration (never hard-remove first).
- Protected-mode regression suite required on every consolidation PR.
- Incremental rollout with clear rollback path.

---

## File: docs/design/project-session-manager.md

# Project Session Manager (PSM) - Design Document

> **Skill Name:** `project-session-manager` (alias: `psm`)
> **Version:** 1.0.0
> **Author:** oh-my-claudecode
> **Status:** Design Draft

## Executive Summary

Project Session Manager (PSM) automates the creation and management of isolated development environments using git worktrees and tmux sessions with Claude Code. It enables parallel work across multiple tasks, projects, and repositories while maintaining clean separation and easy context switching.

---

## Table of Contents

1. [Problem Statement](#1-problem-statement)
2. [Use Cases](#2-use-cases)
3. [Command Interface](#3-command-interface)
4. [Architecture](#4-architecture)
5. [Directory Structure](#5-directory-structure)
6. [Session Naming Conventions](#6-session-naming-conventions)
7. [Workflow Presets](#7-workflow-presets)
8. [State Management](#8-state-management)
9. [Cleanup Strategies](#9-cleanup-strategies)
10. [Integration Points](#10-integration-points)
11. [Edge Cases & Error Handling](#11-edge-cases--error-handling)
12. [Security Considerations](#12-security-considerations)
13. [Future Enhancements](#13-future-enhancements)

---

## 1. Problem Statement

### Current Pain Points

1. **Context Switching Overhead**: Switching between tasks requires stashing changes, switching branches, and losing Claude Code context
2. **PR Review Isolation**: Reviewing PRs often contaminates the working directory
3. **Parallel Work Limitation**: Can only work on one task at a time per repository
4. **Session Management**: Manual tmux session creation is tedious and inconsistent
5. **Cleanup Burden**: Orphaned worktrees and sessions accumulate over time

### Solution

PSM provides a unified interface to:
- Create isolated worktrees with a single command
- Spawn pre-configured tmux sessions with Claude Code
- Track and manage all active sessions
- Automate cleanup of completed work

---

## 2. Use Cases

### 2.1 PR Review

```bash
# Review PR #123 from oh-my-claudecode repo
/psm review omc#123

# Review PR from any GitHub URL
/psm review https://github.com/anthropics/claude-code/pull/456

# Review with specific focus
/psm review omc#123 --focus "security implications"
```

**What happens:**
1. Fetches PR branch
2. Creates worktree at `~/.psm/worktrees/omc/pr-123`
3. Spawns tmux session `psm:omc:pr-123`
4. Launches Claude Code with PR context pre-loaded
5. Opens diff in editor (optional)

### 2.2 Issue Fixing

```bash
# Fix issue #42
/psm fix omc#42

# Fix with branch name override
/psm fix omc#42 --branch fix/auth-timeout

# Fix from issue URL
/psm fix https://github.com/anthropics/claude-code/issues/789
```

**What happens:**
1. Fetches issue details via `gh`
2. Creates feature branch from main
3. Creates worktree at `~/.psm/worktrees/omc/issue-42`
4. Spawns tmux session with issue context
5. Pre-populates Claude Code with issue description

### 2.3 Feature Development

```bash
# Start new feature
/psm feature omc "add-webhook-support"

# Feature from existing branch
/psm feature omc --branch feature/webhooks

# Feature with specific base
/psm feature omc "dark-mode" --base develop
```

**What happens:**
1. Creates feature branch from specified base
2. Creates worktree
3. Spawns session with feature context
4. Optionally creates draft PR

### 2.4 Release Preparation

```bash
# Prepare release
/psm release omc v3.5.0

# Release candidate
/psm release omc v3.5.0-rc1 --draft

# Hotfix release
/psm release omc v3.4.1 --hotfix --base v3.4.0
```

**What happens:**
1. Creates release branch
2. Creates worktree
3. Spawns session with release checklist
4. Pre-loads CHANGELOG context

### 2.5 Session Management

```bash
# List all sessions
/psm list

# List sessions for specific project
/psm list omc

# Attach to existing session
/psm attach omc:pr-123

# Detach current session (return to main)
/psm detach

# Kill specific session
/psm kill omc:pr-123

# Kill all sessions for project
/psm kill omc --all

# Cleanup completed sessions
/psm cleanup

# Cleanup aggressively (force)
/psm cleanup --force --older-than 7d
```

### 2.6 Quick Context Switch

```bash
# Switch to another session (detach current, attach target)
/psm switch omc:feature-auth

# Switch with session picker (fzf)
/psm switch
```

---

## 3. Command Interface

### 3.1 Primary Commands

| Command | Description | Aliases |
|---------|-------------|---------|
| `review <ref>` | Start PR review session | `pr`, `r` |
| `fix <ref>` | Start issue fix session | `issue`, `i` |
| `feature <name>` | Start feature development | `feat`, `f` |
| `release <version>` | Start release preparation | `rel` |
| `list [project]` | List active sessions | `ls`, `l` |
| `attach <session>` | Attach to session | `a` |
| `detach` | Detach from current | `d` |
| `switch [session]` | Switch sessions | `sw`, `s` |
| `kill <session>` | Kill session | `k`, `rm` |
| `cleanup` | Clean up completed | `gc`, `clean` |
| `status` | Show current session info | `st` |

### 3.2 Global Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--project`, `-p` | Project identifier or path | Current directory |
| `--no-claude` | Skip Claude Code launch | false |
| `--no-tmux` | Use current terminal | false |
| `--editor`, `-e` | Open in editor after | false |
| `--verbose`, `-v` | Verbose output | false |
| `--dry-run` | Show what would happen | false |

### 3.3 Project References

PSM supports multiple reference formats:

```bash
# Short alias (requires ~/.psm/projects.json config)
omc#123

# Full GitHub reference
anthropics/claude-code#123

# GitHub URL
https://github.com/anthropics/claude-code/pull/123

# Local path
/path/to/repo#123

# Current directory (implicit)
#123
```

### 3.4 Project Aliases Configuration

```json
// ~/.psm/projects.json
{
  "aliases": {
    "omc": {
      "repo": "anthropics/oh-my-claudecode",
      "local": "~/Workspace/oh-my-claudecode",
      "default_base": "main"
    },
    "cc": {
      "repo": "anthropics/claude-code",
      "local": "~/Workspace/claude-code",
      "default_base": "main"
    },
    "myapp": {
      "repo": "myorg/myapp",
      "local": "~/Projects/myapp",
      "default_base": "develop"
    }
  },
  "defaults": {
    "worktree_root": "~/.psm/worktrees",
    "cleanup_after_days": 14,
    "auto_cleanup_merged": true
  }
}
```

---

## 4. Architecture

### 4.1 Component Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    PSM Skill Entry Point                     │
│                   /oh-my-claudecode:psm                      │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
    ┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
    │  Command Parser │ │ State Store │ │ Project Resolver│
    │   (argparse)    │ │  (JSON DB)  │ │  (git/gh API)   │
    └─────────────────┘ └─────────────┘ └─────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
    ┌─────────────────────────────────────────────────────────┐
    │                   Session Orchestrator                   │
    └─────────────────────────────────────────────────────────┘
              │               │               │
              ▼               ▼               ▼
    ┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
    │ Worktree Manager│ │Tmux Manager │ │ Claude Launcher │
    │   (git cmd)     │ │ (tmux cmd)  │ │  (claude cmd)   │
    └─────────────────┘ └─────────────┘ └─────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
    ┌─────────────────────────────────────────────────────────┐
    │                    Integration Layer                     │
    │  (gh CLI, git, tmux, claude, omc skills, webhooks)        │
    └─────────────────────────────────────────────────────────┘
```

### 4.2 Session Lifecycle

```
┌────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  CREATING  │ ──▶ │   ACTIVE   │ ──▶ │  DETACHED  │ ──▶ │  ARCHIVED  │
└────────────┘     └────────────┘     └────────────┘     └────────────┘
      │                  │                  │                  │
      │                  │                  │                  │
      ▼                  ▼                  ▼                  ▼
  - Fetch refs      - Claude active    - Session saved    - Worktree kept
  - Create worktree - Tmux attached    - Tmux running     - PR merged
  - Create branch   - Work in progress - Can resume       - Ready for GC
  - Start tmux
  - Launch claude
```

### 4.3 Data Flow

```
User Command
     │
     ▼
┌─────────────────┐
│ Parse Arguments │
└─────────────────┘
     │
     ▼
┌─────────────────┐     ┌─────────────────┐
│ Resolve Project │◀───▶│ projects.json   │
└─────────────────┘     └─────────────────┘
     │
     ▼
┌─────────────────┐     ┌─────────────────┐
│ Fetch Context   │◀───▶│ GitHub API (gh) │
│ (PR/Issue/etc)  │     └─────────────────┘
└─────────────────┘
     │
     ▼
┌─────────────────┐     ┌─────────────────┐
│ Create Worktree │◀───▶│ Git Repository  │
└─────────────────┘     └─────────────────┘
     │
     ▼
┌─────────────────┐     ┌─────────────────┐
│ Create Session  │◀───▶│ sessions.json   │
└─────────────────┘     └─────────────────┘
     │
     ▼
┌─────────────────┐
│ Launch Tmux +   │
│ Claude Code     │
└─────────────────┘
```

---

## 5. Directory Structure

### 5.1 Global PSM Directory

```
~/.psm/
├── config.json              # Global configuration
├── projects.json            # Project aliases
├── sessions.json            # Active session registry
├── templates/               # Session templates
│   ├── pr-review.md         # PR review prompt template
│   ├── issue-fix.md         # Issue fix prompt template
│   ├── feature.md           # Feature dev template
│   └── release.md           # Release prep template
├── logs/                    # Session logs
│   └── psm.log
└── worktrees/               # Default worktree location
    ├── omc/                 # Per-project worktrees
    │   ├── pr-123/
    │   ├── issue-42/
    │   └── feature-auth/
    └── claude-code/
        └── pr-456/
```

### 5.2 Per-Session Directory

```
~/.psm/worktrees/omc/pr-123/
├── .git                     # Git worktree link
├── .psm-session.json        # Session metadata
├── .psm-context.md          # Pre-loaded Claude context
├──           # Actual code
└── .omc/                    # OMC state (if applicable)
```

### 5.3 Session Metadata File

```json
// .psm-session.json
{
  "id": "omc:pr-123",
  "type": "review",
  "project": "omc",
  "ref": "pr-123",
  "branch": "feature/add-hooks",
  "base": "main",
  "created_at": "2024-01-26T10:30:00Z",
  "last_accessed": "2024-01-26T14:45:00Z",
  "tmux_session": "psm:omc:pr-123",
  "worktree_path": "~/.psm/worktrees/omc/pr-123",
  "source_repo": "~/Workspace/oh-my-claudecode",
  "github": {
    "pr_number": 123,
    "pr_title": "Add webhook support",
    "pr_author": "contributor",
    "pr_url": "https://github.com/anthropics/oh-my-claudecode/pull/123"
  },
  "state": "active",
  "notes": []
}
```

---

## 6. Session Naming Conventions

### 6.1 Tmux Session Names

Format: `psm::<type>-`

| Type | Pattern | Example |
|------|---------|---------|
| PR Review | `psm::pr-<num>` | `psm:omc:pr-123` |
| Issue Fix | `psm::issue-<num>` | `psm:omc:issue-42` |
| Feature | `psm::feat-<name>` | `psm:omc:feat-auth` |
| Release | `psm::rel-<ver>` | `psm:omc:rel-v3.5.0` |
| Generic | `psm::<name>` | `psm:omc:experiment` |

### 6.2 Worktree Directory Names

Format: `<type>-`

| Type | Pattern | Example |
|------|---------|---------|
| PR Review | `pr-<num>` | `pr-123` |
| Issue Fix | `issue-<num>` | `issue-42` |
| Feature | `feat-<name>` | `feat-auth` |
| Release | `rel-<ver>` | `rel-v3.5.0` |

### 6.3 Branch Names

| Type | Pattern | Example |
|------|---------|---------|
| PR Review | (uses PR branch) | `feature/add-hooks` |
| Issue Fix | `fix/-<slug>` | `fix/42-auth-timeout` |
| Feature | `feature/<name>` | `feature/auth` |
| Release | `release/<ver>` | `release/v3.5.0` |
| Hotfix | `hotfix/<ver>` | `hotfix/v3.4.1` |

---

## 7. Workflow Presets

### 7.1 PR Review Preset

```yaml
name: pr-review
steps:
  - fetch_pr_info
  - create_worktree_from_pr_branch
  - generate_review_context:
      template: pr-review.md
      includes:
        - pr_description
        - changed_files_summary
        - commit_history
        - related_issues
  - spawn_tmux_session
  - launch_claude_with_context:
      initial_prompt: |
        You are reviewing PR #{{pr_number}}: {{pr_title}}

        Focus areas:
        - Code quality and patterns
        - Security implications
        - Test coverage
        - Documentation updates

        Changed files:
        {{changed_files}}
```

### 7.2 Issue Fix Preset

```yaml
name: issue-fix
steps:
  - fetch_issue_info
  - create_branch_from_base
  - create_worktree
  - generate_fix_context:
      template: issue-fix.md
      includes:
        - issue_description
        - issue_labels
        - related_code_search
        - similar_issues
  - spawn_tmux_session
  - launch_claude_with_context:
      initial_prompt: |
        You are fixing issue #{{issue_number}}: {{issue_title}}

        Issue description:
        {{issue_body}}

        Labels: {{labels}}

        Potentially related files:
        {{related_files}}
```

### 7.3 Feature Development Preset

```yaml
name: feature-dev
steps:
  - create_feature_branch
  - create_worktree
  - generate_feature_context:
      template: feature.md
      includes:
        - project_structure
        - related_components
        - coding_standards
  - spawn_tmux_session
  - launch_claude_with_context:
      initial_prompt: |
        You are developing feature: {{feature_name}}

        Project context loaded. Ready to implement.

        Suggested starting point:
        {{suggested_files}}
```

### 7.4 Release Preparation Preset

```yaml
name: release-prep
steps:
  - validate_version_format
  - create_release_branch
  - create_worktree
  - generate_release_context:
      template: release.md
      includes:
        - changelog_since_last_release
        - pending_prs
        - version_files
        - release_checklist
  - spawn_tmux_session
  - launch_claude_with_context:
      initial_prompt: |
        You are preparing release {{version}}

        Changes since last release:
        {{changelog}}

        Release checklist:
        - [ ] Update version in package.json
        - [ ] Update CHANGELOG.md
        - [ ] Run full test suite
        - [ ] Update documentation
        - [ ] Create release notes
```

---

## 8. State Management

### 8.1 Sessions Registry

```json
// ~/.psm/sessions.json
{
  "version": 1,
  "sessions": {
    "omc:pr-123": {
      "id": "omc:pr-123",
      "state": "active",
      "created_at": "2024-01-26T10:30:00Z",
      "last_accessed": "2024-01-26T14:45:00Z",
      "worktree": "~/.psm/worktrees/omc/pr-123",
      "tmux": "psm:omc:pr-123",
      "type": "review",
      "metadata": {
        "pr_number": 123,
        "pr_merged": false
      }
    },
    "omc:issue-42": {
      "id": "omc:issue-42",
      "state": "detached",
      "created_at": "2024-01-25T09:00:00Z",
      "last_accessed": "2024-01-25T18:00:00Z",
      "worktree": "~/.psm/worktrees/omc/issue-42",
      "tmux": "psm:omc:issue-42",
      "type": "fix",
      "metadata": {
        "issue_number": 42,
        "issue_closed": false
      }
    }
  },
  "stats": {
    "total_created": 45,
    "total_cleaned": 32,
    "active_count": 3
  }
}
```

### 8.2 State Transitions

```
┌───────────┐
│  CREATING │ ─── on success ───▶ ACTIVE
└───────────┘
      │
      │ on failure
      ▼
┌───────────┐
│  FAILED   │ ─── cleanup ───▶ (removed)
└───────────┘

┌───────────┐
│  ACTIVE   │ ─── detach ───▶ DETACHED
└───────────┘
      │
      │ kill
      ▼
┌───────────┐
│ ARCHIVED  │ ─── cleanup ───▶ (removed)
└───────────┘

┌───────────┐
│ DETACHED  │ ─── attach ───▶ ACTIVE
└───────────┘
      │
      │ pr_merged / issue_closed / timeout
      ▼
┌───────────┐
│ ARCHIVED  │
└───────────┘
```

### 8.3 Auto-Archive Triggers

Sessions automatically transition to ARCHIVED when:

1. **PR Merged**: GitHub webhook or polling detects merge
2. **Issue Closed**: GitHub webhook or polling detects closure
3. **Inactivity Timeout**: No access for configured days (default: 14)
4. **Manual Archive**: User marks as complete

---

## 9. Cleanup Strategies

### 9.1 Cleanup Levels

| Level | Command | What it Cleans |
|-------|---------|----------------|
| Safe | `/psm cleanup` | Merged PRs, closed issues, archived |
| Moderate | `/psm cleanup --stale` | + Inactive > 14 days |
| Aggressive | `/psm cleanup --force` | + All detached sessions |
| Nuclear | `/psm cleanup --all` | Everything (with confirmation) |

### 9.2 Cleanup Algorithm

```python
def cleanup(options):
    sessions = load_sessions()
    to_remove = []

    for session in sessions:
        should_remove = False

        # Level 1: Safe (always)
        if session.type == "review" and session.pr_merged:
            should_remove = True
        elif session.type == "fix" and session.issue_closed:
            should_remove = True
        elif session.state == "archived":
            should_remove = True

        # Level 2: Stale
        if options.stale:
            days_inactive = now() - session.last_accessed
            if days_inactive > options.older_than:
                should_remove = True

        # Level 3: Force
        if options.force:
            if session.state == "detached":
                should_remove = True

        if should_remove:
            to_remove.append(session)

    # Execute cleanup
    for session in to_remove:
        if not options.dry_run:
            kill_tmux_session(session.tmux)
            remove_worktree(session.worktree)
            remove_session_record(session.id)

        log(f"Cleaned: {session.id}")
```

### 9.3 Cleanup Safeguards

1. **Uncommitted Changes Check**: Warn if worktree has uncommitted changes
2. **Unpushed Commits Check**: Warn if local commits not pushed
3. **Active Session Check**: Never cleanup currently attached session
4. **Confirmation Prompt**: For aggressive/nuclear cleanup
5. **Dry Run**: Always preview what will be cleaned

### 9.4 Scheduled Cleanup

```json
// ~/.psm/config.json
{
  "cleanup": {
    "auto_enabled": true,
    "schedule": "daily",
    "level": "safe",
    "older_than_days": 14,
    "notify_before_cleanup": true
  }
}
```

---

## 10. Integration Points

### 10.1 OMC Skill Integration

| OMC Skill | PSM Integration |
|-----------|-----------------|
| `autopilot` | Can spawn PSM session for isolated work |
| `ultrawork` | Parallel agents across PSM sessions |
| `ralph` | Persistence tracking per PSM session |
| `git-master` | Aware of worktree context |
| `deepsearch` | Scoped to session worktree |

### 10.2 Custom Agent Gateway Integration

```typescript
// A custom webhook can manage PSM sessions through your own gateway.
interface CustomAgentGatewayIntegration {
  // List sessions via your gateway UI
  listSessions(): Promise<Session[]>;

  // Create session from your gateway
  createSession(options: SessionOptions): Promise<Session>;

  // Attach to session in a new terminal
  attachSession(sessionId: string): Promise<void>;

  // Session status in your gateway dashboard
  getSessionStatus(sessionId: string): Promise<SessionStatus>;
}
```

### 10.3 GitHub Integration

| Feature | Integration |
|---------|-------------|
| PR Creation | Auto-create draft PR from feature session |
| PR Status | Track merge status for cleanup |
| Issue Linking | Auto-link commits to issue |
| Review Comments | Load review comments as context |
| CI Status | Show CI status in session info |

### 10.4 Editor Integration

```bash
# VSCode
/psm review omc#123 --editor vscode

# Cursor
/psm review omc#123 --editor cursor

# Neovim
/psm review omc#123 --editor nvim
```

Opens editor in worktree directory alongside tmux session.

### 10.5 HUD Integration

PSM status in OMC HUD statusline:

```
[psm:omc:pr-123] 📋 Review | 🕐 2h active | 📁 ~/.psm/worktrees/omc/pr-123
```

---

## 11. Edge Cases & Error Handling

### 11.1 Common Edge Cases

| Scenario | Handling |
|----------|----------|
| Worktree already exists | Offer: attach, recreate, or abort |
| Tmux session name conflict | Append timestamp suffix |
| PR branch force-pushed | Warn and offer to refetch |
| Network offline | Cache what's possible, queue GitHub ops |
| Git dirty state in main repo | Warn but allow (worktree is isolated) |
| Worktree on different filesystem | Use git clone instead |
| Very large repository | Shallow clone option |
| Session metadata corrupted | Rebuild from git/tmux state |

### 11.2 Error Recovery

```bash
# Rebuild sessions.json from existing worktrees and tmux
/psm repair

# Fix orphaned tmux sessions (no worktree)
/psm repair --orphaned-tmux

# Fix orphaned worktrees (no session record)
/psm repair --orphaned-worktrees

# Full reconstruction
/psm repair --full
```

### 11.3 Conflict Resolution

```
User runs: /psm review omc#123

Existing session found!

Options:
  [A] Attach to existing session (recommended)
  [R] Recreate (destroys existing worktree)
  [C] Create parallel (omc:pr-123-2)
  [Q] Quit
```

---

## 12. Security Considerations

### 12.1 Credential Handling

- **GitHub Token**: Uses existing `gh` CLI auth, never stored by PSM
- **SSH Keys**: Relies on system SSH agent
- **Secrets in Worktrees**: Worktrees inherit .gitignore, secrets not duplicated

### 12.2 Path Sanitization

```python
def sanitize_session_name(name: str) -> str:
    # Prevent path traversal
    name = name.replace("..", "")
    name = name.replace("/", "-")
    name = name.replace("\\", "-")
    # Limit length
    name = name[:64]
    # Alphanumeric + dash only
    name = re.sub(r'[^a-zA-Z0-9-]', '', name)
    return name
```

### 12.3 Permissions

- Worktree directories: `0755` (user rwx, others rx)
- Session metadata: `0600` (user only)
- Config files: `0600` (user only)

---

## 13. Future Enhancements

### 13.1 Planned Features

| Feature | Priority | Description |
|---------|----------|-------------|
| Session Templates | High | Custom workflow templates |
| Team Sharing | Medium | Share session configs |
| Session Recording | Medium | Record session for replay |
| Cloud Sync | Low | Sync sessions across machines |
| Auto-PR Creation | Medium | Create PR when session completes |
| Session Metrics | Low | Time tracking per session |

### 13.2 Extension Points

```typescript
// Plugin interface for custom workflows
interface PSMPlugin {
  name: string;

  // Called before session creation
  beforeCreate?(context: SessionContext): Promise<void>;

  // Called after session creation
  afterCreate?(session: Session): Promise<void>;

  // Custom cleanup logic
  shouldCleanup?(session: Session): Promise;

  // Custom context generation
  generateContext?(session: Session): Promise<string>;
}
```

### 13.3 Potential Integrations

- **Linear**: Create sessions from Linear issues
- **Jira**: Create sessions from Jira tickets
- **Slack**: Notifications on session events
- **Discord**: Team session coordination

---

## Appendix A: Quick Reference Card

```
┌────────────────────────────────────────────────────────────┐
│            Project Session Manager (PSM)                   │
├────────────────────────────────────────────────────────────┤
│ CREATE SESSIONS                                            │
│   /psm review       Review a PR                       │
│   /psm fix       Fix an issue                      │
│   /psm feature <name>   Start feature                     │
│   /psm release <ver>    Prepare release                   │
├────────────────────────────────────────────────────────────┤
│ MANAGE SESSIONS                                            │
│   /psm list             List all sessions                 │
│   /psm attach       Attach to session                 │
│   /psm switch [id]      Switch sessions                   │
│   /psm detach           Detach current                    │
│   /psm status           Current session info              │
├────────────────────────────────────────────────────────────┤
│ CLEANUP                                                    │
│   /psm cleanup          Clean merged/closed               │
│   /psm kill         Kill specific session             │
│   /psm repair           Fix corrupted state               │
├────────────────────────────────────────────────────────────┤
│ REFERENCES                                                 │
│   omc#123               Project alias + number            │
│   org/repo#123          Full GitHub reference             │
│   https://...           GitHub URL                        │
└────────────────────────────────────────────────────────────┘
```

---

## Appendix B: Configuration Reference

```json
// ~/.psm/config.json (complete)
{
  "version": 1,
  "worktree_root": "~/.psm/worktrees",
  "defaults": {
    "editor": "cursor",
    "launch_claude": true,
    "launch_tmux": true,
    "shallow_clone_depth": 100
  },
  "cleanup": {
    "auto_enabled": true,
    "schedule": "daily",
    "level": "safe",
    "older_than_days": 14,
    "notify_before_cleanup": true,
    "keep_archived_days": 7
  },
  "tmux": {
    "session_prefix": "psm",
    "default_layout": "main-vertical",
    "status_bar": true
  },
  "claude": {
    "auto_context": true,
    "context_template": "default",
    "model": "opus"
  },
  "github": {
    "poll_interval_minutes": 5,
    "auto_fetch_pr_reviews": true
  },
  "notifications": {
    "on_pr_merged": true,
    "on_issue_closed": true,
    "on_cleanup": true
  }
}
```

---

## Appendix C: Example Session Transcript

```bash
$ /psm review omc#123

🔍 Fetching PR #123 from oh-my-claudecode...
   Title: "Add webhook support for external integrations"
   Author: @contributor
   Changed: 12 files (+450, -23)

📁 Creating worktree at ~/.psm/worktrees/omc/pr-123...
   Branch: feature/webhook-support
   Base: main

🖥️  Creating tmux session: psm:omc:pr-123...

🤖 Launching Claude Code with PR context...

✅ Session ready!

   Session ID: omc:pr-123
   Worktree:   ~/.psm/worktrees/omc/pr-123
   Tmux:       psm:omc:pr-123

   Commands:
     /psm attach omc:pr-123  - Reattach later
     /psm kill omc:pr-123    - End session
     /psm cleanup            - Clean when PR merged

Attaching to session...
```

---

*Document Version: 1.0.0*
*Last Updated: 2024-01-26*