File: README.md Copy Chapter

English | 한국어 | 中文 | 日本語 | Español | Tiếng Việt | Português

oh-my-claudecode

For Codex users: Check out 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 • Documentation • CLI Reference • Workflows • Migration Guide • Discord

Core Maintainers Copy Chapter

Ambassadors Copy Chapter

Document Specialists Copy Chapter

Top Collaborators Copy Chapter

Quick Start Copy Chapter

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):

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

Then:

/plugin install oh-my-claudecode

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

npm i oh-my-claude-sisyphus@latest

Known npm warning: npm may print deprecated [email protected] during the CLI install.
This currently comes from the upstream better-sqlite3 native-addon dependency
(better-sqlite3 -> prebuild-install); [email protected] 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
and does not by itself mean the OMC CLI install failed.

Step 2: Setup

# 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 for a complete decision matrix and all available flags.

Step 3: Build something

# 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>:

/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:

{
  "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 and Reference.

That's it. Everything else is automatic.

CLI Commands vs In-Session Skills Copy Section

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.

VS Code, Agent SDK, and automation scope Copy Section

• 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? Copy Section

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) Copy Chapter

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

/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:

{
  "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+) Copy Section

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:

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):

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

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:

{
  "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 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. 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 Copy Section

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

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:

# 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:

/omc-doctor

Your Claude Just Have been Steroided.

Why oh-my-claudecode? Copy Chapter

• 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 Copy Chapter

Orchestration Modes Copy Section

Multiple strategies for different use cases — from Team-backed orchestration to token-efficient refactoring. Learn more →

Goal Workflow Guidance Copy Section

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 and Anthropic Claude Code changelog. 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 Copy Section

• 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 - Which model to pair with each agent, with premium/balanced/budget presets

Developer Experience Copy Section

• 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 for details.
• Skill learning - Extract reusable patterns from your sessions
• Analytics & cost tracking - Understand token usage across all sessions

Contributing Copy Section

Want to contribute to OMC? See 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 Copy Section

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

# .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 Copy Section

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.

Full feature list →

Multi-repo workspaces Copy Section

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:

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 for resolution order, OMC_STATE_DIR, and workspace identifier options.

In-session shortcuts Copy Chapter

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.

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 Copy Chapter

Provider Advisor (`omc ask` / `/ask`) Copy Section

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

# 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) Copy Section

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

/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 Copy Section

Auto-resume Claude Code sessions when rate limits reset.

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 Copy Section

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) Copy Section

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

# 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 Copy Section

Forward Claude Code session events to an OpenClaw gateway to enable automated responses and workflows via your OpenClaw agent.

Quick setup (recommended):

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

Manual setup: create ~/.claude/omc_config.openclaw.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:

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

Reply channel environment variables:

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

Documentation Copy Chapter

• Full Reference - Complete feature documentation
• CLI Reference - All omc commands, flags, and tools
• Notifications Guide - Discord, Telegram, Slack, and webhook setup
• Recommended Workflows - Battle-tested skill chains for common tasks
• Release Notes - What's new in each version
• Website - Interactive guides and examples
• Migration Guide - Upgrade from v2.x
• Architecture - How it works under the hood
• Performance Monitoring - Agent tracking, debugging, and optimization
• Model × Agent Compatibility Matrix - Which model to pair with each agent (premium / balanced / budget presets)
• Security Guide - Enterprise deployment and hardening

Requirements Copy Chapter

• Claude Code CLI
• Claude Max/Pro subscription OR Anthropic API key

Platform & tmux Copy Section

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

Windows users: psmux provides a native tmux binary for Windows with 76 tmux-compatible commands. No WSL required.

Optional: Multi-AI Orchestration Copy Section

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

Migrating from Gemini CLI: Per Google's announcement, the Gemini CLI is being superseded by the Antigravity CLI (agy); see the official Antigravity docs. 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 Copy Chapter

MIT

Featured by OmC Contributors Copy Chapter

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

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

Star History Copy Chapter

💖 Support This Project Copy Chapter

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

Why sponsor? Copy Section

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

Other ways to help Copy Section

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

GEO visibility benchmark Copy Chapter

OmC includes a geobench product spec for measuring LLM hit rate, MRR, share of voice, and citations.

• Spec: geobench/oh-my-claudecode.yaml
• Runbook: docs/geobench.md

File: benchmark/results/README.md Copy Chapter

SWE-bench Verified Results

Summary Copy Chapter

Delta: - percentage points improvement

