oh-my-harness

😤 The Problem

Every AI code agent needs configuration files. Claude Code needs CLAUDE.md + hooks. Cursor needs .cursorrules. Codex needs AGENTS.md. You end up:

• 📋 Copy-pasting config files between projects
• 🔓 Forgetting to set up TDD enforcement hooks
• 💥 Agents committing code without running tests
• 🎲 Inconsistent behavior across projects

✨ The Solution

oh-my-harness init "React + FastAPI fullstack, TDD enforced, lint on save"

That's it. oh-my-harness generates enforced guardrails — not just instructions, but hooks that actually block bad behavior:

• ❌ Commit without tests passing? Blocked.
• ❌ Edit source without updating tests first? Blocked. (TDD Guard)
• ❌ Write to node_modules/ or .next/? Blocked.
• ❌ Run rm -rf /? Blocked.
• ❌ Commit on a merged branch? Blocked.
• ✅ Auto-lint on every file save? Done.
• ✅ Auto-create PR after push? Done.
• 📊 Track all hook events for analytics? Done.

🚀 Quick Start

# Zero-install: run directly with npx
npx oh-my-harness init "TypeScript Next.js frontend with Python FastAPI backend"

# Or install globally
npm install -g oh-my-harness
oh-my-harness init "React app with TDD"

# Short alias works too
omh init "Android Kotlin app with Hilt, JUnit, Gradle"
omh catalog list
omh test          # Dry-run verify your harness
omh stats         # TUI analytics dashboard
omh diff          # Preview what `omh sync` would change
omh sync --check  # Fail (exit 1) if generated files are out of date — CI gate

🔄 Keeping generated files in sync

harness.yaml is the source of truth, so the committed CLAUDE.md, hooks, and runtime configs can drift if someone edits harness.yaml without re-running omh sync. Three commands keep them honest:

# .github/workflows/ci.yml
- run: npx oh-my-harness sync --check   # fails the build if the harness is out of date

The hook manifest records the oh-my-harness version that generated it, so an upgrade that changes output is surfaced as a "re-run omh sync" hint.

📁 What Gets Generated

~/.omh/
└── config.json                        # AI provider config (global, not per-project)

your-project/
├── CLAUDE.md                          # Claude Code instructions (TDD rules, standards)
├── AGENTS.md                          # Codex CLI instructions (same managed sections)
├── harness.yaml                       # Your harness config (source of truth)
├── .omh/                              # Single source of truth — hooks + state
│   ├── hooks/
│   │   ├── catalog-branch-guard.sh    # Blocks commits on merged branches
│   │   ├── catalog-tdd-guard.sh       # Enforces test-first workflow
│   │   ├── catalog-commit-test-gate.sh # Tests must pass before commit
│   │   ├── catalog-path-guard.sh      # Protects build outputs
│   │   ├── catalog-command-guard.sh   # Blocks dangerous commands
│   │   ├── catalog-lint-on-save.sh    # Auto-lint on save
│   │   └── catalog-auto-pr.sh         # Auto-create PR after push
│   ├── state/                         # gitignored — log/runtime data
│   │   ├── events.jsonl               # Unified hook event log (powers omh stats)
│   │   └── tdd-edits.json             # TDD guard working state
│   └── manifest.json                  # Generated-files manifest
├── .claude/
│   ├── settings.json                  # Claude permissions + hooks → .omh/hooks/*.sh
│   └── oh-my-harness.json             # Harness init/sync state
└── .codex/
    ├── config.toml                    # [features] hooks = true, goals = true
    └── hooks.json                     # Codex hooks → .omh/hooks/*.sh (same scripts)

