OMA

OMA is an agentic coding system for terminal-first implementation workflows. It ships as a native CLI/TUI runtime with an embedded agent hierarchy, durable .oma/ workspace state, and GitHub Releases-based binary distribution.

Install

Stable lane (default)

curl -fsSL https://raw.githubusercontent.com/vaur94/oma/main/install.sh | sh

For a reproducible install, pin an explicit release:

curl -fsSL https://raw.githubusercontent.com/vaur94/oma/main/install.sh | sh -s -- --version v2.1.2

Alpha lane

curl -fsSL https://raw.githubusercontent.com/vaur94/oma/main/install.sh | sh -s -- --channel alpha

You can also pin an explicit prerelease tag:

curl -fsSL https://raw.githubusercontent.com/vaur94/oma/main/install.sh | sh -s -- --channel alpha --version v2.1.2-alpha.3

If you want the latest alpha automatically, keep python3 available. Otherwise, pin --version.

install.sh installs from GitHub Releases assets only.

Linux x64 packages (.deb / .rpm)

For Linux x64, OMA ships .deb and .rpm files as GitHub Releases assets.

# .deb (Debian/Ubuntu)
sudo dpkg -i oma_*.deb

# .rpm (Fedora/RHEL)
sudo rpm -i oma_*.rpm

Manual asset download

Pre-built Linux/macOS binaries are attached on the Releases page.

Upgrade

oma upgrade
oma upgrade --channel alpha
oma upgrade --check

• default channel: stable
• optional prerelease channel: alpha

Source build

bun install
bun run build

For local source execution, run bun run apps/oma/src/main.ts.

---

Quick start

1. Authenticate

Set at least one provider API key:

export ANTHROPIC_API_KEY=sk-...
# or
export OPENAI_API_KEY=sk-...
# or
export OPENROUTER_API_KEY=sk-...

OpenAI OAuth (ChatGPT account):

For OpenAI, you can also use OAuth with your ChatGPT account instead of an API key:

# Web login (opens browser)
oma auth login openai --web

# Device flow (for headless environments)
oma auth login openai --device

After setting the preference, authenticate with the Codex CLI:

codex login
codex login --device-auth

2. Run

Launch the interactive TUI:

oma

Or run a one-shot command:

oma plan "add a multiply function to src/math.ts"

First run creates .oma/ in the current working directory.

3. Continue a session

When a one-shot command starts a new conversation, OMA prints the session ID:

[OMA] Session: <session-id>

Continue with:

oma --session <session-id> implement
oma --session <session-id> validate

---

Release model

• dev is the alpha prerelease lane
• main is the stable release lane
• package.json.version is the release base source of truth
• each push to dev can produce v<base>-alpha.<n>
• each push to main can produce v<base>
• after a stable release, automation bumps dev to the next patch base

Useful local checks:

• bun run release:flow status — show current branch/tag/version state
• bun run release:flow status --refresh-refs — fetch origin/main, origin/dev, and tags before reporting
• bun run release:flow check --lane alpha — validate alpha readiness
• bun run release:flow check --lane stable — validate stable readiness
• bun run release:flow check --lane both --json — script-friendly readiness report

---

Commands

Command	Description
/plan	Create an implementation-ready plan
/implement	Execute an implementation-ready task
/validate	Run the smallest sufficient validation scope
/roadmap	Create or revise a roadmap-scale plan
/roadmap-status	Summarize current roadmap progress
/roadmap-continue	Continue roadmap execution from current phase

Additional commands

Command	Description
/brainstorm	Structured ideation and contradiction finding
/prompt	Turn brainstorm output into a refined prompt artifact
/loop	Execute roadmap items through plan → implement → validate
/review	Findings-first review of plan, diff, or workspace
/status	Summarize current repo, plan, and validation status
/analyze	Repository, architecture, or target-area investigation

Run oma --help for the full command reference.

---

Configuration

OMA reads JSONC config from:

1. ~/.config/oma/oma.jsonc (global)
2. .oma/oma.jsonc (project-local, overrides global)

Key sections:

• agent — per-agent model, temperature, fallback
• workflow.hookProfile — off, standard, or strict
• workflow.orchestration — max parallel agents, timeout
• github — GitHub integration settings
• mcp.context7 — Context7 MCP endpoint metadata
• disabledTools — global and per-agent tool restrictions
• commandSurface — dangerous command policy

Minimal config:

{
  "$schema": "https://oma.local/schemas/oma.schema.json",
  "version": 2,
  "workflow": {
    "hookProfile": "standard",
  },
}

Full reference: docs/config.md

---

Storage

OMA separates project artifacts from runtime state:

Repo-local .oma/ — project-local artifacts and config:

• .oma/oma.jsonc — project config (overrides global)
• .oma/plans/ — plans and active plan state
• .oma/roadmap/ — roadmap and roadmap items
• .oma/prompts/ — prompt artifacts

XDG state — runtime/app-owned per-project state:

• $XDG_STATE_HOME/oma/projects/<project-id>/sessions/ (fallback ~/.local/state/oma/projects/<project-id>/sessions/)
• $XDG_STATE_HOME/oma/projects/<project-id>/tasks/
• $XDG_STATE_HOME/oma/projects/<project-id>/memory/

---

Development

bun run release:audit
bun run build
bun run lint
bun run typecheck
bun run test

Live E2E (requires provider credentials):

OMA_E2E=true bun test ./test/e2e/oma-workflow.e2e.ts

---

Documentation

• Getting started
• Architecture
• Commands
• Configuration
• Migration v1 → v2
• Release evidence matrix

Schema and template:

• schemas/oma.schema.json
• templates/oma.jsonc

---

Repository structure

src/                      # Agent, tool, and command definitions
packages/
  kernel/                 # Runtime kernel (session, conversation, routing)
  cli/                    # Shared CLI helpers
  tui/                    # Ink-based TUI surface
apps/oma/src/main.ts      # Native CLI entrypoint

---

Status

OMA is on the clean-break dev/main release model. See RELEASE.md for release operations and docs/adr/ for architecture decision history.