Methodology Copy Chapter

Dataset Copy Section

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

Evaluation Setup Copy Section

• 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 Copy Section

Standard Claude Code with default settings:

• No OMC extensions loaded
• Default system prompt
• Single-agent execution

OMC Configuration Copy Section

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 Copy Section

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 Copy Chapter

By Repository Copy Section

By Difficulty Copy Section

Failure Analysis Copy Section

Top failure categories for each mode:

Vanilla:

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

OMC:

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

Improvements Copy Chapter

Instances that OMC solved but vanilla failed:

Regressions Copy Chapter

Instances that vanilla solved but OMC failed:

Reproduction Copy Chapter

Prerequisites Copy Section

# Install SWE-bench
pip install swebench

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

Running Vanilla Baseline Copy Section

# 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 Copy Section

# 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 Copy Section

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

Analyzing Failures Copy Section

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

Files Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

• SWE-bench Paper
• SWE-bench Repository
• Oh-My-ClaudeCode Documentation

Last updated: [DATE]

File: benchmark/README.md Copy Chapter

SWE-bench Benchmark Suite

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

Quick Start Copy Chapter

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

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

# 3. Full comparison
./run_full_comparison.sh

Scripts Copy Chapter

setup.sh Copy Section

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:

./setup.sh

quick_test.sh Copy Section

Quick sanity test with limited instances (default: 5):

• Tests both vanilla and OMC modes
• Fast verification before full runs
• Recommended before production benchmarks

Usage:

./quick_test.sh [--limit N] [--model MODEL] [--timeout SECS]

Examples:

./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 Copy Section

Run vanilla Claude Code benchmark:

• Standard Claude Code without OMC
• Saves predictions to predictions/vanilla/
• Logs to logs/vanilla_*.log

Usage:

./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:

./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 Copy Section

Run OMC-enhanced benchmark:

• Claude Code with oh-my-claudecode orchestration
• Saves predictions to predictions/omc/
• Logs to logs/omc_*.log

Usage:

./run_omc.sh [OPTIONS]

Options: Same as run_vanilla.sh

Examples:

./run_omc.sh                    # Full benchmark
./run_omc.sh --limit 100        # First 100 instances

run_full_comparison.sh Copy Section

Complete benchmark suite:

• Runs vanilla benchmark
• Runs OMC benchmark
• Evaluates both runs
• Generates comparison report

Usage:

./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:

./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 Copy Chapter

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 Copy Chapter

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

export ANTHROPIC_API_KEY=your_key_here

Workflow Copy Chapter

1. Setup (one-time):

   bash Copy

   ./setup.sh

2. Quick Test (recommended):

   bash Copy

   ./quick_test.sh

3. Full Benchmark:

   bash Copy

   # 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 Copy Chapter

Setup Issues Copy Section

./setup.sh
# Check output for specific errors

API Key Issues Copy Section

# Verify API key is set
echo $ANTHROPIC_API_KEY

# Export if missing
export ANTHROPIC_API_KEY=your_key_here

Docker Issues Copy Section

# Check Docker is running
docker ps

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

Python Dependencies Copy Section

# Reinstall dependencies
pip install -r requirements.txt

Advanced Usage Copy Chapter

Custom Model Copy Section

./run_vanilla.sh --model claude-opus-4-6-20260205
./run_omc.sh --model claude-opus-4-6-20260205

Longer Timeout Copy Section

# 15 minutes per instance
./run_full_comparison.sh --timeout 900

Subset Testing Copy Section

# Test instances 50-150
./run_full_comparison.sh --skip 50 --limit 100

Resume Failed Run Copy Section

# If vanilla failed at instance 42, skip to 42 and continue
./run_vanilla.sh --skip 42

Performance Tips Copy Chapter

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 Copy Chapter

Metrics Copy Section

• 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 Copy Section

The results/comparison_report.md includes:

• Side-by-side metrics
• Statistical significance tests
• Instance-level comparisons
• Qualitative analysis

License Copy Chapter

Same as parent project (MIT)

File: docs/agent-templates/base-agent.md Copy Chapter

{{AGENT_NAME}}

Role Copy Chapter

{{ROLE_DESCRIPTION}}

Tier-Specific Instructions Copy Chapter

{{TIER_INSTRUCTIONS}}

Worker Preamble Protocol Copy Chapter

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 Copy Chapter

Verification Before Completion Copy Section

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 Copy Section

• 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 Copy Section

