[!IMPORTANT] BizarHarness OMP is an extension for oh-my-pi, not a second agent runtime. OMP still owns models, credentials, tools, task execution, sessions, and conversation state.

Start here

Choose the path that matches what you are trying to do:

| Your goal | Run this | What it gives you | | --- | --- | --- | | Set up the complete experience | npx --yes @polderlabs/bizar-omp setup | omb, bizar-omp, the OMP extension, native agents, skills, rules, prompts, tools, and model roles | | Preview setup before changing anything | npx --yes @polderlabs/bizar-omp setup --dry-run | A report of the plugin and missing settings the installer would add | | Start one durable engineering session | omb | OMP inside a Bizar-owned tmux host, with reconnect support | | Switch between projects and sessions | omb agents | The full session hub and new-session picker | | Watch sessions in a browser | omb dashboard --open | A local, loopback-only dashboard with a single-use link | | Stop or restart everything Bizar owns | omb stop / omb restart | Bizar sessions, the daemon, and the tray, with a per-resource report | | Update an installed Bizar command | omb update | The latest global omb package and, when OMP is available, its enabled plugin | | Install only the OMP extension | omp plugin install @polderlabs/bizar-omp | Extension discovery without installing the omb and bizar-omp shell commands |

The shortest useful path is:

npx --yes @polderlabs/bizar-omp setup
omb

The setup command is safe to preview and safe to run again. It preserves credentials, provider choices, approval policies, explicit false or empty settings, and project overrides. It proposes only settings that are absent.

How Bizar fits into OMP

Bizar adds the engineering contract around an OMP session:

| You need | Bizar adds | | --- | --- | | A proportionate process | Focused, bounded, and full workflow tiers selected from scope and risk | | Durable work | omb sessions in tmux, or psmux on Windows, with reconnect and a cross-project hub | | Specialist help | Native roles for planning, research, implementation, review, security, verification, architecture, and documentation | | A stronger finish line | Acceptance criteria, host-observed checks, fresh evidence, review decisions, and serialized integration admission | | A readable operator view | OMP's native Advisor, visible agents, session activity, a local dashboard, and inspectable projections |

The ownership boundary is deliberate:

| OMP owns | Bizar owns | | --- | --- | | Models, providers, credentials, tools, task execution, session files, and conversation state | Workflow intent, acceptance, evidence freshness, candidate lineage, resource ownership, review policy, and integration admission |

Bizar does not replace OMP's task system, add a parallel scheduler, or provide a Claude Code, MCP, or background-daemon compatibility layer.

Install

Requirements

• Node.js 22 or newer
• Bun 1.3.14 or newer
• OMP 18.2.8 on PATH
• OMP 18.2.7, 18.2.6, 18.2.5, 18.2.4 remain regression-qualified
• tmux on Linux and macOS, or psmux on Windows for durable sessions

Check the host before installing:

node --version
bun --version
omp --version

Full installation

This is the supported path for a complete Bizar OMP setup:

npx --yes @polderlabs/bizar-omp setup

The installer:

1. Installs the exact Bizar package version globally, providing omb and bizar-omp.
2. Registers and enables that same version through OMP's plugin manager.
3. Installs the extension, eight specialist agents, skills, rules, prompts, tools, and model roles.
4. Makes the Bizar Orchestrator the default conversation and enables OMP's native Advisor.
5. Adds only absent compatibility settings for background work, visible agents, and readable output.
6. Writes a recoverable receipt for settings it changed and reads the result back.

For a reproducible install, pin the version:

npx --yes @polderlabs/[email protected] setup

For a named OMP profile or a non-standard OMP binary:

npx --yes @polderlabs/bizar-omp setup --profile bizar
npx --yes @polderlabs/bizar-omp setup --omp /path/to/omp

Preview or script the same operation:

npx --yes @polderlabs/bizar-omp setup --dry-run
npx --yes @polderlabs/bizar-omp setup --json

The interactive installer shows detected versions, each phase, settings it will add, the recovery receipt, and the next commands. --json produces machine-readable output for shell automation.

To update an installed global omb command to the latest published release:

omb update

Use omb update --check to inspect versions without changing anything, or omb update --dry-run to preview the package and plugin refresh. The global command is updated even when OMP is not available; the plugin refresh is skipped until OMP is installed.

Extension-only installation

Use this when you already manage omb separately or only need the OMP extension:

omp plugin install @polderlabs/bizar-omp

This does not install omb or bizar-omp on PATH. For checkout development, link the package instead:

omp plugin link /path/to/bizaromp

Check, repair, or remove

