Skip to content

Hoya324/oh-my-harness

BranchesTags

Repository files navigation

Claude Code Plugin Version Node >= 18 MIT License CI

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.

한국어 · Get Started · Features · Multi-Agent · Config · Architecture

Why Oh My Harness?

Claude Code is powerful out of the box — but it doesn't enforce testing, doesn't warn before rm -rf, and treats every request the same regardless of complexity.

Oh My Harness (OMH) adds a thin layer of smart defaults using Claude Code's native hook system. No heavy plugins, no runtime overhead — just hooks, skills, and CLAUDE.md instructions that make every session safer and more productive.

graph LR
    A[You type a prompt] --> B{OMH Hooks}
    B --> C[Ambiguity? Ask first]
    B --> D[3+ tasks? Plan mode]
    B --> E[rm -rf? Warn]
    B --> F[Code changed? Test reminder]
    B --> G[git commit? Convention check]
    style B fill:#7C3AED,color:#fff
Loading

Philosophy

Minimal guards, maximum customization.

OMH believes the best harness is one you barely notice. Instead of blocking and enforcing, OMH guides with smart defaults — warnings instead of walls, reminders instead of restrictions.

Where OMH truly shines is helping you build and use project-specific skills. Every codebase is different: your test conventions, review checklists, and lint workflows are unique. OMH auto-scaffolds per-project skills based on your detected stack, then gets out of the way so you can customize them.

  • Built-in skills (agent management, setup) stay in the plugin
  • Project skills (code-review, test-write, lint-fix) live in .claude/skills/ — your project, your rules
  • Run /init-project to scaffold, then customize freely

Quick Start

Option A: Claude Code Plugin (recommended)

# 1. Install plugin (user scope by default)
claude plugin install oh-my-harness@oh-my-harness

# 2. Restart Claude Code, then initialize your project config:
/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

When a new version is released, update to get the latest hooks, detection patterns, and features.

Plugin mode

# Pull the latest plugin version
claude plugin update oh-my-harness@oh-my-harness

# Re-initialize to apply updated hooks and dictionary
/harness-setup

npm CLI mode

# Update the global package
npm update -g oh-my-harness

# Re-run init to copy updated hooks into your project
oh-my-harness init

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

Features Overview

# Feature Hook Default What it does
1 Convention Auto-Detect SessionStart ON Scans project and injects language/test/lint context
2 Test Enforcement Stop ON Reminds to verify tests after every code change
3 Model Routing CLAUDE.md + agents ON Routes subagents to haiku / sonnet / opus by complexity
4 Auto-Plan Mode UserPromptSubmit ON Detects 3+ tasks and suggests planning first
5 Ambiguity Guard UserPromptSubmit ON Forces clarification for vague requests
6 Dangerous Guard PreToolUse ON Warns before rm -rf, git push --force, .env writes
7 Context Snapshot PreCompact ON Saves task state before context compaction
8 Commit Convention PostToolUse ON Reminds commit format (Conventional / Gitmoji)
9 Scope Guard PostToolUse OFF Warns when modifying files outside allowed paths
10 Usage Tracking PostToolUse ON Records tool usage per session
11 Auto .gitignore CLI init ON Adds .claude/.omh/ to .gitignore
12 Multi-Agent /agent-spawn — Parallel Claude agents in tmux with git worktrees
13 Native Team /team-spawn ON Native Claude Code team orchestration with templates
14 Skill Scaffolding /init-project ON Auto-generates project-specific skills based on detected stack

See Feature Details for full descriptions of each feature.

Architecture

Full details: docs/architecture.md

graph TB
    subgraph "Claude Code Session"
        direction TB
        CC[Claude Code] --> HOOKS[Hook System]
        CC --> SKILLS[Skill System]
        CC --> AGENTS[Agent System]
    end

    subgraph "Oh My Harness"
        direction TB
        HOOKS --> H1[session-start.mjs]
        HOOKS --> H2[pre-prompt.mjs]
        HOOKS --> H3[dangerous-guard.mjs]
        HOOKS --> H4[commit-convention.mjs]
        HOOKS --> H5[scope-guard.mjs]
        HOOKS --> H6[usage-tracker.mjs]
        HOOKS --> H7[pre-compact.mjs]
        HOOKS --> H8[post-task.mjs]

        SKILLS --> S1["/harness-setup"]
        SKILLS --> S2["/set-harness"]
        SKILLS --> S3["/agent-spawn"]
        SKILLS --> S4["/agent-status"]
        SKILLS --> S5["/team-spawn"]
        SKILLS --> S6["/team-status"]

        AGENTS --> A1["harness:quick (haiku)"]
        AGENTS --> A2["harness:standard (sonnet)"]
        AGENTS --> A3["harness:architect (opus)"]
    end

    subgraph "Project Data (.claude/.omh/)"
        CONFIG[harness.config.json]
        CONV[conventions.json]
        USAGE[usage.json]
        SNAP[context-snapshot.md]
    end

    H1 --> CONV
    H6 --> USAGE
    H7 --> SNAP
    H1 --> CONFIG
    H2 --> CONFIG
    H3 --> CONFIG

    style CC fill:#7C3AED,color:#fff
    style CONFIG fill:#f59e0b,color:#000
