oh-my-agents

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2026 License: MIT

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 together cost ~275 tokens of resident surface (name + description), versus OMC's 15-20k, about 2%, 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 default path is plain oma commands plus markdown, so Claude Code and Codex follow the same contract. Host-only accelerations (Claude Code's structured option picker, subagents, plan mode) are clearly-marked optional branches, never the default.
  • One asset model, two agents. Assets live in canonical ~/.agents/ and are projected by symlink into both ~/.claude/ and ~/.codex/. Install once, available to both. (Hook assets are placed canonically only — oma never writes your host config; you wire hooks into settings.json/hooks.json by hand, see docs/relay-v2-protocol.md §12.4.)

This is CLI + skills, deliberately not a Claude Code plugin: a plugin is a Claude-Code-only concept, and the whole point is to stay neutral and lightweight.

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. oma counts rounds and judges the stop; the agent runs the verifier itself and reports the exit code.
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.

The skills require the oma CLI. They are deliberately not standalone prompts: every mechanical step (state, scoring gates, sequence-numbered ledger operations) shells out to oma, and a skill invoked without the binary on PATH stops at its first command. Install the CLI first, then the skills. 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

By default the installer downloads the prebuilt binary for the latest GitHub release, verifies its SHA-256 against the release checksums.txt (the same fail-closed contract self-update uses), writes oma to ${OMA_INSTALL_BIN_DIR:-$HOME/.local/bin}, and prints a PATH hint if that directory is not already on PATH — no Go toolchain required. Useful overrides: OMA_INSTALL_VERSION=v0.1.0 pins a tag, OMA_INSTALL_BIN_DIR=/some/bin changes the destination, and OMA_INSTALL_FROM_SOURCE=1 forces a source build. If no prebuilt binary matches your platform (or no release can be resolved), the installer falls back to a source build (needs git + go). On Windows, run the same command from Git Bash; it installs oma.exe, and Git Bash can invoke it as oma once that directory is on PATH.

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.

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: the oma CLI must be installed and on PATH (see above) — the skills drive it for every mechanical step and do not work without it.

# With oma, from a checkout of this repository
./oma asset install --from assets deep-interview ralph autopilot pair-delivery

# Or directly through the npx skills installer
npx skills add sean2077/oh-my-agents -g --agent claude-code codex

Wire the statusline and hooks (optional)

oma never writes your host config. The relay 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 "which pair / whose turn" line) — add to ~/.claude/settings.json:

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

Already have a custom statusline script? Don't replace it — call oma relay statusline --json from inside it and gate on .bound (so non-pair windows stay clean). See ~/.claude/statusline-command.sh in this repo's author's setup for the pattern.

Auto-continue hooks (drive the pair-delivery loop without manual nudging) — add to the top-level hooks key in ~/.claude/settings.json. 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)$, and run /hooks once to trust the new entries. Full field reference (matchers, timeouts, guard rationale) is in docs/relay-v2-protocol.md §12.4.

Quickstart

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

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

Command surface

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

  • oma asset: install / list / remove / rollback assets; canonical placement plus per-agent projection.
  • 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, terminal-state judgment. oma never runs your verifier.
  • oma relay: the v2 pair ledger: append-only artifacts, atomic publish with integrity sidecars, sequence reservation, and wait-based handoff.
  • 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 nothing; 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              subagent
  hooks/<name>/                 hook (manifest + fragment; canonical-only, wire by hand)
  prompts/<name>.md             prompt
        |  projection (symlink; hooks are canonical-only — never written to host config)
        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.
  • 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 symlink-escape checks, 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/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

go build ./...
go test ./...           # full suite
gofmt -l .              # must be empty
go vet ./...

CI runs the test matrix, gofmt/vet/build, and golangci-lint on every push and PR. The release workflow cross-compiles six platforms with a checksums manifest and a tag-version gate.

This project is itself built through its own pair-delivery workflow: every slice is cross-reviewed by a second agent over the oma relay ledger before it lands. The skill that describes that process is the one we used to build it.

License

MIT © 2026 sean2077

Directories