bizar-omp install-doctor
omp plugin list
omp plugin doctor

install-doctor reports the active plugin, receipt state, settings drift, and the policies Bizar left under OMP's control. Uninstall only the Bizar integration with:

bizar-omp uninstall

Uninstall restores a setting only when it still contains the value Bizar applied. If you changed that value later, Bizar preserves your change. Remove the global shell commands separately when needed:

npm uninstall --global @polderlabs/bizar-omp

Your first durable session

1. Start OMP through omb

omb

omb starts OMP inside a Bizar-owned tmux session from the first process. Closing the terminal client detaches from the session; it does not stop the host or its background agents. Run omb again in the same directory to reconnect to the most recently active live session.

Use a task-specific session when you want an explicit name:

omb new "Investigate the API timeout"
omb --session api-retries

omp remains the direct OMP command. Use it when you do not need durable tmux or psmux behavior.

2. Ask for work in the main conversation

The main conversation is the Bizar Orchestrator. Give it the outcome and constraints in plain language. It selects the smallest workflow tier that fits the work:

| Tier | Good fit | Typical proof | | --- | --- | --- | | Focused | A typo, small documentation edit, or narrow local fix | Targeted check, diff review, or smoke test | | Bounded | A contained behavior change or small feature | Acceptance criteria and focused tests | | Full | Security, architecture, migrations, concurrency, or cross-cutting work | Planning, isolation, review, fresh evidence, and serialized integration |

The tier can escalate when the scope or risk changes. A focused request still gets validation.

3. Inspect the work

Inside OMP, these commands expose the workflow state and proof:

/bizar run <objective>       Start a bounded workflow
/bizar status                 Show the active workflow state
/bizar evidence               List recorded checks and evidence
/bizar inspect                Explain blockers and evidence lineage
/bizar recipe <objective>     Preview an inspectable recipe
/bizar capabilities          Show native qualification boundaries
/bizar cancel [reason]        Cancel the active workflow

The tools behind these commands keep completion tied to fresh, host-observed checks. A stale check, changed candidate, missing review, or unknown native capability remains a blocker instead of being silently treated as success.

Useful model and dashboard commands are also available:

/bizar-models                 Ask the agent to distribute OMP's models across Bizar roles
/bizar-models preview         Show the live catalog's deterministic baseline without writing settings
/bizar-models health          Validate configured role selectors
/bizar-dashboard              Print a single-use local dashboard link
/bizar-dashboard open         Open the dashboard in the default browser
/bizar-dashboard stop         Stop the dashboard daemon

/bizar-models reads OMP's authenticated model catalog locally, reports what changed since the last observation, and hands the catalog, the current mapping, and a deterministic baseline to the active agent, which decides the distribution and persists it through the native bizar_apply_model_roles tool. That tool validates every selector against the live catalog and writes the whole mapping or nothing, preserving unrelated roles; a host without agent messaging applies the baseline itself. It does not promise a particular provider, model family, price, or quality level.

Command reports are longer than a status line can show, so the complete text is appended to .bizar-omp/run.log in the project the command ran in, as one JSON line per run with its timestamp, command event, and last session entry. The status line shows the fitted summary.

The omb agents hub

Open the session switcher from any project:

omb agents
omb agents --new    # open the new-session picker immediately
omb hub             # alias for omb agents

The hub shows every Bizar-owned session across projects. It includes:

• One full-width, workspace-grouped session list with a compact selected-session strip.
• Attach, rename, delete, refresh, settings, help, and reconnect controls.
• A new-session selector opened with n.
• Recursive search inside the configured Project directory root, parent navigation, recent paths, autocomplete, and direct absolute paths.
• Optional task text and an explicit session name.
• Privacy-safe activity summaries derived from the session journal. Prompts, thinking text, shell commands, tool output, credentials, and raw terminal history are not rendered.
• Optional native tray controls for opening the hub, creating a session, attaching a named session, stopping the daemon, and quitting the tray.

Hub controls

| Key | Action | | --- | --- | | Enter | Attach to the selected live session | | n | Open the full new-session menu | | e | Rename the selected session inline | | d | Delete the selected Bizar session | | s | Open settings | | r | Refresh without moving selection or scroll | | ? | Open help | | q | Exit the hub |

Mouse clicks select sessions and a second click opens a live one. Mouse scrolling moves through the session list while the hub is open. The hub enables terminal SGR mouse reporting only for its own lifetime. Mouse behavior inside an attached OMP session follows the session's OMP and multiplexer settings.

