Oh My Harness

Lightweight Claude Code harness. Zero config, instant boost. Smart defaults, test enforcement, model routing, and multi-agent orchestration — all through native hooks.

Installation

Option A: Claude Code Plugin (recommended)

# 1. Install plugin
claude plugin install oh-my-harness@oh-my-harness

# 2. Restart Claude Code, then initialize:
/harness-setup

Option B: npm CLI

npm install -g oh-my-harness
cd your-project
oh-my-harness init

Either way, start Claude Code as usual — harness features activate automatically.

Updating

# Plugin mode
claude plugin update oh-my-harness@oh-my-harness
/harness-setup

# npm mode
npm update -g oh-my-harness
oh-my-harness init

init preserves your existing harness.config.json. Only hooks, commands, and CLAUDE.md instructions are refreshed.

Quick Start

After installation, OMH works immediately. Here's what happens in your first session:

1. Convention detected — OMH scans your project and outputs: [omh:convention-detect] Project: node | test: vitest | lint: eslint
2. Guards active — Ambiguity detection, dangerous command warnings, and test enforcement are all ON by default.
3. Model routing ready — Claude automatically delegates to haiku/sonnet/opus based on task complexity.

Run /init-project to scaffold project-specific skills (code review, test writing, lint fixing) for your detected stack.

Configuration

All settings live in .claude/.omh/harness.config.json.

Default Config

{
  "version": 1,
  "features": {
    "conventionSetup": true,
    "testEnforcement": true,
    "contextOptimization": true,
    "autoPlanMode": true,
    "ambiguityDetection": true,
    "dangerousGuard": true,
    "contextSnapshot": true,
    "commitConvention": true,
    "scopeGuard": false,
    "usageTracking": true,
    "autoGitignore": true,
    "skillScaffolding": true
  },
  "testEnforcement": { "minCases": 2, "promptOnMissing": true },
  "modelRouting": { "quick": "haiku", "standard": "sonnet", "complex": "opus" },
  "autoPlan": { "threshold": 3 },
  "ambiguityDetection": { "threshold": 2, "language": "auto" },
  "commitConvention": { "style": "auto" },
  "scopeGuard": { "allowedPaths": [] },
  "multiAgent": { "maxAgents": 4, "useWorktree": true, "tmuxSession": "omh-agents" },
  "conventions": { "autoDetect": true, "overrides": {} }
}

Modify Settings

/set-harness                                # Show all current settings
/set-harness features.scopeGuard true       # Enable scope guard
/set-harness testEnforcement.minCases 3     # Require 3+ test cases
/set-harness modelRouting.standard opus     # Use opus for implementation
/set-harness commitConvention.style gitmoji # Switch to gitmoji

Hooks

OMH hooks into Claude Code's lifecycle at every stage. All hooks run automatically — no manual intervention needed.

Feature Tags — [omh:*]

Every OMH action is prefixed with a tag so you always know which feature fired:

[omh:convention-detect]       → Detected project conventions
[omh:ambiguity-guard]        → Asking for clarification
[omh:auto-plan]              → Detected 3+ tasks
[omh:dangerous-guard]        → Warning before destructive command
[omh:model-routing → sonnet] → Delegating to sonnet
[omh:test-enforcement]       → Reminding to verify tests
[omh:commit-convention]      → Showing commit format
[omh:scope-guard]            → Warning about edit outside paths
[omh:context-snapshot]       → Saving state before compaction

Skills

OMH provides 10 built-in slash commands:

Agents

OMH provides 3 built-in agent types for cost-efficient subagent delegation:

Model Routing

Claude automatically routes subagent work to the appropriate model tier based on task complexity. This is configured in CLAUDE.md and agent definitions.

Announce with: [omh:model-routing → <model>]

# Customize model assignments
/set-harness modelRouting.quick haiku
/set-harness modelRouting.standard sonnet
/set-harness modelRouting.complex opus

Features Overview

Safety Guards

Ambiguity Guard

Detects vague requests using a scoring system (threshold: 2):

Dangerous Guard

Warns before potentially destructive operations:

Warning only — does not block execution. Asks Claude to confirm with user.

Scope Guard

When enabled, warns if Edit/Write targets files outside allowed directories.

{
  "features": { "scopeGuard": true },
  "scopeGuard": { "allowedPaths": ["src/auth", "src/utils"] }
}

OFF by default. Enable when you want to restrict Claude's write scope.

Convention Auto-Detect

Scans project root on session start and injects detected conventions as context. Results are cached for 1 hour.

Test Enforcement

After code changes (Edit / Write / NotebookEdit), injects a reminder at session stop:

• Verify test files exist for changed code
• Each test file has at least N cases (configurable, default: 2)
• Tests must cover happy path, edge case, and error case at minimum

HUD Status Line

OMH replaces Claude Code's default status line with a real-time dashboard:

[OMH] | 5h:14%(3h51m) | wk:7%(6d5h) | session:29m | ctx:39% | 🔧53 | agents:2 | opus-4-6

Skill Scaffolding

Run /init-project to auto-generate project-specific skills based on your detected stack.

Generated Skills

Supported Languages

Skills are user-owned. Customize freely — OMH never overwrites existing skills.

Multi-Agent System

Spawn parallel Claude Code instances in tmux panes, each with an isolated git worktree.

Agent Commands

Worktree Mode

Safety Policies

• Always ask first — never spawn without explicit user confirmation
• Never auto-merge — /agent-apply always shows a diff and waits for approval
• Never silently discard — /agent-stop with unmerged commits requires explicit choice
• Max agents — capped by multiAgent.maxAgents (default: 4)

Prerequisites

• tmux — brew install tmux (macOS) / apt install tmux (Linux)
• git — for worktree isolation
• claude CLI — must be available in PATH

Native Team System

Use Claude Code's built-in team orchestration — no tmux or worktree dependencies required.

Team Commands

Templates

Multi-Agent vs Native Team

Team Safety Policies

• Always ask first — never create a team without explicit user confirmation
• Never silently discard — /team-stop with incomplete tasks requires explicit choice
• Max teammates — capped by nativeTeam.maxTeammates (default: 4)
• One team at a time — must stop existing team before creating a new one

Settings Reference

CLI Commands

oh-my-harness init      # Set up harness in current project
oh-my-harness update    # Regenerate settings from config
oh-my-harness status    # Show current configuration
oh-my-harness reset     # Remove all harness files (clean uninstall)

OMC Compatibility

Oh My Harness coexists cleanly with Oh My ClaudeCode:

Both plugins can be installed simultaneously without conflicts.

Disable / Uninstall

# Temporarily disable
DISABLE_HARNESS=1 claude

# Plugin mode — uninstall
claude plugin uninstall oh-my-harness

# npm mode — full removal
oh-my-harness reset
npm uninstall -g oh-my-harness

Requirements

• Node.js >= 18
• Claude Code CLI
• tmux — for multi-agent only
• git — for worktree isolation