omocode

A terminal coding-agent harness with real LLM calls, approved shell execution, and durable session ledgers. Inspired by Gajae-Code's workflow surface (deep-interview → ralplan → ultragoal → team), built on the orchestration philosophy of oh-my-openagent.

What this is

omocode is a standalone terminal CLI that:

• Talks to real LLMs — Anthropic Claude, OpenAI GPT, Ollama, OpenRouter, LM Studio, or any OpenAI-compatible endpoint. BYO API key.
• Executes shell commands — proposes actions from the LLM, asks for your confirmation, then runs them. --yes skips prompts. --dry-run previews without executing.
• Runs in isolated git worktrees — --worktree <name> creates or reuses .omocode/worktrees/<name> so agent commands and session ledgers stay outside your main checkout.
• Runs in background — --background <name> starts the agent in a detached process that survives terminal close. Monitor with omocode sessions and omocode attach.
• Runs parallel agents — --parallel spawns 3 agents (architect, planner, critic) in separate worktrees concurrently.
• Tracks everything in a durable ledger — every session creates .omocode/sessions/<id>/ with ledger.jsonl, plan.md, and an evidence/ directory.
• Exposes the OMO workflow — four skills (deep-interview, ralplan, ultragoal, team) that map to Gajae-Code's stages, plus the six-stage OMO workflow surface.

Install

Requires Node.js 18+.

npm install -g omocode-agent

Quick start

# Configure your provider interactively
omocode init

# Or set API key manually
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

# Run a goal
omocode run --goal "list all TypeScript files and count lines"

# Interactive mode (just run omocode with no args)
omocode

# Preview without executing
omocode run --goal "fix the failing tests" --dry-run

# Run in an isolated git worktree
omocode run --goal "fix the failing tests" --worktree fix-tests

# Run in background (detached process)
omocode run --goal "fix the failing tests" --background mysession
omocode sessions          # list active sessions
omocode attach --name mysession   # stream live output
omocode stop --name mysession     # stop session

# Run parallel agents (3 roles: architect, planner, critic)
omocode run --goal "refactor auth module" --parallel

# Use a specific skill/stage
omocode run --goal "add a login page" --skill deep-interview
omocode run --goal "add a login page" --skill ralplan
omocode run --goal "add a login page" --skill ultragoal
omocode run --goal "add a login page" --skill team

# Use Ollama (local, no API key needed)
omocode run --goal "explain this repo" --skill deep-interview
# with .omocode/config.json: {"provider":"openai-compatible","model":"llama3","baseUrl":"http://localhost:11434"}

Configuration

Create .omocode/config.json in your repo root:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "apiKey": "sk-ant-..."
}

Or use environment variables:

| Env var | Purpose | |---|---| | ANTHROPIC_API_KEY | Anthropic Claude API key | | OPENAI_API_KEY | OpenAI / OpenRouter / compatible API key | | OMOCODE_PROVIDER | anthropic or openai-compatible | | OMOCODE_MODEL | Model name (e.g. claude-sonnet-4-20250514, gpt-4o, llama3) | | OMOCODE_BASE_URL | Custom base URL for OpenAI-compatible servers | | ANTHROPIC_BASE_URL | Override Anthropic API base URL | | OPENAI_BASE_URL | Override OpenAI API base URL |

Provider auto-detection: if ANTHROPIC_API_KEY is set, defaults to Anthropic. Otherwise defaults to OpenAI-compatible.

Workflow skills

omocode ships four OMO-flavored skills, mirroring Gajae-Code's surface:

| Skill | Stage | What it does | |---|---|---| | deep-interview | Intake | Clarifies ambiguous requirements before planning. | | ralplan | Plan | Produces options, risks, acceptance criteria, verification plan. | | ultragoal | Execute | Proposes shell commands to achieve the goal, asks confirmation, runs them. | | team | Verify | Multi-perspective review pass (architect, planner, critic). |

Session state

Every omocode run creates a durable session:

.omocode/sessions/20260703-120000/
  ledger.jsonl          ← append-only audit trail (JSONL)
  plan.md               ← human-readable goal brief
  evidence/
    ultragoal-response.txt   ← raw LLM response

With --worktree <name>, omocode first creates or reuses an isolated git worktree at:

.omocode/worktrees/<name>/

The LLM prompt, proposed shell commands, and session ledger all use that worktree as the active working directory. This keeps generated files, command execution, and .omocode/sessions/<id>/ state out of the main checkout while preserving the same OMO workflow surface.

Commands

| Command | Description | |---|---| | omocode init | Interactive config wizard — creates .omocode/config.json | | omocode (no args) | Interactive guided session via @clack/prompts | | omocode run --goal "..." | Run agent cycle: LLM → propose → confirm → execute → ledger | | omocode run --goal "..." --worktree <name> | Run the agent inside .omocode/worktrees/<name> | | omocode run --goal "..." --background <name> | Start agent in a detached background process | | omocode run --goal "..." --parallel | Spawn 3 agents (architect, planner, critic) concurrently | | omocode sessions [--json] | List all sessions (running/completed/failed) | | omocode attach --name <session> | Stream live output from a background session | | omocode stop --name <session> | Stop a running session | | omocode inspect | Show repo context (git, scripts, manifests) | | omocode plan | Turn a goal into an implementation brief | | omocode workflow | Show OMO 6-stage workflow surface | | omocode smoke-test | Self-verify: cli-parse / inspect / plan / workflow / apply-preview safety | | omocode apply-preview | Preview a command without executing |

Background sessions

omocode run --goal "..." --background mysession starts the agent in a detached process. The session metadata is stored at .omocode/sessions/mysession/meta.json with status tracking (starting → running → completed/failed/stopped). Logs are written to stdout.log and stderr.log in the same directory.

omocode run --goal "fix tests" --background fix-1   # start
omocode sessions                                     # list
omocode attach --name fix-1                          # stream output
omocode stop --name fix-1                            # stop

Parallel agents

omocode run --goal "..." --parallel spawns 3 background agents in separate worktrees:

| Role | Worktree | Focus | |---|---|---| | Architect | .omocode/worktrees/team-architect/ | Structural analysis | | Planner | .omocode/worktrees/team-planner/ | Implementation plan | | Critic | .omocode/worktrees/team-critic/ | Risk identification |

Each runs independently as a background session. Monitor with omocode sessions.

What this does NOT do (yet)

• No TUI dashboard — @opentui/solid is installed and a rendering PoC exists at src/tui/poc.tsx, but it is not connected to the CLI yet. The interactive mode uses @clack/prompts.
• No tmux-backed sessions.
• No native binaries or NAPI bindings.
• No Python kernel / research mode (rlm).
• No notification daemon (Telegram/Discord).
• Parallel agents do not yet aggregate/synthesize results into a unified output — each produces independent output in its own worktree.

These are future work. This is a real, runnable LLM agent harness — not a metadata surface.

Development

bun install
bun test
bun run typecheck
bun run lint
bun run build
node ./dist/cli.js smoke-test --path . --json

License

MIT — see LICENSE.