oh-my-agents

README

oh-my-agents

A single Go binary (oma) plus a small set of curated, agent-neutral skills that form a lightweight base layer for everyday AI coding workflows across both Claude Code and Codex.

oma solidifies the mechanical parts of a workflow (asset install/projection, state, scoring gates, loop stop-judgment, a cross-review pair ledger) into a deterministic, fail-closed CLI. The skills describe only the non-mechanical parts: the judgment. They call oma commands for everything that should be counted, validated, or persisted.

Why

The trigger for this project was a concrete pain point in oh-my-claudecode (OMC): it ships ~40 skills that are always resident in the model's context (roughly 15-20k tokens) with no per-skill disable. You pay that context tax on every turn whether or not the work needs any of those skills.

oma is the opposite bet:

• You decide what is installed. Skills are explicit assets you install and remove. Nothing is resident unless you put it there. The four core skills currently cost 169 tokens of resident surface (name + description), versus OMC's 15-20k, about 1%; the release ceiling is 400 and every asset is independently installable.
• Mechanical logic belongs in a binary, not a prompt. Sequence numbers, ambiguity math, threshold gates, stall detection, atomic file writes, and integrity checks are deterministic. They live in oma, where they are testable and fail-closed, not re-derived by the model each turn.
• Skills stay agent-neutral. A skill's complete default path is plain oma commands plus markdown, so Claude Code and Codex follow the same contract. A clearly marked capability-gated branch may proactively delegate independent bounded lanes when the current runtime exposes controlled subagent tools; genuinely host-only affordances use a separate optional marker. The shared gate and marker contracts are in docs/reference/workflows.md §0.1 and docs/reference/adapter-conformance.md §3.
• One asset model, two agents. Assets live in canonical ~/.agents/ and each supported target projection lands under ~/.claude/ or ~/.codex/ (symlink on Unix-like hosts; directory junction for skills on native Windows, with managed copy fallback). Install once, available wherever that asset type is supported. (Hook assets are placed canonically only — oma never writes your host config; you wire hooks into settings.json/hooks.json by hand, see docs/reference/relay-v2-protocol.md §12.4.)

This is CLI + agent-neutral skills, deliberately not a Claude-only workflow. The minimal .claude-plugin/plugin.json is installer compatibility metadata: npx skills uses it to group the installed skills under Oh My Agents, while the canonical asset model and runtime contract remain shared by Claude Code and Codex.

What ships

Four core workflow skills (the "core4"):

Skill	What it does
deep-interview	Socratic requirements crystallization with deterministic ambiguity gating. Turns a vague idea into a pending approval spec, never straight to code.
ralph	A persistent improvement loop that iterates until a verifier passes — or, under the score_improvement keep-policy, until a scored evaluator plateaus. oma counts rounds and judges the stop; the agent runs the verifier itself and reports the exit code (and score).
autopilot	End-to-end autonomous delivery (clarify -> plan -> implement -> verify -> deliver) with resumable phase state in oma state. Pure markdown; no dedicated command group.
pair-delivery	Cross-agent delivery over the oma relay ledger (plan -> review -> implement -> review -> decision) with an explicit lead and rule-based role-swap escalation.

On-demand skills (install only when a task needs them — zero resident cost otherwise):

Skill	What it does
trace	Adversarial root-cause investigation: competing hypotheses, evidence-strength ranking, self-falsification, ending at the single highest-value discriminating probe.
analyze	Read-only deep repository analysis: a ranked, confidence-tagged synthesis with file:line evidence and a strict evidence / inference / unknown split.
best-practice-research	Bounded external best-practice research with official/upstream sourcing, version/date context, and a terminal read-only handoff.
code-review	Read-only review of an existing diff under Spec compliance and Standards & quality, with file:line findings, verification, and limitations; never pair evidence.
prototype	Build one runnable, disposable artifact to answer one material design question before production work.
research-mission	Scaffold a falsifiable research/optimization mission (deterministic evaluator contract + candidate ledger) and drive it with ralph's score_improvement keep-policy.
ai-slop-cleaner	Regression-safe, deletion-first cleanup of AI code slop, gated by a green verifier.
ultraqa	Adversarial end-to-end QA as a ralph profile (hostile-scenario matrix).
skillify	Capture a repeatable workflow into a new oma skill, gated by a four-part quality test.