⚙️ How It Works

  ~/.omh/config.json   ┌─────────────────────┐
  ┌────────────────┐   │                     │
  │ • Claude CLI   │──▶│   NL Processing     │◀── "React + FastAPI
  │ • Claude API   │   │   (describe your    │     TDD enforced"
  │ • OpenAI API   │   │                     │
  │ • Gemini API   │   │                     │
  │ • Codex OAuth  │   │                     │
  │ • Codex OAuth  │   │                     │
  │   API          │   └────────┬────────────┘
  └────────────────┘            │
   (global AI config)   ┌────────▼────────────┐
                        │  Project Detector   │  ← Auto-detects language,
                        │  (14 languages)     │    framework, package manager
                        └────────┬────────────┘
                                 │
                        ┌────────▼────────────┐
                        │   harness.yaml      │  ← Source of truth
                        │   (editable, git    │    (hooks + rules)
                        │    trackable)       │
                        └────────┬────────────┘
                                 │
                  ┌──────────────┼──────────────┐
                  ▼              ▼              ▼
            ┌──────────┐  ┌──────────┐  ┌──────────┐
            │CLAUDE.md │  │  Hooks   │  │settings. │
            │ (rules)  │  │(enforce) │  │  json    │
            │          │  │          │  │(perms)   │
            └──────────┘  └──────────┘  └──────────┘

🔍 Project Detector

oh-my-harness automatically detects your project type and injects accurate facts into the LLM prompt:

🤖 AI Provider Setup

oh-my-harness supports multiple AI providers for natural language mode:

Configuration is saved to ~/.omh/config.json and selected via interactive UI on first use:

omh init  # will prompt for AI provider selection and model choice

🧱 Building Block Catalog

All enforcement is powered by catalog blocks — reusable, parameterized hook templates:

Usage in harness.yaml

hooks:
  - block: branch-guard
  - block: tdd-guard
    mode: ask          # ask for approval instead of hard-blocking (Claude)
  - block: commit-test-gate
    params:
      testCommand: "npx vitest run"
  - block: path-guard
    params:
      blockedPaths:
        - "node_modules/"
        - "dist/"
  - block: command-guard
    params:
      patterns:
        - "rm -rf /"
        - "sudo rm"
  - block: lint-on-save
    params:
      filePattern: "*.ts"
      command: "npx eslint --fix"
  - block: auto-pr
    params:
      baseBranch: main

mode: block vs. ask

Any blocking hook accepts an optional mode (default block):

• block — hard-blocks the tool call. The agent cannot proceed.
• ask — escalates to the user for approval instead of blocking outright.
  • Claude Code: shows a native permission prompt (permissionDecision: "ask").
  • Codex: ask is not supported, so the hook falls back to a hard block — your guardrail is never silently downgraded to "allow". The same generated script detects the calling runtime and responds accordingly.

mode: ask only applies to blocks that can block (canBlock: true); setting it on a non-blocking block (e.g. lint-on-save) is reported and ignored.

🖥️ Commands

# 🚀 Initialize
omh init "your project description"      # NL-powered (requires AI provider)
omh init                                  # Interactive TUI (import existing harness.yaml)

# 📋 Catalog
omh catalog list                          # Browse all building blocks
omh catalog info branch-guard             # Block details + params

# 🔧 Hook management
omh hook add branch-guard                 # Add a hook
omh hook remove auto-pr                   # Remove a hook

# 🔄 Sync & manage
omh sync                                 # Regenerate all files from harness.yaml
omh uninstall --dry-run                  # Preview generated-file cleanup
omh uninstall -y                         # Remove generated files, keep user content
omh uninstall -y --purge                 # Also remove harness.yaml

# 🩺 Verify & monitor
omh doctor                               # Health check
omh test                                  # Dry-run verify all hooks
omh stats                                 # TUI analytics dashboard

🧹 omh uninstall — Safe generated-file cleanup

omh uninstall removes oh-my-harness generated artifacts while preserving user content in merged files.

omh uninstall --dry-run
omh uninstall -y
omh uninstall -y --purge

Safety behavior:

• Prints the same uninstall plan for dry-run and real execution.
• Recommends backing up before execution; use --skip-backup-warning only for automation that already handles backups.
• Keeps harness.yaml by default; --purge removes it.
• Preserves user content in CLAUDE.md, AGENTS.md, .claude/settings.json, .codex/hooks.json, .codex/config.toml, and user Pi extensions.
• Removes only OMH-owned hook commands that point at this project's .omh/hooks directory.
• Warns when .codex/config.toml feature flags (hooks/goals) are removed, because manually-owned feature settings cannot be distinguished from OMH generated settings.
• Warns that .codex/config.toml comments may be lost when TOML is rewritten.
• Uses backups for modified files and restores them on stop-on-error failures; --continue-on-error records failures and keeps applying independent operations.

🩺 omh doctor

oh-my-harness: running health checks...
  ✓ .claude/oh-my-harness.json found
  ✓ CLAUDE.md exists with intact markers
  ✓ .claude/settings.json is valid
  ✓ All hook scripts are executable
oh-my-harness: all checks passed

🧪 omh test — Dry-Run Verification

Simulates hook inputs to verify block/allow behavior without entering Claude Code:

┌  omh test  Harness dry-run verification
│
◇  Branch guard
│    ✓ git commit on feat/my-feature → ALLOWED
│
◇  TDD Guard
│    ✓ src/foo.ts without test → BLOCKED
│    ✓ tests/unit/foo.test.ts → ALLOWED
│    ✓ README.md → ALLOWED
│
◇  File guards
│    ✓ node_modules/test-file.js → BLOCKED
│    ✓ dist/test-file.js → BLOCKED
│    ✓ src/index.ts → ALLOWED
│
◇  Command guards
│    ✓ "rm -rf /" → BLOCKED
│    ✓ "npm test" → ALLOWED
│
└  14/14 checks passed ✓

📊 omh stats — TUI Analytics Dashboard

Interactive dashboard powered by ink with 3 views:

 [1] Overview   [2] Timeline   [3] Blocks          d:filter r:reload q:quit

 Active: 8  Events: 1213  Block rate: 2%

 branch-guard          ████████████████████ 0b/202a
 tdd-guard             █████████████████████ 14b/68a
 commit-test-gate      ████████████████████ 0b/199a
 path-guard            ████████████████████ 4b/76a
 command-guard         ████████████████████ 4b/202a

 Dormant (0 hits):
   ░ lockfile-guard
   ░ secret-file-guard

• Overview — Active blocks with hit bar charts + dormant block detection
• Timeline — 24-hour heatmap + block rate + peak hour
• Blocks — Scrollable detail view with params, hits, last block reason

Keyboard: 1/2/3 views, ↑/↓ scroll, d date filter, r reload, q quit

📊 Stateful Hook Logging

Every hook invocation is recorded in .omh/state/events.jsonl:

{"ts":"2026-03-18T08:00:00Z","event":"PreToolUse","hook":"catalog-tdd-guard.sh","decision":"block","reason":"TDD — foo.test.* 테스트 파일을 먼저 수정하세요"}
{"ts":"2026-03-18T08:00:05Z","event":"PreToolUse","hook":"catalog-command-guard.sh","decision":"allow","reason":""}

This powers omh test live verification and omh stats analytics.

🏗️ Architecture

oh-my-harness/
├── bin/                    # CLI entry point
├── src/
│   ├── catalog/
│   │   ├── blocks/         # 17 building block definitions
│   │   ├── types.ts        # BuildingBlock, HookEntry schemas
│   │   ├── registry.ts     # Block discovery & search
│   │   ├── template-engine.ts # Handlebars rendering + applyDefaults
│   │   └── converter.ts    # HookEntry[] → rendered scripts
│   ├── cli/
│   │   ├── commands/       # init, doctor, catalog, hook, sync, test
│   │   ├── stats/          # TUI dashboard (ink/React)
│   │   │   ├── App.tsx     # App shell (tab bar, keyboard nav)
│   │   │   ├── data.ts     # Data aggregation layer
│   │   │   └── components/ # Overview, Timeline, Blocks views
│   │   ├── harness-tester.ts  # Hook simulation engine
│   │   ├── event-logger.ts    # events.jsonl read/write/stats
│   │   ├── event-verifier.ts  # Event-based verification
│   │   ├── tui/               # Interactive provider & model selection
│   │   ├── provider-setup.ts  # Provider configuration UI
│   │   └── tool-checker.ts    # Command executable checks
│   ├── core/
│   │   ├── harness-schema.ts      # harness.yaml Zod schema
│   │   ├── merged-config.ts       # MergedConfig + HooksConfig interfaces
│   │   ├── harness-converter-v2.ts # harness.yaml → MergedConfig (catalog pipeline)
│   │   └── generator.ts           # Orchestrates all generators
│   ├── generators/
│   │   ├── claude-md.ts    # CLAUDE.md with idempotent markers
│   │   ├── hooks.ts        # Hook scripts + event logger injection
│   │   ├── settings.ts     # .claude/settings.json
│   │   └── gitignore.ts    # .gitignore updater
│   ├── detector/
│   │   ├── project-detector.ts  # Deterministic project detection
│   │   ├── types.ts             # ProjectFacts, Detector interface
│   │   └── detectors/           # 14 language detectors
│   ├── cli/
│   │   ├── tui/            # Interactive provider & model selection
│   │   └── provider-setup.ts # Provider configuration UI
│   └── nl/
│       ├── provider-registry.ts # Multi-provider definitions
│       ├── config-store.ts      # ~/.omh/config.json persistence
│       ├── providers/           # Provider implementations
│       │   ├── claude-cli.ts
│       │   ├── claude-api.ts
│       │   ├── openai-api.ts
│       │   └── gemini-api.ts
│       ├── parse-intent.ts      # LLM prompt integration
│       └── prompt-templates.ts  # NL prompt construction
└── tests/                  # 900+ tests (unit + integration)

📦 Requirements

• Node.js >= 20
• Claude CLI (optional, for default NL mode) — Install guide
• API Keys (optional, for Claude/OpenAI/Gemini API modes) — set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY
• Codex CLI OAuth (optional, for codex CLI-wrapper mode) — install codex and run codex login
• Codex OAuth API (optional, experimental direct mode) — run omh config and choose Codex OAuth API to complete device-code sign-in; credentials are stored under ~/.omh

🗺️ Roadmap

• npx oh-my-harness — zero-install usage
• omh sync — regenerate from harness.yaml
• Building block catalog — 17 verified hook templates
• Project detector — 14 language auto-detection
• omh test — dry-run hook verification
• omh stats — TUI analytics dashboard (ink)
• Stateful hook logging — events.jsonl
• TDD Guard — enforce test-first workflow
• Multi-provider AI support — Claude API, OpenAI, Gemini, Codex OAuth
• Interactive model selection per provider
• GitHub star prompt — first-time only
• Codex emitter — AGENTS.md + .codex/hooks.json + .codex/config.toml
• Unified .omh/ layout — single source of truth for hooks & state across runtimes
• Pi (pi.dev) emitter — bridge extension (.pi/extensions/omh-harness.ts) reusing the same .omh/hooks/*.sh
• ask mode — request approval before executing risky tools (Claude native prompt / Pi ctx.ui.select; Codex falls back to block)
• omh uninstall — remove generated artifacts while preserving user content
• omh config — view, reconfigure, or reset the saved AI provider (rotate expired keys, switch provider/model)
• Community harness.yaml registry — share and reuse configs
• omh modify "change X" — NL config editing

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a PR.

💪 Support This Project

oh-my-harness is free and open source. Here's how you can help:

• ⭐ Star — Give a star to help others discover the project
• 🐛 Report Bugs — Open an issue when something doesn't work
• 💡 Request Features — Suggest ideas for new blocks, emitters, or features
• 🔧 Contribute — Fix a bug, add a block, or improve docs — PRs are always welcome
• 📢 Spread the Word — Share oh-my-harness with your team or community

📄 License

MIT