• Always read a file before editing it
• Preserve exact indentation when editing
• Verify edits with fresh reads after changes

Communication Copy Section

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

Error Handling Copy Section

• Never ignore errors or warnings
• Investigate root causes before fixing
• Document workarounds if needed
• Ask for help when stuck

Task Execution Copy Chapter

{{TASK_SPECIFIC_INSTRUCTIONS}}

Deliverables Copy Chapter

{{EXPECTED_DELIVERABLES}}

File: docs/agent-templates/README.md Copy Chapter

Agent Prompt Templates

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

Files Copy Chapter

• 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 Copy Chapter

Injection Points Copy Section

The template uses the following placeholders:

Usage Copy Section

1. Copy the base template:

   bash Copy

   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 Copy Section

# 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 Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

Future Enhancements Copy Chapter

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 Copy Chapter

Tier-Specific Instructions

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

LOW Tier (Haiku) Copy Chapter

Model: claude-haiku-4-5
Focus: Speed and efficiency for simple, well-defined tasks

**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) Copy Chapter

Model: claude-sonnet-4-5
Focus: Balance between thoroughness and efficiency

**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) Copy Chapter

Model: claude-opus-4-8
Focus: Correctness and quality for complex tasks

**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 Copy Chapter

Template Usage Copy Chapter

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

Example for executor-low:

# 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 Copy Chapter

Consolidation Phase 3+ Roadmap

Context Copy Chapter

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 Copy Chapter

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 Copy Chapter

1) Agent Catalog Consolidation Copy Section

• 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 Copy Section

• 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 Copy Section

• 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 Copy Chapter

• 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 Copy Chapter

Milestone A — Discovery + Metrics Copy Section

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

Milestone B — Runtime Routing Cleanup Copy Section

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

Milestone C — Docs + Migration Policy Copy Section

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

Milestone D — Validation Gate Copy Section

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

Risks Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

1. Problem Statement
2. Use Cases
3. Command Interface
4. Architecture
5. Directory Structure
6. Session Naming Conventions
7. Workflow Presets
8. State Management
9. Cleanup Strategies
10. Integration Points
11. Edge Cases & Error Handling
12. Security Considerations
13. Future Enhancements

1. Problem Statement Copy Chapter

Current Pain Points Copy Section

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 Copy Section

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 Copy Chapter

2.1 PR Review Copy Section

# 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 Copy Section

# 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 Copy Section

# 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 Copy Section

# 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 Copy Section

# 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 Copy Section

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

# Switch with session picker (fzf)
/psm switch

3. Command Interface Copy Chapter

3.1 Primary Commands Copy Section

3.2 Global Flags Copy Section

3.3 Project References Copy Section

PSM supports multiple reference formats:

# 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 Copy Section

// ~/.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 Copy Chapter

4.1 Component Overview Copy Section

┌─────────────────────────────────────────────────────────────┐
│                    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 Copy Section

┌────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  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 Copy Section

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 Copy Chapter

5.1 Global PSM Directory Copy Section

~/.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 Copy Section

~/.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 Copy Section

// .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 Copy Chapter

6.1 Tmux Session Names Copy Section

Format: psm::<type>-

6.2 Worktree Directory Names Copy Section

Format: <type>-

6.3 Branch Names Copy Section

7. Workflow Presets Copy Chapter

7.1 PR Review Preset Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Chapter

8.1 Sessions Registry Copy Section

// ~/.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 Copy Section

┌───────────┐
│  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 Copy Section

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 Copy Chapter

9.1 Cleanup Levels Copy Section

9.2 Cleanup Algorithm Copy Section

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 Copy Section

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 Copy Section

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

10. Integration Points Copy Chapter

10.1 OMC Skill Integration Copy Section

10.2 Custom Agent Gateway Integration Copy Section

// 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 Copy Section

10.4 Editor Integration Copy Section

# 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 Copy Section

PSM status in OMC HUD statusline:

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

11. Edge Cases & Error Handling Copy Chapter

11.1 Common Edge Cases Copy Section

11.2 Error Recovery Copy Section

# 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 Copy Section

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 Copy Chapter

12.1 Credential Handling Copy Section

• 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 Copy Section

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 Copy Section

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

13. Future Enhancements Copy Chapter

13.1 Planned Features Copy Section

13.2 Extension Points Copy Section

// 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 Copy Section

• 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 Copy Chapter

┌────────────────────────────────────────────────────────────┐
│            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 Copy Chapter

// ~/.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 Copy Chapter

$ /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