To configure project discovery, open s, select Project directory root, press Enter, enter a path such as ~/projects, and save. Use Show stopped sessions in this view when you need to inspect sessions whose host is no longer running. Deleting a session also tombstones its native journal so a recent history entry cannot reappear as an unopenable session; deleting an already unhosted row removes that stale history entry.

Session states

| State | Meaning | | --- | --- | | working | The journal shows unfinished work. | | waiting | The agent finished its turn and is waiting for input. | | connected | A client is attached and no structured activity has been journaled yet. | | disconnected | The host is live and unattached, with no work in progress. | | stopped | No host is observed and the journal is silent. |

State follows journal activity and host liveness, not tmux attachment alone. A detached session can remain working. Activity that stops advancing is marked stalled; old journal data is marked stale.

Optional tray

Enable the tray from hub Settings or use:

omb tray start
omb tray status
omb tray stop

The native tray backend is available on supported Linux, macOS, and Windows hosts. Unsupported desktop environments keep the terminal hub and daemon available.

Browser dashboard and daemon

The daemon keeps a session snapshot fresh independently of a terminal client. The dashboard binds to loopback and uses a single-use access code that expires after five minutes.

omb daemon start
omb daemon status
omb daemon restart
omb daemon stop

Open the dashboard:

omb dashboard          # print the local URL
omb dashboard --open   # print and open it in the default browser
omb dashboard --json   # emit { url, port, pid, code }
omb dashboard stop     # stop the daemon; tmux sessions keep running

The dashboard is organized around the active session. Choose a workspace session, read its live tmux console, and send a message from the composer with Ctrl Enter. Console output refreshes automatically without pulling you back to the bottom when you scroll up. Open terminal remains available for full-screen OMP interaction.

Create, rename, attach, and stop actions stay alongside the selected session. The new-session dialog lets you choose an available OMP model, thinking level, and permission mode. Dashboard settings can save those three choices as defaults for future dashboard-created sessions, alongside the shared project-root, auto-attach, mouse-forwarding, stopped-session, and tray preferences. Existing sessions keep the runtime they were launched with.

Permission choices map directly to OMP: Always ask auto-approves read-only tools, Allow workspace writes also auto-approves workspace writes, and Auto approve all uses OMP's yolo approval mode. OMP policy may still prompt or block an operation. Attach uses a terminal emulator from PATH; set BIZAR_TERMINAL to override detection. If no emulator is available, the dashboard returns the exact attach command.

The dashboard does not fetch a remote frontend. It serves one self-contained page, binds to 127.0.0.1, and keeps the exchanged token in browser session memory. omb dashboard --open replaces an incompatible resident daemon before opening the page, so an upgrade cannot leave stale dashboard styling or scripts running. The session-list payload excludes credentials, environment values, pane commands, process ids, prompts, and terminal history. Opening a session console makes a separate authenticated request for a bounded, control-sequence-stripped capture of that exact Bizar-owned tmux pane; composer input is length-limited and sent literally to that pane.

Stopping and restarting the runtime

omb stop is the single teardown path for everything Bizar owns: Bizar-named tmux sessions, the daemon, and the tray. With no target flag it stops all three, and stopping something that is not running is a success rather than an error.

omb stop                    # sessions, daemon, and tray
omb stop --all              # sessions and services (the default)
omb stop --sessions         # only Bizar-owned tmux sessions
omb stop --session ADDRESS  # one session, repeatable: Bizar name, session id,
                            # or the digest its name carries
omb stop --idle             # only sessions with no client and no work in flight
omb stop --daemon           # only the daemon (alias: --dashboard)
omb stop --tray             # only the tray
omb stop --force            # also stop sessions a client is attached to
omb stop --dry-run          # report what would stop without stopping it
omb stop --json             # { command, dryRun, stopped, started, skipped,
                            #   planned, failed, resources }

Every omb stop row reports what happened to that resource — stopped, skipped with the reason, planned for a dry run, or failed — and states stopped as a boolean as well, so a reader that only asks whether a resource is now stopped does not have to know the action vocabulary.

Only Bizar-owned sessions are ever candidates, omb stop never stops the session it is running inside, and an address that does not name exactly one session is refused with exit code 2 before anything is stopped. A Bizar name that is not running is a success with a not found row, so the same command twice is safe.

Target flags are additive, except that --all together with --session NAME narrows the session selection to the sessions named while the daemon and the tray are still stopped. The daemon and the tray are signalled only while the recorded lock's PID is verified to still be that process, so a lock that cannot be verified is skipped with a reason instead of signalled.

A session is reported stopped only when its absence is proven: a kill-session the multiplexer refused, or a refusal that could not be confirmed by listing the sessions, is reported as failed rather than as a stop that did not happen. A multiplexer that is not installed, or that has no server running, stops nothing and reports success.

omb restart                 # stop the runtime, then start the daemon and tray
omb restart --force         # also stop sessions a client is attached to
omb restart --dry-run       # report the plan without stopping or starting
omb restart --json          # { command, dryRun, stopped, started, skipped,
                            #   planned, failed, resources, url }

omb restart always stops the whole runtime first, so omb stop owns the target flags: --all, --sessions, --session NAME, --daemon, --dashboard, --tray, and --idle are all refused with an error that points at omb stop and exit code 2. It starts the daemon, starts the tray only when the tray is enabled in hub settings, and prints a fresh single-use dashboard link. Agent sessions are not relaunched: their journals are kept, so omb in a project or the hub brings a session back.

omb restart reports exactly one row per resource — each Bizar-owned tmux session, the daemon, the tray, and the dashboard. A row's state is the state observed before the command acted, and its action is what the restart did with that resource overall: started when the resource was stopped and started again (reason stopped, then started), stopped when it ended stopped (a session, or a tray that settings no longer run), skipped when there was nothing to do, and failed on a failure. A stop that failed leaves that resource's row failed even when the resource was started again, and the exit code is nonzero; the daemon and the tray are still started, so the runtime is left usable.

omb restart --dry-run uses the same one-row-per-resource shape, including the dashboard row, with action planned and reason stop, then start; a tray that settings do not enable is skipped instead. In --json, url is always present: the freshly minted dashboard access link, or null when no link was minted, which is a dry run or a dashboard that failed to start.

omb help lists the commands, and omb help <command> prints that command's own usage; --help works on every command too.

omb help            # every command
omb help stop       # one command's usage
omb help --json     # { commands: [{ name, names, summary, usage }] }

omb --help and omb -h are omb's own tokens and print omb's table; use omp --help for OMP's own help. --session ADDRESS, --session-id ADDRESS, and --new are omb's launcher options and are consumed before OMP sees them; anything else omb does not recognise is passed through to OMP, so omb --resume and omb "fix the failing test" keep their OMP meaning.

Native roles and assets

Installation registers visible bizar_* roles without replacing operator-owned mappings. The default package includes:

• Bizar Orchestrator and Advisor integration.
• Specialist agents for architecture, planning, research, implementation, review, security, verification, and documentation.
• The bizar-omp orientation and workflow skills.
• Native rules, prompts, tools, evidence schemas, and the OMP-native development reference skill.

The role names are selectors, not guarantees of speed, cost, provider, or model quality. Inspect the resolved OMP catalog when those properties matter.

Safety and ownership boundaries

• Bizar is trusted in-process extension code. OMP extensions and shell commands are not an OS sandbox.
• Credentials, API keys, .env contents, and private control links are excluded from logs, commits, and evidence bundles.
• OMP keeps ownership of credentials, providers, model selections, approval policies, tool policies, and project overrides.
• Managed worker changes stay isolated and require explicit parent integration. Bizar never silently applies worker patches.
• Git worktree cleanup is preview-first, ownership-aware, and non-forced. Ignored or uncertain content blocks cleanup.
• Install only in projects and environments you trust. Review setup --dry-run and bizar-omp install-doctor before making changes.

Qualification boundary

The 0.6.7 release ships the omb a alias for the agents view, an interactive Ink progress panel for omb update, and a live Server-Sent Events chat stream with connection status in the dashboard, published on npm and available as a GitHub release.

The release does not claim OS sandboxing, provider model quality, universal native task or eval interception, automatic cleanup of an unqualified native isolation backend, or Claude Code/AO compatibility. See the support matrix for the current boundary.

Compatibility

| Component | Qualified baseline | | --- | --- | | OMP | 18.2.8, with 18.2.6, 18.2.5, and 18.2.4 regression-qualified | | Node.js | 22.x and 24.x | | Bun | 1.3.14 compatibility job | | Package | @polderlabs/[email protected] |

Upstream OMP changes require a new compatibility baseline and contract run. The package does not widen a version range to hide an unqualified runtime.

Development and verification

npm ci
npm run typecheck
npm test
make verify

make verify runs typecheck, tests, package verification, generated documentation checks, and secret scanning. Build the package directly with:

npm run build
npm run verify:package
npm run pack:check

The native OMP qualification needs the OMP source package. When it is available:

npm run verify:omp
npm run verify:omp:registry

Release notes and compatibility records live in docs/releases/. See CONTRIBUTING.md for branch conventions, release tags, and trusted publishing.

License

MIT. See LICENSE.