The full installed catalog (with lifecycle status) is oma asset catalog. oma asset audit reports resident, description/budget, and loaded-body token estimates alongside advisory intra-catalog labels; ORPHAN means no inbound asset reference, not "unused." Release tests separately fail when an active description exceeds its manifest budget.

Which workflow?

This is a documentation router, not another skill. Start from the outcome you need:

Need	Use
Turn a vague idea into an approved, durable specification	deep-interview
Drive a sufficiently concrete task end to end	autopilot
Iterate against a verifier until the stop judgment passes	ralph
Obtain independent cross-agent review when it is useful and available	pair-delivery
Explain why a bug, regression, or surprising result happened	trace
Explain a repository-wide design or behavior from local evidence	analyze
Review a bounded existing diff without editing it	code-review
Resolve current external or version-sensitive guidance	best-practice-research
Answer a material design question with a runnable throwaway artifact	prototype
Improve a measurable baseline under a deterministic evaluator	research-mission
Remove duplication or needless abstraction while preserving behavior	ai-slop-cleaner
Harden a feature against hostile and boundary scenarios	ultraqa
Turn a repeated workflow into a reusable OMA skill	skillify

Optional handoffs are best-effort; when absent, the parent workflow continues.

Install the oma CLI for mechanical workflows. Every counted, validated, or persisted step (state, scoring gates, sequence-numbered ledger operations) shells out to oma, and a skill that names an oma command stops at that command without the binary on PATH. Judgment-only on-demand skills with no CLI command — such as analyze, code-review, and prototype — can run without it. By the same principle, skill bodies carry only the core workflow; installation and platform guidance live here in the README, never in a SKILL.md.

Install the CLI

Install the latest released oma into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/sean2077/oh-my-agents/main/scripts/install.sh | bash

This downloads the prebuilt binary for the latest GitHub release, verifies its SHA-256 against the release checksums.txt, atomically installs oma into ${OMA_INSTALL_BIN_DIR:-$HOME/.local/bin}, and asserts the installed binary's version — the same fail-closed contract self-update uses, no Go toolchain required. It is fail-closed: if it cannot resolve a release, match a prebuilt asset, verify the checksum, or confirm the version, it stops with an actionable error — it never silently builds from source or from the unreleased main branch.

Useful overrides: OMA_INSTALL_VERSION=vX.Y.Z pins a specific release, OMA_INSTALL_BIN_DIR=/some/bin changes the destination, and OMA_INSTALL_FROM_SOURCE=1 opts into a source build (needs git + go). On Windows, run the same command from Git Bash (it installs oma.exe, callable as oma once the directory is on PATH), or use the native PowerShell installer:

irm https://raw.githubusercontent.com/sean2077/oh-my-agents/main/scripts/install.ps1 | iex
oma version

For a reproducible, supply-chain-pinned install, fetch the installer at a release tag (so the script itself is immutable, not the moving main) and pin the version to match:

OMA_VERSION=v1.0.0   # a tag from the releases page
curl -fsSL "https://raw.githubusercontent.com/sean2077/oh-my-agents/${OMA_VERSION}/scripts/install.sh" | OMA_INSTALL_VERSION="$OMA_VERSION" bash

You can also install from a checkout. This is the preferred self-build path: it stamps oma version with git describe, the short git commit, and -dirty when the checkout has uncommitted changes.

git clone https://github.com/sean2077/oh-my-agents
cd oh-my-agents
make install
oma version

make install uses Go's normal install location (GOBIN, or GOPATH/bin when GOBIN is unset), so make sure that directory is on PATH. Use make build instead when you want a stamped local ./oma binary in the checkout. On native Windows / Codex Desktop, PowerShell users can skip make and run:

go install -trimpath ./cmd/oma
oma version

Ensure Go's install directory (usually %USERPROFILE%\go\bin) is on PATH.

Once releases are published, oma self-update updates the binary in place from the pinned GitHub Releases (checksum-verified, atomic, with automatic rollback).

Install the skills

