Oh My OpenAgent (previously “oh-my-opencode”) is a powerful, opinionated agent harness that turns multiple LLMs and tools into a coordinated, reliable developer team. This guide walks you through a safe, pragmatic setup so you can try the harness this weekend and understand the immediate productivity wins.
Repository (source): https://github.com/code-yeongyu/oh-my-openagent
Quick install guide (raw): https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
What you’ll get after setup (summary)
- A single command orchestration: ultrawork / ulw — kick off multi-agent, multi-model workflows.
- Parallel background agents (Sisyphus, Hephaestus, Prometheus, etc.) that plan, execute, and loop until a goal is complete.
- Robust edit tooling (hash-anchored edits) that dramatically reduces stale-line and patch corruption errors.
- Built-in LSP/AST-aware refactoring, tmux integration, and MCPs (scoped retrieval services).
- Model-agnostic orchestration with configurable fallbacks so you can mix cloud and open models.
Prerequisites
- Git installed and a shell you’re comfortable with (bash, zsh, or similar).
- Node.js or Bun available — the repo includes TypeScript and Bun files; follow the repo installation guide if you prefer Bun.
- Accounts/keys for any cloud models you want to use (if you plan to use hosted models). See the repo docs for provider configuration.
- A sandbox or non-production environment to test initially (strongly recommended).
1) Clone the repo and read the install guide
Clone the official repository and inspect the install guide before running anything:
git clone https://github.com/code-yeongyu/oh-my-openagent.git
cd oh-my-openagent
# Read the guide directly (recommended)
curl -s https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md | less
Reading the guide ensures you follow any repo-specific instructions (model credential locations, plugin installation details, or platform-specific advice).
2) Disable telemetry while testing (optional but recommended)
Oh My OpenAgent enables anonymous telemetry by default. If you want to avoid telemetry while you try things locally, set the env var before installation:
export OMO_SEND_ANONYMOUS_TELEMETRY=0
# or
export OMO_DISABLE_POSTHOG=1
These env vars were documented in the repo and will prevent PostHog-style anonymous events during your trial.
3) Install dependencies
The project includes Bun artifacts but also works with Node-based flows. Follow the repo’s recommended install path. A common pattern:
- With Bun (recommended if you have it):
# from project root
bun install
# run any provided postinstall steps
bunx oh-my-opencode doctor # runs the repo’s built-in diagnostics
- With npm/yarn (if you prefer):
npm install
# or
yarn install
# then run the repo diagnose script (if available)
# check the installation guide for exact npm scripts
If the repo exposes a published package/binary, you can also install that globally (see the repo docs). The README advertises a one-word UX (ultrawork / ulw) once installed.
4) Configure providers and models (follow repo docs)
Oh My OpenAgent is model-agnostic — it orchestrates models by category and maps categories to providers. The project supports multiple models out of the box. To configure credentials and model fallbacks:
- Edit your OpenCode config file (per the repo):
- Global: ~/.config/opencode/opencode.json (or .jsonc)
- Project: .opencode/opencode.json (or .jsonc)
The repo includes examples and an opencode.json schema; follow the installation guide to add provider keys and define fallback arrays for ultrawork categories (e.g., ultrabrain, quick, deep). The harness will handle routing automatically once keys are provided.
Important: don’t paste keys into public repos — keep them in environment variables or local config.
5) Run the quick health check
Once installed and configured, run the project’s built-in diagnostics to verify the environment:
bunx oh-my-opencode doctor
# or, if the binary is installed globally
oh-my-opencode doctor
This will confirm plugin registration, model connectivity, and minimal environment sanity checks. If the repo exposes opencode –version you can verify plugin removal/installs later.
6) Try ultrawork — a safe smoke test
Run a small, safe test to see agents plan and act. For example, in a sandbox project directory run:
# from your target repo (or a toy project)
ultrawork –dry-run “refactor and lint the repository’s JavaScript files”
Use –dry-run if available, or run the planner-only mode (Prometheus) to see the plan without executing edits. The harness has an interview/planning mode that asks clarifying questions before executing — let Prometheus run so you can observe planning quality.
7) Inspect AGENTS.md and the hash-anchored edits
Run /init-deep or the repo’s equivalent initialization to generate AGENTS.md files. These hierarchical files supply context to background agents and keep context windows lean.
Open a small file and watch how the harness tags lines with LINE#ID hashes. That’s the hash-anchored edit tool: it gives every edit a stable identifier so agents won’t produce stale-line patches.
8) Iterate: run an actual small task
Pick a safe, small task (fix an eslint rule, rename a function) and let the agents attempt it. Review changes, run tests locally, and then commit if the results are acceptable. The usual workflow:
- Let Prometheus create a plan.
- Let Sisyphus/Hephaestus do the edits.
- Inspect the diff and run your test suite.
- Revoke or refine if needed.
Why Oh My OpenAgent will help you (practical benefits)
- Faster feature prototyping: multi-agent parallelism means planning, research, implementation, and tests can run simultaneously.
- Higher edit reliability: hash-anchored edits reduce edit corruption and make agent-driven refactors safer.
- Lower cognitive load: Prometheus’ interview-mode forces requirements refining before code changes begin — fewer wasted iterations.
- Multi-model routing: you get the best model for each job automatically (e.g., fast models for trivial edits, strong models for architecture decisions).
- Reproducible developer environment: AGENTS.md contextualization and ultrawork macros give consistent, repeatable agent behavior across machines.
Safety & final tips
- Start in a throwaway repo or branch. Observe and validate every change.
- Disable telemetry if you’re testing in a sensitive environment (see env vars above).
- Review any external MCP (websearch, GitHub search) defaults to ensure no unwanted data exfiltration.
- If you plan to use paid cloud models, monitor token usage and set budget limits on your account.
If you want, I can:
- Paste a minimal ~/.config/opencode/opencode.json example (skeleton) that follows the repo’s documented shape (no provider keys — placeholders only).
- Create a safe, step-by-step “first task” script you can run in a sandbox repo to see ultrawork in action.
Which would you prefer?