Path Synopsis
cmd
oma command
internal
agentdir
Package agentdir owns the per-agent directory conventions: where each asset type projects for claude and codex (docs/adapter-conformance.md §2).
Package agentdir owns the per-agent directory conventions: where each asset type projects for claude and codex (docs/adapter-conformance.md §2).
asset
Package asset implements the content-asset domain: manifest parsing, canonical placement, per-agent projection, backup and verification (docs/adapter-conformance.md).
Package asset implements the content-asset domain: manifest parsing, canonical placement, per-agent projection, backup and verification (docs/adapter-conformance.md).
budget
Package budget implements the resident-context measurement gate (docs/adapter-conformance.md §5): a deterministic, pinned approximation of the always-loaded prompt surface created by installed assets.
Package budget implements the resident-context measurement gate (docs/adapter-conformance.md §5): a deterministic, pinned approximation of the always-loaded prompt surface created by installed assets.
checks
Package checks implements oma doctor's check registry (docs/command-tree.md §4): each check inspects one aspect of the installation and reports findings at ok/warn/fail levels.
Package checks implements oma doctor's check registry (docs/command-tree.md §4): each check inspects one aspect of the installation and reports findings at ok/warn/fail levels.
cli
Package cli wires the oma command tree (docs/command-tree.md).
Package cli wires the oma command tree (docs/command-tree.md).
config
Package config implements the user-intent configuration layer (docs/config.md).
Package config implements the user-intent configuration layer (docs/config.md).
interview
Package interview implements the solidified surface of the Socratic clarification workflow (docs/workflows.md §1): deterministic scoring math, threshold gating and state persistence live HERE; question generation, dimension assessment and ontology extraction stay with the agent, which feeds results in via `oma interview score --input`.
Package interview implements the solidified surface of the Socratic clarification workflow (docs/workflows.md §1): deterministic scoring math, threshold gating and state persistence live HERE; question generation, dimension assessment and ontology extraction stay with the agent, which feeds results in via `oma interview score --input`.
ralph
Package ralph implements the solidified surface of the persistent improvement loop (docs/workflows.md §2): counting, stop-judgment and history live HERE; doing the work and RUNNING the verifier stay with the agent — oma never executes verifier commands (security contract), the agent reports the exit code via `oma ralph check`.
Package ralph implements the solidified surface of the persistent improvement loop (docs/workflows.md §2): counting, stop-judgment and history live HERE; doing the work and RUNNING the verifier stay with the agent — oma never executes verifier commands (security contract), the agent reports the exit code via `oma ralph check`.
relay
Package relay implements the oma relay v2 pair ledger (docs/relay-v2-protocol.md): append-only artifacts with sidecar integrity markers, O_EXCL sequence reservation, draft-as-durable- publish-intent transactions, heartbeat liveness and pair bindings.
Package relay implements the oma relay v2 pair ledger (docs/relay-v2-protocol.md): append-only artifacts with sidecar integrity markers, O_EXCL sequence reservation, draft-as-durable- publish-intent transactions, heartbeat liveness and pair bindings.
state
Package state implements oma's generic project-level key/value store (docs/command-tree.md §3, docs/schemas.md §3).
Package state implements oma's generic project-level key/value store (docs/command-tree.md §3, docs/schemas.md §3).
update
Package update implements oma self-update with the docs/security-contract.md §5 trust chain: the update source is pinned to this repository's GitHub Releases at compile time, asset names must match the release naming contract, every download is verified against the release's checksums.txt, replacement is atomic with an .old backup and a post-replace self-check that auto-rolls-back, and an unwritable target degrades to printed manual instructions (never sudo).
Package update implements oma self-update with the docs/security-contract.md §5 trust chain: the update source is pinned to this repository's GitHub Releases at compile time, asset names must match the release naming contract, every download is verified against the release's checksums.txt, replacement is atomic with an .old backup and a post-replace self-check that auto-rolls-back, and an unwritable target degrades to printed manual instructions (never sudo).
version
Package version holds build metadata, the schema version registry and pinned algorithm versions.
Package version holds build metadata, the schema version registry and pinned algorithm versions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL