CUELO An AI coding agent workspace and harness for omp (oh-my-pi)

CUELO runs omp's own SDK inside a local web server and reads the same ~/.omp/agent directory as the omp CLI. Start a session in the terminal, continue it in the browser, and go back — history, accounts and model settings stay in one place.

View source on GitHub Run from source

Install from GitHub source or the cuelo package on npm. Node.js and Bun are required.

In the app, accounts appear as these character faces and aliases instead of email addresses.

What CUELO is for

CUELO aims to turn the failures and blockers found during real work into memory, working rules and procedures, so the next task avoids the same mistake without someone having to point it out again.

Record what happened
A failure or blocker is written down from what was actually observed.
Change only the cause
The part that caused it is updated: a memory, a rule, or a procedure.
Carry it into the next task
The next task starts with that change in its context.
Check that it stopped
It counts only if the problem does not come back. If it does, start again at step 1.

Saving a record is not treated as the improvement itself. This is the goal the project works toward, not a measured result.

Two parts in one repository

The workspace

Web app · repository root

Find and continue past omp sessions per project, with live streaming of tool calls, cost and context use.
Branch from an earlier message or fork into a separate session.
Assign models to roles (default, smol, slow, plan, task …) using the same config.yml as the TUI.
Manage providers, models.yml, plugins and skills; preview files; switch Git worktrees.
Password lock, browser notifications and PWA install. The interface is Korean-first, with English and Simplified Chinese available.

The harness

Public rules · Tools/OMP_Global_Config/agent

How CUELO's agents work: a Main role that owns requirements, review and final judgement, and Maker roles that implement and verify delegated slices.
Dispatch and review contracts, a task guard, a routing advisor (Jev) and a command guard, as rules, SOPs and extensions.
Patches for the omp core.
node install.mjs setup copies it into your ~/.omp/agent, adding only missing files. You set your own modelRoles in config.yml. The web app works without it.

Read the harness documentation (Korean).

What this repository covers, and what it does not

Part	Details
Works from this repository	The whole web app: session browsing, live chat, branch and fork, model roles, provider, plugin and skill management, file preview, worktrees, password lock, character notifications, and an efficiency panel that reads `~/.omp/stats.db`.
Needs provider sign-in	Sessions, credentials and model settings live in `~/.omp/agent`, the same profile the `omp` CLI uses. You sign in to your providers yourself, in CUELO under Settings › Models.
Separate local services	The account usage card, side chat (`/btw`) and SubAgent archive get their data from three local services (`usage`, `btw`, `subagent`). `node install.mjs start` runs them next to the app on `127.0.0.1`. Credentials and records stay on your machine. If a service is not running, only its panel shows “not connected”.
Public harness	Rules, SOPs, extensions and omp core patches under `Tools/OMP_Global_Config`, described above.
Not included	Logins and API keys, personal provider, account and model choices (`config.yml`, `models.yml`), personal skills, work records, and the maintainer's private PC deployment tooling.

Install and run from source

CUELO is developed and tested on Windows. macOS and Linux are not development or test environments for this project; operation and support on those platforms are not guaranteed. You need Node.js 22.19.0 or newer, Bun 1.4.2 or newer and Git for a source installation.

git clone https://github.com/gim47656-ship-it/CUELO.git
cd CUELO
node install.mjs setup     # install, build, patch the SDK, copy the public harness
node install.mjs start     # app + usage, btw, subagent in the foreground

# in another terminal
node install.mjs health    # checks that all four services answer

Then open http://127.0.0.1:30141 yourself; the browser does not open automatically. Sign in to the providers you want to use under Settings › Models: browser OAuth or an API key, done by you. If the official omp CLI (@oh-my-pi/pi-coding-agent) is already installed, omp login works too; this guide does not install it. Every service listens on 127.0.0.1 only, and Ctrl+C stops all four. health only checks that each service answers; it does not sign in or call a model provider.

setup copies the public harness into ~/.omp/agent but only adds missing files; it never changes or deletes existing ones. When no config.yml exists, it creates one with safe default operating settings (for example, provider-calling automatic features stay off). These defaults ship with the installer; no one's personal configuration is copied, and an existing config.yml is left untouched. Choosing your models also stays with you: pass --model/--role to setup, or pick them later in Settings › Model roles. The installer does not guess models for you.

CUELO runs agents with broad permissions: do not expose plain HTTP to the internet — put it behind a trusted HTTPS reverse proxy or a VPN. The full guide, including other port sets and troubleshooting, is in docs/installation.md (Korean).

To use the prepared npm build, run npm install -g cuelo, then cuelo setup and cuelo start. Check the services with cuelo health. The omp-web package is the upstream project, not CUELO. Releases are listed on GitHub Releases; container use is covered in docs/docker.md.

Harness comparison

A separate page by the CUELO maintainer compares tools on the same coding tasks with the same model, changing only the tool (CUELO, Claude Code and Codex). Its conditions, caveats and weak spots are stated on that page.

Open the CUELO harness benchmark (Korean).