Metadata-Version: 2.4
Name: oh-my-hermes
Version: 3.0.0
Summary: Install a Hermes-native skill workflow pack.
Author: oh-my-hermes maintainers
License-Expression: MIT
Project-URL: Homepage, https://rlaope.github.io/oh-my-hermes/
Project-URL: Issues, https://github.com/rlaope/oh-my-hermes/issues
Project-URL: Repository, https://github.com/rlaope/oh-my-hermes
Keywords: hermes,agent,skills,workflow,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="assets/oh-my-hermes-wordmark.png" alt="OH-MY-HERMES" width="100%" style="display:block;max-width:none;height:auto">
</p>

# oh-my-hermes

<p align="center">
  <a href="README.md">English</a> |
  <a href="README.ko.md">한국어</a> |
  <a href="README.ja.md">日本語</a> |
  <a href="README.zh.md">中文</a>
</p>

<p align="center">
  <a href="https://github.com/rlaope/oh-my-hermes"><img alt="GitHub" src="https://img.shields.io/badge/github-rlaope%2Foh--my--hermes-181717?logo=github"></a>
  <a href="https://github.com/NousResearch/hermes-agent"><img alt="Hermes Agent" src="https://img.shields.io/badge/Hermes%20Agent-NousResearch-6f42c1?logo=github"></a>
  <a href="https://github.com/rlaope/oh-my-hermes"><img alt="OMH stars" src="https://img.shields.io/github/stars/rlaope/oh-my-hermes?style=flat&logo=github"></a>
  <a href="https://github.com/NousResearch/hermes-agent"><img alt="Hermes Agent stars" src="https://img.shields.io/github/stars/NousResearch/hermes-agent?style=flat&logo=github"></a>
</p>

<p align="center">
  <img src="assets/hermes-agent-hero.png" alt="Oh My Hermes" width="720">
</p>

<p align="center">
  <strong>Install once. Keep Hermes. Add a stronger operating layer.</strong>
  <br>
  <em>Planning, research, creation, coding handoffs, operations, and project memory with explicit evidence boundaries.</em>
</p>

<p align="center">
  <img src="assets/oh-my-hermes-agent-poster.png" alt="Oh My Hermes Agent poster" width="720">
</p>

<p align="center">
  <strong>oh-my-hermes</strong> (OMH) turns a normal
  <a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a>
  request into a clear capability, a useful next step, and an honest record
  of what actually happened — strengthening the workflow you already use,
  never replacing Hermes or hiding a coding executor behind it.
  <br><br>
  OMH is the operating layer above Hermes-native skills: it frames the
  problem, picks the workflow and evidence gates, and runs native skills
  as capabilities inside that governed path.
</p>

