oh-my-super-agent

Oh My Super Agent (OMS) is an experimental, skill-first harness that runs a durable Claude Code and Codex campaign from one natural-language goal.

An operator starts OMS, supplies one goal, and keeps the tmux client attached while subscription-backed roles run. OMS opens an interactive, read-only Claude conductor; the conductor advances a bounded campaign loop without asking the operator to route each step. Workers edit code in isolated Git worktrees. Durable state and evidence live under the repository's untracked .oms/runtime-v2/ directory, so a restarted session can recover from the journal instead of relying on model context.

OMS is not a daemon or a general workflow framework. It has no automatic merge surface and does not configure or require GitHub branch protection.

Quick start

Requirements:

• Node.js 20 or newer and npm
• git and tmux
• Claude Code CLI logged into a supported subscription
• Codex CLI logged into a supported ChatGPT subscription
• GitHub CLI (gh) for GitHub queue and draft-PR delivery
• Linux with bubblewrap for protected verification
• Gitleaks 8.30.1 for repository-backed delivery checks

Install OMS globally, enter the Git repository you want it to work on, and run it:

npm install --global oh-my-super-agent
cd /path/to/your/repository
oms

Bare oms performs the idempotent first-run setup, refreshes OMS-owned skills, starts or attaches the tmux session named oms, and opens the interactive Claude conductor. There is no separate setup command in the public interface.

The conductor asks:

What goal should OMS work on?

Answer in normal language. The conductor cannot read or modify repository files itself; it has only narrow typed OMS capabilities for accepting the goal, reading status, stopping, and advancing the campaign. It delegates code changes to workers.

Do not detach while subscription-backed work is active. Detaching the final tmux client terminates the live OMS session so provider work cannot silently continue unattended. Journal state and worktrees remain preserved; run oms again from the same repository to repair the session and resume under operator attendance.

Public commands

OMS intentionally exposes four human commands:

| Command | Purpose | | --- | --- | | oms | Set up or repair OMS, then start or attach the interactive conductor | | oms status | Show the goal, task activity and health, typed events, blocks, watchdog, and terminal status | | oms doctor | Run offline local dependency and capability checks | | oms stop | Stop the campaign terminally and non-destructively |

Operational details such as worker launch, result processing, event polling, and recovery are agent-owned internals. Humans do not need to copy state roots, run identifiers, task identifiers, or lower-level routing commands.

The campaign loop

OMS is a real closed-loop ticket controller, but it is not an infinite autoresearch optimizer. Autoresearch repeatedly mutates one experiment and keeps or discards it against one scalar metric until a human interrupts it. OMS advances each admitted ticket through durable workflow gates and stops when the ticket is done, blocked after three attempts, needs human attention, reaches the campaign deadline, is stopped by the operator, or the admitted queue is empty.

The conductor does not manually pick tasks, models, or result transitions. After goal acceptance it invokes one factory-bound CampaignLoop:

goal
  -> fresh cross-engine advice
  -> stage inert worker placeholder in an isolated worktree
  -> durably bind the exact pane and physical nonce
  -> activate the interactive worker
  -> deterministic protected verification
  -> fresh opposite-engine grade
  -> pass: stop the exact worker, mark task done, continue or complete
  -> fail: stop the exact worker, reflect, then retry or block

Deterministic verification has the final vote. A grader may explain a result, but it cannot override a failed deterministic check.

Each loop call performs only a bounded number of immediate durable steps. It then stops at one of these boundaries:

• an external wait, such as a working worker, provider result, quota reset, or GitHub update;
• a terminal task or campaign result;
• a condition that needs human attention;
• the internal step limit, after which the conductor safely advances again from journal state.

A failed ticket may be retried at most three times. Failure evidence, opposite-engine grade, reflection, and retry lineage are recorded before the next attempt. After the final failed attempt the ticket becomes blocked.

Task activity is explicit: idle, working, done, or blocked. Health is a separate signal: healthy, parked, stalled, or stopped. oms status reports these durable states rather than guessing from pane text.