Prerequisite for core4 and any skill that names an oma command: install the CLI on PATH first. Commandless judgment-only skills can instead be installed directly through npx skills; using oma asset install itself naturally requires the CLI.

# Clean machine: fetch the assets bundle matching your installed oma version
# (verified against the release checksums.txt; never an unpinned fetch).
oma asset install deep-interview ralph autopilot pair-delivery

# Pin an explicit release, or install from a checkout of this repository:
oma asset install --ref v1.0.0 deep-interview ralph autopilot pair-delivery
./oma asset install --from assets deep-interview ralph autopilot pair-delivery

# Add on-demand lanes only when a task needs them:
oma asset install trace prototype code-review

# Or directly through the npx skills installer (skills only; not oma-managed)
npx skills add sean2077/oh-my-agents -g --agent claude-code codex

The compatibility manifest groups these entries under Oh My Agents in npx skills ls. If they were installed before the manifest existed, rerun the add command once so npx skills records the group in its lockfile.

For a deliberately small, versioned list of external skills that complement rather than duplicate oma, see Companion skills for oma.

Wire the statusline and hooks (optional)

oma never writes your host config. The statusline and the auto-continue hooks are opt-in: you add them to your own ~/.claude/settings.json (or ~/.codex/hooks.json) by hand. Use the absolute path to your binary (which oma) behind an existence guard so a missing binary degrades silently instead of spamming command-not-found.

Statusline (a compact one-line view of the core workflow you're currently in — relay / ralph / interview / autopilot, each tagged oma) — add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "[ -x '/ABS/PATH/oma' ] || exit 0; exec '/ABS/PATH/oma' statusline"
  }
}

oma statusline supersedes the older relay-only oma relay statusline. Already have a custom statusline script? Don't replace it — call oma statusline --active-only once from inside it so idle windows stay clean while active output keeps oma's native styling; structured consumers can use --json and gate on .active. The CLI hard-bounds the complete workflow probe internally; wrappers do not need GNU timeout. The full example requires Bash and jq, exits without output when jq is unavailable, and supports both GNU and BSD date. See docs/examples/statusline-command.sh for a complete working example.

Auto-continue hooks (drive the pair-delivery loop without manual nudging) — add to the top-level hooks key in ~/.claude/settings.json. For Codex, the Stop hook is the main self-continuation path; without a trusted Stop hook it falls back to foreground oma relay wait. The dispatcher oma relay hook <event> is pure-read and always exits 0, so it can never break your session:

{
  "hooks": {
    "SessionStart": [{ "matcher": "startup|resume|clear",
      "hooks": [{ "type": "command", "timeout": 10,
        "command": "[ -x '/ABS/PATH/oma' ] || exit 0; exec '/ABS/PATH/oma' relay hook SessionStart" }] }],
    "PreToolUse": [{ "matcher": "^(Edit|Write|MultiEdit)$",
      "hooks": [{ "type": "command", "timeout": 5,
        "command": "[ -x '/ABS/PATH/oma' ] || exit 0; exec '/ABS/PATH/oma' relay hook PreToolUse" }] }],
    "Stop": [{
      "hooks": [{ "type": "command", "timeout": 5,
        "command": "[ -x '/ABS/PATH/oma' ] || exit 0; exec '/ABS/PATH/oma' relay hook Stop" }] }]
  }
}

For Codex, put the same structure in ~/.codex/hooks.json, change the PreToolUse matcher to ^(apply_patch|Edit|Write)$, then run /hooks and confirm the oma relay hook Stop entry is trusted. Full field reference (matchers, timeouts, guard rationale) is in docs/reference/relay-v2-protocol.md §12.4. For native Windows Codex Desktop, use a PowerShell command string such as:

{
  "hooks": {
    "Stop": [{
      "hooks": [{ "type": "command", "timeout": 5,
        "command": "& 'C:\\Users\\YOU\\go\\bin\\oma.exe' relay hook Stop" }]
    }]
  }
}

Use the same PowerShell form for SessionStart and PreToolUse, changing only the final event name.

Quickstart

# See what is installed and healthy
oma asset list --installed

# Check the resident-context budget gate
oma doctor budget --agent claude --profile core4 --max-resident-tokens 400