[Website](https://rlaope.github.io/oh-my-hermes/) ·
[Documentation](docs/README.md) ·
[Installation](docs/INSTALLATION.md) ·
[Capabilities](docs/CAPABILITIES.md) ·
[Capability Impact](docs/CAPABILITY_IMPACT.md) ·
[Agent Install](INSTALL_FOR_AGENTS.md) ·
[GitHub Pages site](site/index.html)

> [!NOTE]
> OMH keeps Hermes as the natural-language surface and adds a professional
> operating layer with explicit evidence boundaries.
>
> <p align="center">
>   <img src="assets/omh-terminal-boot-banner.png" alt="OH-MY-HERMES terminal banner listing available tools, grouped skills, OMH specialists, infrastructure, and the model pool on Hermes Agent" width="1080">
> </p>

> [!TIP]
> Be with us!
>
> <table>
>   <tr>
>     <td width="124"><a href="https://x.com/rlaope"><img alt="X link" src="https://img.shields.io/badge/Follow-%40rlaope-00CED1?style=flat-square&logo=x&labelColor=black" width="112" /></a></td>
>     <td>Updates for <code>oh-my-hermes</code> are shared on <a href="https://x.com/rlaope">@rlaope</a> on X, alongside release notes and project news.</td>
>   </tr>
>   <tr>
>     <td width="124"><a href="https://github.com/rlaope"><img alt="GitHub Follow" src="https://img.shields.io/github/followers/rlaope?style=flat-square&logo=github&labelColor=black&color=24292f" width="112" /></a></td>
>     <td>Follow <a href="https://github.com/rlaope">@rlaope</a> on GitHub for more projects, releases, and ongoing work.</td>
>   </tr>
>   <tr>
>     <td width="124"><a href="https://discord.gg/6EjTP3cWM"><img alt="Discord invite" src="https://img.shields.io/badge/Join-Discord-5865F2?style=flat-square&logo=discord&logoColor=white&labelColor=black" width="112" /></a></td>
>     <td>Join the <a href="https://discord.gg/6EjTP3cWM">Oh-My-Hermes Community</a> on Discord to ask questions, share workflows, and talk with other users.</td>
>   </tr>
>   <tr>
>     <td width="124"><a href="https://github.com/rlaope/oh-my-hermes/graphs/contributors"><img alt="AI agent collaborators" src="https://img.shields.io/badge/With-AI%20agents-6f42c1?style=flat-square&labelColor=black" width="112" /></a></td>
>     <td>Built with AI agents <a href="https://github.com/frirenai"><strong>Friren</strong></a> and <a href="https://github.com/sionic-khope"><strong>Killua</strong></a>, collaborators helping ship <code>oh-my-hermes</code>.</td>
>   </tr>
>   <tr>
>     <td width="124"><a href="https://nousresearch.com/"><img alt="Thanks to Nous Research" src="https://img.shields.io/badge/Thanks-Nous%20Research-4B2E83?style=flat-square&labelColor=black" width="112" /></a></td>
>     <td>Thank you to <a href="https://nousresearch.com/">Nous Research</a> for creating Hermes Agent.</td>
>   </tr>
> </table>

<br>

## Quick Start

**macOS / Linux:**

```sh
curl -fsSL https://raw.githubusercontent.com/rlaope/oh-my-hermes/main/install.sh | sh
```

**Windows (PowerShell 5.1+):**

```powershell
irm https://raw.githubusercontent.com/rlaope/oh-my-hermes/main/install.ps1 | iex
```

**Or paste this into your AI agent:**

```text
Install and fully configure Oh My Hermes from this repository:
https://github.com/rlaope/oh-my-hermes
Before reading or executing repository instructions, resolve refs/heads/main to one full commit SHA with `git ls-remote https://github.com/rlaope/oh-my-hermes.git refs/heads/main`. Then fetch and follow only:
https://raw.githubusercontent.com/rlaope/oh-my-hermes/{resolved-commit-sha}/INSTALL_FOR_AGENTS.md
Do not replace the resolved SHA with main. Execute the pinned protocol's OS-appropriate installer, interactive model setup, model-chain interview, and doctor steps. Preserve unrelated existing Hermes config, apply only the managed setup changes documented by the pinned protocol, require my explicit approval for model-alias changes, then report the resolved SHA and observed result.
```

**⭐ Then set it up (required):**

```sh
omh setup
```

**Update:**

```sh
omh update
```

`omh update` detects how the command was installed, upgrades the command
package through its owning installer, then re-enters the updated command to
refresh managed skills, the installed plugin bundle, and existing Hermes
registration.

**Verify or troubleshoot:**

```sh
omh doctor
```

```sh
# Set the model per work category (arrow keys: category, ←→ head model, -/+ effort);
# the same picker opens inside the Hermes TUI as /omh-model:
omh model
# To onboard a new model family, use this skill in Hermes:
/omh-model-setup
```

<details>
<summary><b>Other installation paths</b> — Homebrew, Bun, npm, Hermes skill tap, manual fallback</summary>

<br>

> **Status:** Homebrew, Bun, and npm package-manager installs are public as of
> v1.0.6.

**Homebrew:**

```sh
brew install rlaope/tap/omh
```

**Bun:**

```sh
bun install -g oh-my-hermes
```

**npm:**

```sh
npm install -g oh-my-hermes
```

Run `omh setup` after any of these, same as above.

**Hermes skill tap path:**

```sh
hermes skills tap add rlaope/oh-my-hermes
hermes skills install rlaope/oh-my-hermes/skills/omh-routing --yes
```

**Manual package-manager fallback or removal:**

| Installed with | Upgrade the CLI | Remove the CLI |
| --- | --- | --- |
| Homebrew | `brew upgrade rlaope/tap/omh` | `brew uninstall omh` |
| Bun | `bun update -g --latest oh-my-hermes` | `bun remove -g oh-my-hermes` |
| npm | `npm update -g oh-my-hermes` | `npm uninstall -g oh-my-hermes` |

Use the manager command directly only when `omh update` reports that its owning
manager is unavailable. Removing the command package preserves OMH state. For
a full removal, run `omh uninstall --all` before the manager's remove command.

Maintenance paths such as reconciling a `--full` install back to core live in
[Installation](docs/INSTALLATION.md#reconciling-an-existing-full-install-back-to-core).

</details>

<br>

## What you get

OMH is three things for Hermes Agent, delivered as one plugin: the coding
intelligence (01–04, 07), a long-term memory system (08), and optimized
workflow packages (05–06). One scene each, drawn from the real surfaces.

### 01 · Per-model tuning, task splitting, and stronger coding skills

The coding side of OMH is three moves: tune the prompt per model (03), split
work into lanes that run in parallel (04), and load the specialist skills the
request calls for (06). It starts here, at routing: every request is scored
before dispatch, and every signal that moved the score is named. A rename scores light and goes to the quick lane. "Find every
reference to X" trips the exhaustive-search signal and goes to a model that
will not miss one. Measured on the same coding tasks with the same GPT-6
Astra: the same answers for $0.66 instead of $4.29, in 5 minutes instead of
23.

<p align="center">
  <img src="assets/showcase-01-routing.svg" alt="omh coding complexity scoring two requests, and the measured Astra table: same 18 of 30 solved, $4.29 to $0.66, 23 to 5 minutes" width="1080">
</p>

### 02 · Categories you own, per executor

`ultrabrain`, `deep`, `architect`, `unspecified-high`, `unspecified-low`,
`quick`, `writing`, `visual-engineering`, `artistry`, `capable`, `simple-work`,
`deep-work`: each is an editable chain of model + effort, the same twelve listed
under Recommended models below, read and overridden in one file. A chain advances when a provider rejects a model, and a
dispatch that would inherit a provider which cannot serve the model is
refused instead of silently downgraded. Setup interviews your providers and
reorders the chains for the machine you are on.

<p align="center">
  <img src="assets/showcase-02-categories.svg" alt="omh coding category-maestro show: per-executor category chains, one operator override, and a refused dispatch" width="1080">
</p>

### 03 · Prompting tuned per model family, and measured

Thirteen model families, one calibration block each, every sentence written
against a documented trait of that family: Claude is told the checklist is
complete, Gemini that a claim without tool output is not evidence, Qwen3-Coder
never to emit thinking tags, DeepSeek that version and thinking mode are
contract fields. GPT-6 Astra gets its own exact-model contract and block. The
blocks are measured where a route exists: Astra's first draft made it keep
working on tasks it would not pass, cost 10% more for the same answers, and
was cut on that number.

<p align="center">
  <img src="assets/showcase-03-calibration.svg" alt="One calibration line per model family, the gpt-6-astra model contract, and the measured revision" width="1080">
</p>

### 04 · Parallel where it is safe, typed when it comes back

`ulw-work` splits an accepted plan into units that never share a file, gives
each one its own worktree branched from one pinned SHA, and lets a unit issue
its tool calls in one turn. Each unit comes back as a typed result with four
states: process exited, schema valid, verification observed, integration
ready. Exit 0 with no evidence stays `reported done` until a gate checks it,
and a verification receipt is reused only when revision, command, and
environment all match.

<p align="center">
  <img src="assets/showcase-04-parallel.svg" alt="An ulw-work fan-out: three units with disjoint files, one worktree each, typed states, and the tool calls issued in one turn" width="1080">
</p>

### 05 · The Oh-My-Hermes interface, and Hermes Agent workflows

The interface is the Hermes terminal with an OMH dock under the prompt and a
phase todo above it; the workflows are the `ulw-*` engines and every `omh-*`
skill, routed from chat. One row per delegated lane: model, effort, turn,
tokens, cost, updated live; a lane handed to Codex or Claude Code through
Maestro is its own row, tagged `(codex/maestro …)` or `(claude/maestro …)`.
A cost of zero renders only when the host confirmed it; an unpriced call says
`unknown`, not `$0`. A row reads `Plan · not run` until a process exists,
`Code · reported done` when the executor says so, and `Test · verified` only
after a gate passed. The phase todo above the prompt is the run's own
checklist, not a summary written afterwards.

<p align="center">
  <img src="assets/showcase-05-hud.svg" alt="The OMH HUD: per-lane rows with model, effort, turn, tokens, cost provenance, and evidence state, plus the phase todo" width="1080">
</p>

### 06 · Expert skills seep into the run

You never invoke an expert. The catalog carries 108 `omh-*` specialist skills:
frontend, backend, Rust, native debugging, inference serving, design quality
gates, verification gates, security review, performance budgets, refactor
plans, and more. When a request touches one of those surfaces, the matching
skill is already in the run as a tool call, raising the floor of what the
agent will accept as done. Say it in English or Korean; the router picks the
specialists.

<p align="center">
  <img src="assets/showcase-06-skills.svg" alt="Expert omh-* skills loading into one run as tool calls, an orbit of specialists around the run, and three numbers" width="1080">
</p>

### 07 · The architecture in one picture, then improved in phases

Ask for a picture of the repo and `codebase-uml` draws it from the code:
packages, modules, and every import edge, with the cycles marked. The
findings come ranked, and `refactor-plan` turns the top ones into phases that
each land as one PR, behavior-locked by the tests, and abort the moment a lock
breaks. The before and after are measured on the tree, and the dock shows
each phase as it runs, and whether anything checked it.

<p align="center">
  <img src="assets/showcase-07-architecture.svg" alt="codebase-uml draws the repo with two cycles, the findings and a phased refactor plan beside it, the measured before and after, and one dock row per phase" width="1080">
</p>

### 08 · A long-term memory that a reviewer admitted

Nothing is remembered silently. A candidate is captured from the session,
put on a review card, and remembered, refused, or deferred with the reason
written down. An approved record carries its provenance and a review-due
date; confirming it resets the clock, silence ages it from active to
reference to archive. The next session gets a recall pack ranked for its task
and cut to a token budget, with conflicts and duplicates resolved. Hermes'
own memory is never read or patched; this store is OMH's, file-backed and
reviewed. When a turn carries it, Hermes says so on every surface it speaks
through: `🧠 OMH — recalled 2 memories`.

<p align="center">
  <img src="assets/showcase-08-memory.svg" alt="Long-term memory: admission cards, one record's lifecycle, attention tiers, and a budgeted recall pack for the next session" width="1080">
</p>

<br>

## The OH-MY-HERMES terminal

Bare `omh` opens Hermes — the same door as `hermes` — wearing the OMH
identity:

```sh
omh
```

<table align="center">
  <tr>
    <td width="50%" align="center">
      <img src="assets/omh-terminal-boot-hud.png" alt="The OH-MY-HERMES boot"><br>
      <sub><b>The OH-MY-HERMES boot.</b></sub>
    </td>
    <td width="50%" align="center">
      <img src="assets/omh-terminal-ulw-work-session.png" alt="An ulw-work run"><br>
      <sub><b>An <code>ulw-work</code> run.</b></sub>
    </td>
  </tr>
</table>

What the terminal shows while OMH workflows run:

- **Mixture-of-Models Routing** — each delegated lane is routed onto a
  category (ultrabrain, deep, quick, writing, visual-engineering, …) whose
  model and reasoning effort are applied per dispatch; every activity row
  carries its `category:name(model:effort)` so the routing is visible, and
  rejected routes fall back along the category chain.
- **Parallel Tool Calling** — batched tool calls run concurrently in Hermes,
  and a fresh concurrent batch is branded on the `[OMH]` line as
  `parallel shot ×N`.
- **Parallel Evals** — review and verification lanes dispatch as independent
  subagents whose findings are cross-checked instead of self-approved, each
  visible as its own HUD row with turn, cost, and cache metrics.
- **Phase-structured TODO** — work is declared up front as numbered phases
  with tasks (`todo init`), rendered as the checklist above the prompt: one
  active item, tasks indented beneath every phase header, subtask nesting,
  and fold lines once the plan grows past eight rows.

<table align="center">
  <tr>
    <td width="50%" align="center">
      <img src="assets/hermes-desktop.gif" alt="Hermes Desktop running an ultrawork prompt with the OMH pane showing the plan and each lane's model" width="380" height="266"><br>
      <sub><b>Hermes Desktop, with oh-my-hermes.</b><br>One ultrawork prompt: the plan, the lanes, and the model each lane runs on, in the OMH pane.</sub>
    </td>
    <td width="50%" align="center">
      <img src="assets/hermes-cli.gif" alt="Hermes TUI running an ultrawork lane fan-out with the OMH plan dock and HUD" width="380" height="266"><br>
      <sub><b>Hermes CLI, with oh-my-hermes.</b><br>The same ultrawork run in the terminal: the plan dock above, each lane's route in the HUD.</sub>
    </td>
  </tr>
  <tr>
    <td width="50%" align="center">
      <img src="assets/hermes-messenger.gif" alt="Hermes messenger app running an OMH workflow" width="380" height="266"><br>
      <sub><b>Hermes messenger app, with oh-my-hermes.</b><br>Ask in a thread; the run reports back there.</sub>
    </td>
    <td width="50%" align="center">
      <img src="assets/omh-setup.gif" alt="omh setup installing the OMH workflows" width="380" height="266"><br>
      <sub><b><code>omh setup</code>, one command.</b><br>Installs the workflows and connects them to Hermes.</sub>
    </td>
  </tr>
</table>

<br>

## Recommended models

<p align="center">
  <img src="assets/omh-model-tui.png" alt="/omh-model in the Hermes Modern TUI: one row per category with its head model, effort bar and state; the cursor row shows the left/right and -/+ handles" width="820">
</p>

OMH ships with these editable, ordered recommendation chains. Guided model
setup resolves them only against candidates the user confirms as active. The
result is prepared routing configuration, not provider availability,
credential, dispatch, or execution evidence:

| Category alias | What it is for | Editable recommendation order |
| --- | --- | --- |
| `ultrabrain` | Deepest reasoning | GPT-6 Astra (xhigh) |
| `deep` | Strong default tier | GPT-6 Sol, then DeepSeek Flash (V4.1) (high) |
| `architect` | Architecture and system design | Claude Fable 5.1, then GPT-6 Astra, then Kimi K3 (xhigh) |
| `unspecified-high` | Default working model | Kimi K3, then Claude Opus 5.5 (medium) |
| `unspecified-low` | Cheaper fallback | GLM 5.3, then DeepSeek Flash (V4.1), then Claude Opus 5.5 (low) |
| `quick` | Short tasks | GLM 5.3 Flash, then Kimi K3, then GPT-6 Luna, then Claude Fable 5.1 (low) |
| `writing` | Prose and docs | Kimi K3, then Qwen3-Coder, then Gemini 3.1 Pro (medium) |
| `visual-engineering` | Frontend and visual | Claude Fable 5.1, then Kimi K3 (high) |
| `artistry` | Unconventional work | Gemini 3.1 Pro, then Claude Fable 5.1, then Kimi K3 (high) |
| `capable` | Strong general work | Claude Fable 5.1, then Claude Opus 5.5, then Kimi K3, then GLM 5.3 (medium) |
| `simple-work` | Small everyday tasks | GPT-6 Luna, then DeepSeek Flash (V4.1), then Claude Haiku 4.5 (low) |
| `deep-work` | Long tasks at frontier depth | GPT-6 Astra (high) |

Want to try the Ultrafast tier — Kimi K3 Ultrafast (300 TPS) and
GLM 5.3 Ultrafast? They are served on
[OpenGateway](https://opengateway.ai/).

Every chain above is user-editable without touching code. The chains are
managed in one file — `omh setup` seeds it:

```sh
$ cat ~/.omh/routing/model-chains.json
{
  "categories": {},
  "schema_version": "mixture_chain_overrides/v1"
}
```

Empty `categories` keeps every shipped default above live. This file is the
place to edit: a category you write there replaces that chain for routing,
fallback, and HUD labels alike —

```json
{
  "schema_version": "mixture_chain_overrides/v1",
  "categories": {
    "architect": [
      {"model": "claude-fable-5-1", "reasoning_effort": "xhigh"},
      {"model": "gpt-5.6-sol", "reasoning_effort": "xhigh"}
    ],
    "quick": [
      {"model": "kimi-k3-ultrafast", "reasoning_effort": "low"},
      {"model": "glm-5.3-ultrafast", "reasoning_effort": "low"}
    ]
  }
}
```

Check the chains currently in effect with `omh model-chains show`. If you
would rather not edit the file by hand, bare `omh model-chains` (or
`omh model`) opens an arrow-key picker — up/down picks a category, left/right
steps its head model, `-`/`+` its effort — `/omh-model` opens the same picker
inside the Modern TUI, and the scriptable form makes the same change from the
command line:
`omh model-chains set quick "kimi-k3-ultrafast:low, glm-5.3-ultrafast:low"`.
When an alias uses a provider-specific wire ID, map it once in
`~/.omh/routing/model-providers.json` with
`model_provider_routes/v1`; `set`, `status`, fallback, and HUD then report the
complete alias/provider/wire-model route. OMH stores only provider IDs, never
provider credentials.

Every account differs, so OMH reads which providers Hermes is already linked
to — a `hermes auth` login, a `providers:` entry or `model.provider` in the
Hermes config, an API-key variable name in `$HERMES_HOME/.env` — and counts
them on its own: each chain is reordered so the entries a linked provider can
serve lead, the pickers mark the rest, nothing is removed, and nothing is
invoked to check. Only ids and variable names are read, never a key or a
token. The interactive `omh setup` still asks, with the linked rows
pre-ticked, so you can correct a kind, untick a linked provider you cannot
really use, add one OMH could not place, or say whether you have a Claude
Code subscription; its answers land in `~/.omh/routing/providers.json`
(`provider_entitlements/v1`) and win over detection. The Claude Code
subscription only seeds the Claude Code `--model` preference for the Maestro
lane, because Hermes itself cannot spend it.

Ask Hermes to **set up my models** to review or change them. These are editable
preferences, not benchmark results. See
[Guided Model Setup](docs/INSTALLATION.md#guided-model-setup) for the detailed
setup, fallback, provider, and ownership rules.

Coding delegation dispatch (`omh coding run` / `omh coding fanout dispatch`)
— the Maestro lane that spawns Claude Code or Codex directly — has the same
category dial as its own sibling file. Route it per work category with

```sh
$ omh coding category-maestro set codex ultrabrain gpt-5.6-sol:xhigh
$ omh coding category-maestro interview   # guided walk, Enter keeps each chain
$ omh coding run --owner codex --category ultrabrain --goal ...
```

which edits `~/.omh/routing/category-maestro.json`
(`omh_category_maestro/v1`); `omh coding category-maestro show` prints the
effective table with operator overrides marked, and the interactive
`omh setup` offers the same walk. An explicit `--model` on a run always wins,
and `~/.omh/routing/dispatch-models.json` remains the per-owner default used
only when no route resolves at all (for the strongest Claude Code tier, set
`"claude-code": "opus"` there). See `docs/FANOUT.md` (Category-maestro and
Dispatch-model preference) for schemas and the full precedence order.

<details>
<summary><strong>Or paste this into Hermes or another coding agent</strong></summary>

```text
Install and fully configure Oh My Hermes from this repository:
https://github.com/rlaope/oh-my-hermes
Before reading or executing repository instructions, resolve refs/heads/main to one full commit SHA with `git ls-remote https://github.com/rlaope/oh-my-hermes.git refs/heads/main`. Then fetch and follow only:
https://raw.githubusercontent.com/rlaope/oh-my-hermes/{resolved-commit-sha}/INSTALL_FOR_AGENTS.md
Do not replace the resolved SHA with main. Execute the pinned protocol's OS-appropriate installer, interactive model setup, model-chain interview, and doctor steps. Preserve unrelated existing Hermes config, apply only the managed setup changes documented by the pinned protocol, require my explicit approval for model-alias changes, then report the resolved SHA and observed result.
```

</details>

<br>

## Ultra-Skills

<p align="center">
  <img src="assets/omh-character-badge.png" alt="Oh My Hermes character mark" width="170">
</p>

<!-- omh:ulw-inventory:begin (generated: uv run python -m omh.cli docs ulw-inventory; source: src/skills/catalog.py) -->
Nine `ulw-` workflows. Say the trigger in chat — Hermes routes the
rest. Full catalog: [Workflow Reference](docs/WORKFLOWS.md).

| Workflow&nbsp;command | What it does |
| --- | --- |
| ⚡ `ulw-context` | Aligns reviewed project terms, captures confirmed candidates, and interviews the next decision frontier without giving terminology routing authority. |
| ⚡ `ulw-interview` | Asks one question at a time until it knows exactly what you want. |
| ⚡ `ulw-research` | Digs through real code and the live web, keeps sources, and verifies anything doubtful. |
| ⚡ `ulw-plan` | Builds a reviewed plan: options compared, risks named, done-criteria agreed. |
| ⚡ `ulw-work` | Runs an accepted plan in parallel lanes that never touch the same file. |
| ⚡ `ulw-maestro` | Runs a delegated task on Claude Code or Codex — prompt composed from the CLI's own installed skills, spawned live with a dock row and a steerable session. |
| ⚡ `ulw-loop` | Cycles plan → build → review until the goal actually passes. |
| ⚡ `ulw-qa` | Attacks the build with hostile scenarios and fixes what breaks. |
| ⚡ `ulw-perf` | Measures where it is actually slow or expensive, then fixes one hot path at a time. |
<!-- omh:ulw-inventory:end -->

<br>

## What OMH Adds

Hermes Agent already runs the loop. OMH decides what goes into it: which
model and effort each lane gets, who owns the code change, which skills
apply, and what counts as done. Two rules hold everywhere — model choice
and coding ownership are separate decisions, and nothing prepared is ever
reported as executed. The generated catalog, triggers, and evidence rules
live in [Workflow Reference](docs/WORKFLOWS.md).

### The workflow

**Understand → Research → Decide → Plan → Execute → Verify → Operate → Learn**

| Stage | What happens |
| --- | --- |
| Understand | Confirm the intent, constraints, project terms, and stop conditions. |
| Research | Replace assumptions with source-backed product, code, or operational context. |
| Decide | Make the options, tradeoffs, and decision owner explicit. |
| Plan | Turn accepted scope, coding ownership, tests, and done criteria into an executable plan. |
| Execute | Dispatch bounded work to the selected owner and track what actually runs; a prepared handoff is not execution evidence. |
| Verify | Base the verdict on observed test results, review findings, CI status, and runtime evidence. |
| Operate | Keep release health, incidents, rollback state, and follow-up work visible. |
| Learn | Promote reviewed, scoped lessons into project memory or workflow improvements. |

**Highlights**

| Intelligence | What OMH adds |
| --- | --- |
| 🧭 **Mixture-of-models routing** | Every delegated lane lands on a category (model + reasoning effort) at dispatch time. Chains fall through when a provider rejects a model, and a child that did no work shows `failed`, never a green row. |
| 🎛️ **Per-family calibration** | Prompting is tuned per model family and generation — GPT-6 Astra, GPT-5.6, Claude 5.1, GLM 5.3, Kimi, Gemini, Qwen, DeepSeek and more — and each tune is kept only while the benchmark pair says it helps. |
| 🗂️ **Categories you own** | Twelve shipped categories per executor, with `omh model-chains set` to reorder, an entitlement interview that reorders chains per machine, and a live view of what a request would route to before it runs. |
| 🖥️ **Native TUI surface** | The OMH HUD (live rows with category, turns, cost, cache), the phase todo above the prompt, `parallel shot ×N`, full-row diff bands, and managed skins — installed beside Hermes, never patching it. |
| ⚡ **Observed parallel work** | Independent work splits into fanout units with disjoint file ownership, admission control under provider pressure, typed result sidecars, and verification gates that read what came back. |
| 🎼 **Maestro handoffs** | An explicit second lane for Codex, Claude Code, or another CLI: readiness probes, capability snapshots, owner-fit reports, and per-run model and effort — opt-in, and never the default path. |
| 💸 **Priced cost telemetry** | Token counts and dollar figures on every HUD row and run summary, priced from a rate table that cites its source; an unpriceable run reads `unknown`, never `$0`. |
| 🧠 **Long-term project memory** | A file-backed memory provider Hermes loads, admission and retention policies, reviewer-gated writes, and recall packs with freshness and budget — Hermes' own memory stays untouched. |
| 🔎 **Structural code search** | A measured `ast-grep` playbook (28 languages, grep fallback) and `omh codegraph uml` for a repo-wide architecture picture, injected where executors read code; `omh codegraph tests --changed` names the tests a change reaches ([codegraph commands](docs/CODEGRAPH.md)). |
| 🛡️ **Guardrails you write** | Toolcall rules that block an off-script call with your own rule text, a completion-integrity gate that refuses stubs and skipped tests as evidence, and an approval tier for risky actions. |
| ♾️ **Ultra workflow engines** | Parallel delivery lanes, measured goal loops with ledgers and real completion gates, and decision-frontier interviews before any engine runs — listed in Ultra-Skills above. |
| 📦 **A deterministic catalog** | A hundred-plus installable skills generated from one source, routing precision corpora with negative controls, and drift gates that fail CI on a single divergent byte. |

<br>

## Evidence Before Claims

OMH never reports that work happened unless it watched it happen. Every status
you see has two parts: the stage, and how sure OMH is about it.

| You see | It means |
| --- | --- |
| `Plan · not run` | A prompt or plan is ready. **Nothing has run yet.** |
| `Code · running` | An executor is running now, and OMH is watching it. |
| `Code · reported done` | The executor said it finished. Nobody checked the result. |
| `Test · verified` | A test, review, or CI gate actually passed. |

The distinction that matters is the second row from the bottom: an executor
saying it is done is not the same as anything having been checked, and most
tools spell both "complete". Capability impact is reported across separate
dimensions rather than collapsed into one marketing score. See
[Capability Impact](docs/CAPABILITY_IMPACT.md).

### Measured: Hermes alone vs Hermes through OMH

`benchmarks/product-ab/v1` compares the two products on a pinned corpus of
this repository's own merged pull requests, graded by those pull requests'
own tests, and reports four numbers per arm: pass rate, cost per passed task,
wall clock per goal, and false-completion rate.

**No measured run has been published yet.** The lane, its corpus, and its
offline pilot are in place; this section carries the table once a run exists
whose records the repository can point at. Reproduction command and the full
claim boundary: [`benchmarks/product-ab/v1/README.md`](benchmarks/product-ab/v1/README.md).

<br>

## Documentation

- [Documentation map](docs/README.md)
- [Installation and updates](docs/INSTALLATION.md)
- [Product direction and boundaries](docs/DIRECTION.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Capability manifests](docs/CAPABILITIES.md)
- [Workflow reference](docs/WORKFLOWS.md)
- [Roles](docs/ROLES.md)
- [Application cases](docs/APPLICATION_CASES.md)
- [Model routing, fan-out contracts, and request scoring](docs/FANOUT.md)
- [Fanout executor evidence: sessions, failure diagnostics, capacity (agent/operator reference)](docs/FANOUT-EXECUTOR-EVIDENCE.md)
- [Agent board and native Kanban coordination (agent/operator reference)](docs/AGENT-BOARD.md)
- [Per-model calibration map](MODEL_OPTI.md)
- [Evidence rules and capability impact](docs/CAPABILITY_IMPACT.md)
- [Long-term memory model](docs/MEMORY.md)
- [Processing a very large PDF with Hermes](docs/LONG-DOCUMENT-READING.md)
- [Live model benchmark and measured results](benchmarks/live-model-tools/v1/README.md)
- [Release and development](docs/RELEASE.md)

<br>

## Development

For a source checkout:

```sh
PYTHONPATH=tests uv run python -m unittest discover -s tests -v
uv run python -m compileall -q src tests
uv run python -m omh.cli docs workflows --check
git diff --check
```

OMH is developed in the open as part of
[Team Art & Engineering](https://rlaope.github.io/artengine-lab/). Follow
[@rlaope](https://github.com/rlaope) for project updates.
## Contributors

Thanks to everyone who has contributed to oh-my-hermes.

<a href="https://github.com/rlaope/oh-my-hermes/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=rlaope/oh-my-hermes&max=100&columns=10" alt="oh-my-hermes contributors" />
</a>