Loading

Hook Pipeline

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant OMH as OMH Hooks

    Note over CC,OMH: Session Start
    CC->>OMH: SessionStart
    OMH-->>CC: Project: node | test: vitest | lint: eslint

    Note over U,CC: User sends prompt
    U->>CC: "refactor auth and add tests"
    CC->>OMH: UserPromptSubmit
    OMH-->>CC: 2 tasks detected, suggest plan mode
    OMH-->>CC: Request is ambiguous, ask for clarification

    Note over CC,OMH: Tool execution
    CC->>OMH: PreToolUse (Bash: rm -rf dist/)
    OMH-->>CC: WARNING: rm -rf detected. Confirm with user.

    CC->>OMH: PostToolUse (Bash: git commit)
    OMH-->>CC: Convention: feat(scope): description

    Note over CC,OMH: Task complete
    CC->>OMH: Stop
    OMH-->>CC: Code changes detected. Verify tests exist.
Loading

Multi-Agent

Full details: docs/multi-agent.md

graph TD
    START["/agent-spawn 3 'fix TypeScript errors'"] --> CONFIG[Read multiAgent config]
    CONFIG --> CONFIRM{"User confirms?"}
    CONFIRM -->|Cancel| ABORT[Abort]
    CONFIRM -->|Yes| CHECK[Check prerequisites: tmux, claude, git]
    CHECK --> WT{"useWorktree?"}

    WT -->|true| CREATE_WT["Create worktrees<br/>.claude/.omh/worktrees/agent-1,2,3"]
    WT -->|false| SHARED[Agents share project root]

    CREATE_WT --> TMUX[Create tmux session: omh-agents]
    SHARED --> TMUX

    TMUX --> LAUNCH["Launch claude in each pane<br/>(--dangerously-skip-permissions)"]
    LAUNCH --> STATE[Save state to agents.json]
    STATE --> DONE[Agents running in parallel]

    DONE --> STATUS["/agent-status"]
    DONE --> APPLY["/agent-apply all"]
    DONE --> STOP["/agent-stop all"]

    style START fill:#7C3AED,color:#fff
    style CONFIRM fill:#f59e0b,color:#000
Loading 
gitGraph
    commit id: "main"
    commit id: "your work"
    branch omh/agent-1
    branch omh/agent-2
    branch omh/agent-3
    checkout omh/agent-1
    commit id: "agent-1: fix A"
    commit id: "agent-1: fix B"
    checkout omh/agent-2
    commit id: "agent-2: fix C"
    checkout omh/agent-3
    commit id: "agent-3: fix D"
    commit id: "agent-3: fix E"
    checkout main
    merge omh/agent-1 id: "/agent-apply 1"
    merge omh/agent-2 id: "/agent-apply 2"
    merge omh/agent-3 id: "/agent-apply 3"
Loading

Native Team

Full details: docs/multi-agent.md

No tmux, no worktrees — use Claude Code's built-in team orchestration.

graph TD
    START["/team-spawn fullstack 'build auth system'"] --> CONFIG[Read nativeTeam config]
    CONFIG --> CONFIRM{"User confirms?"}
    CONFIRM -->|Cancel| ABORT[Abort]
    CONFIRM -->|Yes| CREATE[TeamCreate + TaskCreate]
    CREATE --> SPAWN["Spawn teammates via Agent tool"]
    SPAWN --> ASSIGN[Assign tasks to teammates]
    ASSIGN --> RUNNING[Team running — messages arrive automatically]

    RUNNING --> STATUS["/team-status"]
    RUNNING --> STOP["/team-stop"]

    style START fill:#7C3AED,color:#fff
    style CONFIRM fill:#f59e0b,color:#000
Loading
Template Members Best For
fullstack frontend + backend + tester (all sonnet) Full-stack features
review reviewer (opus) + tester (sonnet) Code review
research researcher (haiku) + implementer (sonnet) + architect (opus) Research-driven work

Documentation

Document Contents
Features HUD status line, smart defaults, feature tags, detailed feature descriptions (1–10)
Architecture System diagram, hook pipeline, plugin mode vs npm CLI directory structure
Multi-Agent Spawn commands, workflow, worktree branching model, safety policies
Configuration Settings reference, CLI commands, slash commands, OMC compatibility, uninstall

License

MIT

About

custom claude harness

hoya324.github.io/oh-my-harness

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 Latest
Mar 24, 2026

Packages

 
 
 

Contributors

Languages