For a full walkthrough — install → deep-interview → autopilot → ralph → pair-delivery → failure/resume → upgrade, migrate, and cleanup — see docs/tutorial.md.

Command surface

oma is organized into a few command groups (full reference: docs/reference/command-tree.md):

• oma asset: install / list / remove / rollback assets; canonical placement plus per-agent projection. catalog derives a status-lifecycle view from manifests; audit reports resident, description/budget, and body token estimates plus advisory lifecycle labels (orphan / oversized / retire).
• oma doctor: installation diagnostics and the resident-token budget gate.
• oma interview: the solidified surface of deep-interview: scoring math, threshold gate, and state. Math in the CLI; judgment in the agent.
• oma ralph: the solidified surface of the loop: round counting, stall detection (pass_only) or score-plateau detection (score_improvement), terminal-state judgment with a falsifiable receipt. oma never runs your verifier.
• oma relay: the v2 pair ledger: append-only artifacts, atomic publish with integrity sidecars, sequence reservation, wait-based handoff, and a fail-closed approve-close gate (completion receipt binding the reviewed work + a non-lead approve review + its structured review-evidence by content hash).
• oma state: generic project-level key/value state for workflows.
• oma config, oma self-update, oma version.

Conventions: --json on every query command; --dry-run is a global flag that discloses exact paths and writes no persistent target state (remote validation may use auto-cleaned temp files); exit codes are contractual (0 ok, 1 warn, 2 usage, 3 fail-closed, 4 gate failed; relay wait adds 10/11/12).

Architecture

~/.agents/                      canonical asset store (shared with the npx-skills ecosystem)
  skills/<name>/                skill body
  agents/<name>.md              installable subagent asset
  hooks/<name>/                 hook (manifest + fragment; canonical-only, wire by hand)
  prompts/<name>.md             prompt
        |  projection (symlink on Unix; junction/copy on native Windows; hooks are canonical-only)
        v
~/.claude/   ~/.codex/          per-agent directories

• Assets are described by a manifest.json (oma-asset/1) declaring type and target agents. Install places the body in ~/.agents/ and projects it to each target; a registry under ~/.config/oma/ tracks ownership so removal and rollback never touch foreign files.
• Runtime-native subagents are not installable subagent assets. Codex projection of the latter is unsupported today, while a Codex session may still expose its own runtime delegation tools; skills decide from capabilities actually present in the session.
• relay v2 is a fresh protocol (it does not read or write the legacy agent-ledger .shared/ tree) that keeps the proven principles: append-only ledger, sidecar integrity markers, fail-closed identity, platform-signal authorship. The ledger lives at <repo>/.oma/relay/.
• Security is fail-closed throughout: unmanaged-target refusal with backup on --force, trusted-root escape checks, POSIX world-writable refusal, duplicate-JSON-key rejection on host configs, mandatory secret scanning before publish, and a checksum-verified self-update trust chain. Details in docs/reference/security-contract.md.

The design documents under docs/ (protocol, command tree, workflows, adapter conformance, schemas, security, config) are the authoritative specification; the implementation follows them rather than the reverse.

Development

make agent-check        # agent-harness links + generated projections
make tooling-check      # internal/public tool inventory and syntax
go build ./...
go test ./...           # full suite
gofmt -l .              # must be empty
go vet ./...

Public installer paths live under scripts/; contributor, release, and CI automation is cataloged under tools/.

CI runs the agent-harness and tooling-manifest gates, the 3-platform test matrix with -race, gofmt/vet/build, golangci-lint, and govulncheck on every push and PR. Releases call the same pipeline as a hard gate, then promote the exact built-and-verified artifacts (no rebuild) with a checksums manifest, a strict SemVer tag gate, prerelease/latest classification checks, a build-provenance attestation, and an SBOM. The compatibility contract is STABILITY.md.

This project dogfoods pair-delivery when independent cross-agent review is useful and available. It is not a contribution prerequisite: local work may proceed through the normal verification gates when no independent peer host is available.

Project policies

• STABILITY.md — what is frozen across releases (the compatibility contract).
• SECURITY.md — supported versions and private vulnerability reporting.
• CONTRIBUTING.md — contribution gates and the optional paired-review workflow.

License

MIT © 2026 sean2077