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.
• 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

Quick start

# Set your API key
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

# 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

Commands

| Command | Description | |---|---| | omocode (no args) | Interactive guided session via @clack/prompts | | omocode run --goal "..." | Run agent cycle: LLM → propose → confirm → execute → ledger | | 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 |

What this does NOT do (yet)

• No TUI (SolidJS terminal UI like Gajae-Code) — uses @clack/prompts interactive mode instead.
• No tmux-backed sessions or worktree isolation.
• No native binaries or NAPI bindings.
• No Python kernel / research mode (rlm).
• No notification daemon (Telegram/Discord).
• No true parallel subagents (team is a single LLM review pass, not real parallel workers).

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.