The default campaign deadline is 24 wall-clock hours. A single-goal campaign completes when its canonical task is done. A GitHub queue campaign completes only after the queue is drained and the required consecutive successful empty polls have been recorded.

Events and recovery

Normal progress is event-driven:

• Provider hooks produce immediate typed session, activity, and completion events. Claude quota hooks are immediate; Codex quota recovery uses an exact pane-bound banner observer because Codex exposes no native quota hook.
• GitHub synchronization is configurable and defaults to every 60 seconds. It produces deduplicated typed issue, pull-request, and check events using durable identities and watermarks.
• Typed wakes cause the conductor to re-enter the bounded campaign loop. Wake claims are consumed in journal order and repeated delivery is idempotent.
• The watchdog runs every 15 minutes for recovery only. It may detect or recover dead or stalled ownership, but it cannot route tickets or perform ordinary campaign progress.

The observer and watchdog run as local companion processes inside the human-started tmux session. Their individual checks are bounded fixed operations and they never own routing, so they do not form a standalone OMS routing daemon. Skills supply conductor and worker judgment; TypeScript owns validation, journal transitions, idempotency, verification authority, and side-effect boundaries.

Roles and models

The default roster is subscription-backed and attended-only:

• Conductor: Claude Opus, interactive, persistent, and read-only
• Advisor: GPT-5.6 Sol through a fresh Codex exec
• Short-ticket executor: Claude Sonnet in an interactive worktree pane
• Long-ticket executor: GPT-5.6 Sol through native Codex Goal mode
• Grader: the opposite engine from the executor; the default Codex grader is GPT-5.6 Terra
• Reflection: fresh Claude Opus

Role models and Codex reasoning effort are user configuration. The first bare oms creates the user-level configuration at ~/.oms/config/oms-config.json; later repositories reuse it. Credit-billed models are disabled by default, and every shipped subscription role has unattended_eligible: false.

OMS validates its seven canonical roles and every model they reference strictly. Additional role or model entries are preserved as inert user extensions and reported with a warning; they cannot become runtime roles or provider execution merely by appearing in the JSON file.

Claude is always interactive in tmux. OMS does not use claude -p or the Agent SDK for the conductor or Claude workers. Codex structured exec and native Goal mode are supported by the configured role policy.

Each Codex Goal worker receives a private OMS-owned CODEX_HOME, an explicitly untrusted project setting, disabled plugin/app surfaces, and a named permission profile. The profile grants read-only access to the sealed Codex runtime and task-scoped Git namespace, write access to the exact attempt worktree, and denies the main checkout, .oms, ambient temporary roots, and user auth. Claude/Codex provider settings, hooks, MCP configuration, and launch bindings remain in a private OMS control directory outside every worker-writable path.

Delivery boundaries

Repository-backed work may pass through a non-force branch push and draft pull request after protected verification and the opposite-engine grade. Delivery stops for human review:

• no automatic merge;
• no ready-for-review mutation;
• no force push;
• no tag, release, or package publication;
• no branch-protection read or write requirement.

Branch protection remains entirely outside OMS. Repository administrators may configure it independently, but OMS does not change it.

Current evidence and limits

The repository has offline integration coverage for the real campaign journal, linked Git worktrees, protected verification, opposite-engine grading, reflection, retry lineage, typed wakes, restart recovery, and terminal campaign transitions. Its React Focus Board canary deliberately fails one deterministic check on attempt one, reconstructs services, and completes the same synthetic task on attempt two.

That proves loop mechanics, not permission or evidence for unattended provider use. It is also not proof of a live 24-hour run: the project does not claim a fresh elapsed 24-hour campaign using real provider sessions and GitHub delivery. Until such evidence is produced and reviewed, OMS should be treated as experimental and every merge remains a human decision.

Development

For contributors working from a source checkout:

npm ci
npm run verify

The npm package exposes CLI binaries only; it has no programmatic package export. See the v0.2 architecture decision, architecture, and security model for the detailed authority and threat model.