oh-my-harness 0.19.0 → 0.20.0

package/README.md

@@ -2,46 +2,40 @@
 
 # 🐴 oh-my-harness
 
-**Tame your AI coding agents with natural language.**
+**CLAUDE.md is a request. oh-my-harness is enforcement.**
+
+One command turns "TDD enforced, block dangerous commands" into hooks that actually **block** your AI coding agent — for Claude Code, Codex and Pi at once.
 
 [![npm version](https://img.shields.io/npm/v/oh-my-harness.svg)](https://www.npmjs.com/package/oh-my-harness)
 [![npm downloads](https://img.shields.io/npm/dm/oh-my-harness.svg)](https://www.npmjs.com/package/oh-my-harness)
 [![CI](https://github.com/kyu1204/oh-my-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/kyu1204/oh-my-harness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/github/license/kyu1204/oh-my-harness.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
 
-> Stop hand-writing CLAUDE.md files. Describe your project, get enforced guardrails.
+<img src="docs/demo.gif" alt="omh init generates hooks; an AI agent's commit, rm -rf and untested edit are blocked" width="900">
 
 </div>
 
----
-
-## 😤 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:
+```bash
+npx oh-my-harness init "React + FastAPI, TDD enforced, lint on save"
+```
 
-- 📋 Copy-pasting config files between projects
-- 🔓 Forgetting to set up TDD enforcement hooks
-- 💥 Agents committing code without running tests
-- 🎲 Inconsistent behavior across projects
+That is the whole setup. Your agent now hits a wall when it tries to:
 
-## ✨ The Solution
+| Agent tries to... | Result |
+|---|---|
+| `git commit` while tests fail | ⛔ **Blocked** |
+| edit `src/foo.ts` before touching `foo.test.ts` | ⛔ **Blocked** (TDD guard) |
+| run `rm -rf /`, `chmod -R 777`, or any pattern you list | ⛔ **Blocked** |
+| write into `node_modules/`, `.next/`, `dist/` | ⛔ **Blocked** |
+| commit on a branch already merged to main | ⛔ **Blocked** |
+| save a file | ✅ auto-lint |
+| push a branch | ✅ auto-PR |
 
-```bash
-oh-my-harness init "React + FastAPI fullstack, TDD enforced, lint on save"
-```
+Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped.
 
-That's it. oh-my-harness generates **enforced guardrails** — not just instructions, but hooks that actually **block** bad behavior:
+## Why not just write CLAUDE.md?
 
-- ❌ 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.**
+Because agents read instructions and then forget them halfway through a long session. A rule in a markdown file is a suggestion; a `PreToolUse` hook that returns `{"decision":"block"}` is a fact. oh-my-harness writes the markdown **and** the hooks, from one `harness.yaml`, and keeps them in sync (`omh sync --check` fails CI when they drift). Side-by-side with rule-sync tools and git hooks: [docs/comparison.md](docs/comparison.md).
 
 ---
 
@@ -64,135 +58,7 @@ 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:
-
-| Command | Use |
-|---------|-----|
-| `omh sync --check` | CI gate — exits non-zero (and lists the files) when generated output is stale, writes nothing |
-| `omh diff` | Human preview of exactly what `omh sync` would change |
-| `omh doctor --strict` | Health check that also fails on drift (plain `omh doctor` warns) |
-
-```yaml
-# .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
-
-```text
-~/.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
-│   ├── loop/
-│   │   └── worktree/                  # gitignored — the loop's isolated git worktree (see Loop Engine)
-│   ├── state/                         # gitignored — log/runtime data
-│   │   ├── events.jsonl               # Unified hook event log (powers omh stats)
-│   │   ├── loop/                      # run.json (lock + identity), stop flag, runs/<id>/events.jsonl
-│   │   └── tdd-edits.json             # TDD guard working state
-│   └── manifest.json                  # Generated-files manifest
-├── .claude/
-│   ├── settings.json                  # Claude permissions + hooks → .omh/hooks/*.sh
-│   ├── skills/omh-loop/SKILL.md       # "run this as a loop" skill
-│   └── 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
-
-```text
-  ~/.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:
-
-| Language | Detection | Commands |
-|----------|-----------|----------|
-| 🟦 TypeScript/JS | package.json, tsconfig | pnpm/npm/yarn test, eslint, tsc |
-| 🐍 Python | pyproject.toml, requirements.txt, Pipfile, manage.py, .python-version | pytest, ruff, black, isort, mypy |
-| 🍎 Swift | Package.swift, .xcodeproj | swift test, xcodebuild |
-| 🦀 Rust | Cargo.toml | cargo test, cargo clippy |
-| 🐹 Go | go.mod | go test, golangci-lint |
-| ☕ Java/Kotlin | pom.xml, build.gradle | mvn test, ./gradlew test |
-| 💎 Ruby | Gemfile | bundle exec rspec |
-| 🐘 PHP | composer.json | phpunit |
-| 🎯 Dart/Flutter | pubspec.yaml | dart test, flutter test |
-| ⚡ C/C++ | CMakeLists.txt | cmake, make |
-| 🟣 C#/.NET | *.csproj | dotnet test |
-| 💧 Elixir | mix.exs | mix test |
-| 🔷 Scala | build.sbt | sbt test |
-| ⚡ Zig | build.zig | zig build test |
-
-### 🤖 AI Provider Setup
-
-oh-my-harness supports multiple AI providers for natural language mode:
-
-| Provider | Setup | Available Models | Default |
-|----------|-------|------------------|---------|
-| **Claude CLI** | `claude` command installed | Opus 4.6, Sonnet 4.6, Haiku 4.5 | ✓ |
-| **Claude API** | Set `ANTHROPIC_API_KEY` | Opus 4.6, Sonnet 4.6, Haiku 4.5 | Sonnet 4.6 |
-| **OpenAI API** | Set `OPENAI_API_KEY` | GPT-5.5, GPT-5.4, GPT-5.4-mini, GPT-5.4-nano, GPT-4.1, GPT-4.1-mini, o3, o4-mini | GPT-5.5 |
-| **Gemini API** | Set `GOOGLE_API_KEY` | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash Lite, Gemini 3.1 Pro Preview | Gemini 2.5 Pro |
-| **Codex OAuth** | `codex` command installed + `codex login`; runs `codex exec` | GPT-5.5, GPT-5.4, GPT-5.4-mini | GPT-5.5 |
-| **Codex OAuth API** | `omh config` device-code login; imports `~/.codex/auth.json` once if present, then uses `~/.omh` | GPT-5.5, GPT-5.4, GPT-5.4-mini | GPT-5.5 |
-
-Configuration is saved to `~/.omh/config.json` and selected via interactive UI on first use:
-
-```bash
-omh init  # will prompt for AI provider selection and model choice
-```
+📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, AI providers](docs/how-it-works.md)
 
 ---
 
@@ -268,91 +134,7 @@ on a non-blocking block (e.g. `lint-on-save`) is reported and ignored.
 
 ## 🔁 Autonomous Loop Engine
 
-Once `omh init`/`omh sync` has run (with `loop.enabled: true`, the default),
-any agent session (Claude Code, Codex, Pi) can be told **"run this as a loop"** — the generated `omh-loop` skill turns that
-into a fully set-up autonomous loop, no manual wiring:
-
-```text
-you: "ship the remaining Phase B tasks as a loop"
-        │
-        ▼  omh-loop skill (the session becomes the ARCHITECT)
-  1. writes the `loop.ledger`     — default WORKPLAN.md; goal gates + task checkboxes
-  2. writes `loop.workOrders`/*.md — default docs/work-orders; one exact work order per task
-  3. runs `omh loop start`        — a detached supervisor; with `isolate: true` (default), in its own git worktree
-  4. attaches monitoring          — omh loop status, then tail -f .omh/state/loop/runs/<id>/events.jsonl
-        │
-        ▼  loop (fresh headless session per iteration, cheap model)
-  pick next unchecked task → implement its work order exactly → run its
-  acceptance commands → tick checkbox + commit → repeat until the sentinel
-```
-
-The design follows a battle-tested pattern from real autonomous runs: state
-lives in **files** (ledger + git log), never in a conversation. Each iteration
-is a fresh headless session (`claude -p` / `codex exec --dangerously-bypass-hook-trust` / `pi --print --no-session`)
-on an explicit cheap model, so token use stays flat.
-
-### Why it doesn't fall over
-
-Every guard below exists because the failure actually happened somewhere:
-
-| Guard | Failure it prevents |
-|-------|---------------------|
-| Sentinel = fixed string, whole line, clean exit only | a crashed turn (or a turn merely *mentioning* the sentinel) ending the loop as "complete" |
-| Three **separate** backoffs — usage limit / empty-output failed turn / consecutive `BLOCKED` | a loop once spun **266 iterations** doing nothing because waiting-on-a-human was treated like a failure |
-| `loop-guard` hook blocks the loop writing its own work orders (Edit/Write **and** Bash redirection/`cd`) | self-approval: the loop authoring the spec it then implements |
-| `loop-guard` blocks architect-only paths, listed **by name** | an abstract "don't improvise" is ignored; a named path is obeyed |
-| Worktree isolation (`isolate: true`, default) | the loop and the architect fighting over the same working tree |
-| Ledger seeded once, re-seeded only when the main-tree copy is newer | the loop's progress being rolled back — or a second goal reusing the first goal's ledger |
-
-### Configuration
-
-On by default. Everything is optional in `harness.yaml`:
-
-```yaml
-loop:
-  enabled: true                # false removes all loop assets on next sync
-  ledger: WORKPLAN.md          # single source of truth
-  workOrders: docs/work-orders # architect-written task specs
-  model: sonnet                # cheap implementation model (always explicit)
-  sentinel: OMH_GOAL_COMPLETE  # whole-line completion signal
-  interval: 120                # seconds between iterations
-  blockedBackoff: 1800         # backoff once stallStreak blocked/idle turns pile up
-  limitBackoff: 1800           # backoff after a provider usage limit
-  emptyBackoff: 300            # backoff after a crashed (empty-output / timed-out) turn
-  stallStreak: 3               # consecutive blocked/idle turns before blockedBackoff
-  turnTimeout: 7200            # hard per-turn timeout (seconds); the turn is killed past this
-  architectOnly: []            # paths the loop must never touch (name them!)
-  isolate: true                # run in .omh/loop/worktree on branch omh-loop
-  runtime: claude              # claude | codex | pi
-```
-
-### Operating it
-
-```bash
-omh loop start            # preflight, then a detached supervisor (the skill does this for you)
-omh loop status           # run id, pid, iteration, last event, events path
-tail -f .omh/state/loop/runs/<id>/events.jsonl   # progress / blocked / idle / limit / crash
-omh loop stop [--now]     # stop flag + SIGTERM to the whole process group (--now: 1s grace)
-omh loop clean [--branch] # remove the worktree and stale state (and optionally the omh-loop branch)
-```
-
-The supervisor is TypeScript (`src/loop/`), not a generated script: the runtime
-is spawned from an argv array (no shell), each turn is judged by the **ledger
-diff and git HEAD** rather than by grepping output, and the run lock is a single
-`run.json` created atomically with `link(2)`. POSIX only — it relies on process
-groups and `ps` for identity checks.
-
-Known limit: the ledger is seeded into the worktree once per goal (by content
-hash). Editing the main-tree ledger mid-run does nothing until the next start,
-which then re-seeds it — add mid-run tasks as new work orders instead, and edit
-the worktree's ledger if you must.
-
-A task the loop cannot finish (needs a human, or 3 failed attempts) is marked
-`BLOCKED: <reason>` in the ledger and skipped — the loop never idles waiting
-for a person. When you unblock it (e.g. fix an architect-only file), the loop
-picks it back up after its backoff. When the goal completes in isolation, merge
-the `omh-loop` branch and **re-verify** — a clean textual merge is not a
-semantic one.
+Hand omh a `WORKPLAN.md` and it runs one work order per fresh agent session, in an isolated git worktree, with hard-blocked protocol rules. `omh loop start` / `omh loop status` / `omh loop stop`. Full guide: [docs/loop-engine.md](docs/loop-engine.md).
 
 ---
 
@@ -383,210 +165,14 @@ 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.
-
-```bash
-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`
-
-```text
-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:
-
-```text
-┌  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](https://github.com/vadimdemedes/ink) with 3 views:
-
-```text
- [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`:
-
-```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
-
-```text
-oh-my-harness/
-├── bin/                    # CLI entry point
-├── src/
-│   ├── catalog/
-│   │   ├── blocks/         # 18 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, loop (start/run/stop/status/clean)
-│   │   ├── 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
-│   ├── loop/               # autonomous loop supervisor (TypeScript, no generated shell)
-│   │   ├── supervisor.ts   # one run: lock → worktree/seed → turns → release
-│   │   ├── state.ts        # run.json link-lock, events, atomic writes
-│   │   ├── classify.ts     # turn verdict from ledger diff + HEAD; wait policy
-│   │   ├── runtime.ts      # argv per runtime, turn execution in its own process group
-│   │   ├── worktree.ts     # git worktree lifecycle, asset sync, ledger seeding
-│   │   ├── protocol.ts     # the rules, rendered into prompt / CLAUDE.md / skill
-│   │   └── stop.ts         # identity-checked group stop, group sweep
-│   ├── 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)
-```
+Details for `uninstall`, `doctor`, `test`, `stats` and hook event logging: [docs/commands.md](docs/commands.md). Internals: [docs/architecture.md](docs/architecture.md) · [roadmap](docs/roadmap.md).
 
 ---
 
 ## 📦 Requirements
 
 - **Node.js** >= 20
-- **Claude CLI** (optional, for default NL mode) — [Install guide](https://docs.anthropic.com/en/docs/claude-code)
-- **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
-
-- [x] `npx oh-my-harness` — zero-install usage
-- [x] `omh sync` — regenerate from harness.yaml
-- [x] Building block catalog — 18 verified hook templates
-- [x] Project detector — 14 language auto-detection
-- [x] `omh test` — dry-run hook verification
-- [x] `omh stats` — TUI analytics dashboard (ink)
-- [x] Stateful hook logging — events.jsonl
-- [x] TDD Guard — enforce test-first workflow
-- [x] Multi-provider AI support — Claude API, OpenAI, Gemini, Codex OAuth
-- [x] Interactive model selection per provider
-- [x] GitHub star prompt — first-time only
-- [x] Codex emitter — `AGENTS.md` + `.codex/hooks.json` + `.codex/config.toml`
-- [x] Unified `.omh/` layout — single source of truth for hooks & state across runtimes
-- [x] Pi ([pi.dev](https://pi.dev)) emitter — bridge extension (`.pi/extensions/omh-harness.ts`) reusing the same `.omh/hooks/*.sh`
-- [x] `ask` mode — request approval before executing risky tools (Claude native prompt / Pi `ctx.ui.select`; Codex falls back to block)
-- [x] `omh uninstall` — remove generated artifacts while preserving user content
-- [x] `omh config` — view, reconfigure, or reset the saved AI provider (rotate expired keys, switch provider/model)
-- [x] Autonomous loop engine — `omh-loop` skill, worktree-isolated runner, loop-guard, JSONL monitoring
-- [ ] Community harness.yaml registry — share and reuse configs
-- [ ] `omh modify "change X"` — NL config editing
+- **An AI provider** (optional, only for natural-language `omh init`) — any one of: the `claude` CLI, an API key for Claude/OpenAI/Gemini/OpenRouter, a ChatGPT subscription via Codex, or a local OpenAI-compatible server (Ollama etc.). See [AI Provider Setup](docs/how-it-works.md#-ai-provider-setup).
 
 ---
 

package/dist/catalog/blocks/tdd-guard.js

@@ -63,7 +63,7 @@ fi
 # 대응 테스트 파일 확인 — 확장자 제거
 BASENAME=$(basename "\$FILE_PATH" | sed -E 's/\\.[^.]+$//')
 
-REASON="oh-my-harness: TDD — \${BASENAME} 에 대응하는 테스트 파일을 먼저 수정하세요"
+REASON="oh-my-harness: TDD guard — edit the test for \${BASENAME} first, then the source"
 if [[ ! -f "\$HISTORY_FILE" ]]; then
   _log_event "block" "\$REASON"
   _emit_decision "block" "\$REASON"

package/dist/cli/commands/config.js

@@ -7,7 +7,9 @@ function printSummary(config) {
     console.log(`  method:   ${chalk.cyan(config.method)}`);
     if (config.method === "api") {
         console.log(`  model:    ${chalk.cyan(config.model ?? "(default)")}`);
-        console.log(`  api key:  ${chalk.dim(maskApiKey(config.apiKey))}`);
+        if (config.baseUrl)
+            console.log(`  base url: ${chalk.cyan(config.baseUrl)}`);
+        console.log(`  api key:  ${chalk.dim(config.apiKey ? maskApiKey(config.apiKey) : "(none)")}`);
     }
     else if (config.method === "oauth") {
         console.log(`  model:    ${chalk.cyan(config.model ?? "(default)")}`);
@@ -72,10 +74,17 @@ export async function configCommand(options = {}) {
         console.log(chalk.green("Removed ~/.omh/config.json"));
         return { exitCode: 0 };
     }
-    // Default: show current config (if any), then reconfigure.
+    // Default: show current config, then ask before launching setup so a plain
+    // `omh config` is a safe read; `--yes` skips the prompt.
     if (existing) {
         printSummary(existing);
         console.log("");
+        if (!options.yes) {
+            const confirm = options.confirm ?? defaultConfirm;
+            const ok = await confirm("Reconfigure the AI provider?");
+            if (!ok)
+                return { exitCode: 0 };
+        }
     }
     else {
         console.log("No AI provider configured yet. Let's set one up.\n");

package/dist/cli/tui/open-browser.d.ts

@@ -0,0 +1,19 @@
+import type { EventEmitter } from "node:events";
+type SpawnLike = (cmd: string, args: string[], opts: {
+    detached: boolean;
+    stdio: "ignore";
+}) => EventEmitter & {
+    unref(): void;
+};
+export declare function browserCommandFor(platform: NodeJS.Platform, url: string): [string, string[]];
+/**
+ * Best-effort: open the URL in the OS default browser. Never throws; returns
+ * false so callers can tell the user to open it by hand (SSH, containers).
+ */
+export declare function openInBrowser(url: string, deps?: {
+    spawn?: SpawnLike;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;
+/** OSC 8 terminal hyperlink: stays one clickable link even when soft-wrapped. */
+export declare function hyperlink(url: string): string;
+export {};

package/dist/cli/tui/open-browser.js

@@ -0,0 +1,34 @@
+import { spawn as nodeSpawn } from "node:child_process";
+export function browserCommandFor(platform, url) {
+    if (platform === "darwin")
+        return ["open", [url]];
+    if (platform === "win32")
+        return ["cmd", ["/c", "start", "", url]];
+    return ["xdg-open", [url]];
+}
+/**
+ * Best-effort: open the URL in the OS default browser. Never throws; returns
+ * false so callers can tell the user to open it by hand (SSH, containers).
+ */
+export function openInBrowser(url, deps = {}) {
+    if (!/^https?:\/\//.test(url))
+        return Promise.resolve(false);
+    const spawn = deps.spawn ?? nodeSpawn;
+    const [cmd, args] = browserCommandFor(deps.platform ?? process.platform, url);
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => resolve(true));
+            child.unref();
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/** OSC 8 terminal hyperlink: stays one clickable link even when soft-wrapped. */
+export function hyperlink(url) {
+    const ESC = String.fromCharCode(27);
+    return `${ESC}]8;;${url}${ESC}\\${url}${ESC}]8;;${ESC}\\`;
+}