README.md
September 18, 2026 · View on GitHub
OMK
Open Multi-Agent Kit
Scope the work. Route the right agents. Verify every release.
A terminal coding agent that lets you switch models without starting a new session.
Quick start ·
Default or opt-in? ·
Evidence and limits
Choosing OMK ·
Documentation
Why OMK
Choose a model, work on your repository, then switch models with /model when
another one suits the next step. The conversation stays in the same session.
You can also stop and return later with /resume or omk -c.
OMK is a standalone CLI, not a plugin for Claude Code or OpenCode. It supports subscription providers, API keys, and local models. Start with one agent that reads files, edits code, and runs commands. Add subagents or explicit verification workflows when you need them; neither is required for your first task.
Quick start
Requires Node.js 22.19 or newer. Start in the repository you want to work on:
npm install -g open-multi-agent-kit --ignore-scripts
omk --version
cd your-project
omk
Without a global install, run npx --ignore-scripts open-multi-agent-kit from
that directory.
- Run
/loginto authenticate a supported subscription or API-key provider. - Run
/modelto choose an available model. - Try a read-only first task:
Summarize this repository and identify the commands used to check it.
Read the project configuration to support your answer. Do not edit files.
After the reply, use /model to choose another configured model and ask it to
review the answer. You stay in the same session. This is manual model switching,
not parallel agents or an independent correctness check.
For a bug fix, name the failing behavior and ask for a regression test, the smallest fix, and the check commands with their exit codes. Review the diff and those results yourself; a request to run tests does not enable a verification gate.
Built-in local bash requires sandbox-exec on macOS or bwrap plus
unprivileged user namespaces on Linux. It blocks network access and fails
closed if the backend is missing. See the safety boundary
and full quickstart for setup.
What runs by default
A fresh install starts one agent/tool loop after provider setup. It does not turn each prompt into a multi-agent workflow or automatically certify its answer.
| Capability | Fresh-install behavior | Where to start |
|---|---|---|
| File editing, shell commands, saved sessions | Built in; tools run when called by the agent | Usage, sessions |
| Tool-call scheduling | dag-v2 schedules resource conflicts within the agent loop; it does not launch a team | Runtime algorithms |
| Subagents | Optional extension; load it and supply agent definitions | Subagent setup and examples |
| MCP servers, extra skills and extensions | Require configured servers or installed resources | MCP, skills, extensions |
| Protocol verification and advisory judging | Explicit API/workflow opt-in; not a gate on ordinary prompts | Run protocol |
| Context budgeting | Off by default | Settings |
| AdaptOrch integration | Optional and separate; no service calls by default | OMK + AdaptOrch |
The internal lane launcher and automatic command-sharding primitives are not connected to the default CLI path. Installing their packages is not the same as enabling an orchestration workflow.
Evidence and limits
No comparative benchmark result is published here yet. We have not established that OMK solves more tasks than another harness, that multi-agent execution improves success, or how much verification reduces false completion.
OMK targets state-of-the-art quality as a CLI coding-agent harness. SOTA is not verified.
The evidence you can inspect today covers specific failure modes:
| Behavior covered | Regression evidence | Scope |
|---|---|---|
Missing test observations produce inconclusive; a required failing test produces fail | Protocol tests | Explicit protocol evaluation, without a waiver |
| Changed artifacts, wrong command bindings, or missing ledger evidence block acceptance | Evidence binding tests | Strict evidence gate and selected workspace scope |
| A relevant workspace mutation after verification makes the receipt stale | Freshness tests | Configured receipt and mutation tracking |
These tests exercise the gates, not the rate at which they catch real bugs.
An ordinary prompt finishes when its tool loop and queued work settle;
prompt_settled is not a correctness verdict.
A useful comparison must hold the model, provider configuration, tasks, budget,
and tool permissions constant, and label default versus opt-in workflows.
Report task success, cost, latency, and false completion (reported complete but
failing the declared checks), with its denominator and per-task outcomes.
The measurement protocol
defines the reproducibility and privacy requirements. omk stats shows local
turn costs and tool failures; it does not score task correctness.
If you evaluate OMK, share a sanitized report and reproduction steps in a GitHub issue. Include failed and interrupted runs, not just successful examples.
OMK//CONTROL
The terminal UI shows the selected model, tools, and session status. Additional signals depend on the integrations you configure.
The header reads omk v<package.version> · OMK//CONTROL; the installed package
version is the source of truth.
Control loop
How scope, routing, verification, and replay fit together
OMK's provider-neutral coding-agent CLI also exposes a multi-agent control plane for explicitly configured workflows. The diagram describes that design, not what every prompt automatically runs.
The v0.98.3 SDK rejects incomplete first-party judge responses and exposes deterministic ties; it is not an automatic TUI judge.
- Scope the goal, paths, resources, and acceptance predicates. A selected orchestration workflow may also supply a DAG; an ordinary prompt remains one agent/tool loop.
- Route work to models, agent skills, MCP tools, and extensions without changing the evidence contract.
- Verify declared checks in explicit evidence workflows. Required failing checks block those workflows; advisory judging cannot replace them.
- Preserve receipts and replay state for bounded session recovery; continue durable goals from explicit reducer state.
The animation changes once every 1.5 seconds and contains no flashing. The four steps above are the complete text alternative.
Verification boundary
AgentSession built-in local bash uses OS sandbox enforcement by default:
sandbox-exec on macOS and bwrap plus unprivileged user namespaces on Linux.
Local shell spawns restrict writes to the workspace and OS temporary directory,
disable network access, and fail closed with sandbox.backend_missing when an
enforcement backend is unavailable.
This is not read-confidentiality or whole-process containment. Other file
tools, extension and custom-tool code, injected or remote BashOperations, and
the OMK process keep the permissions of the process running them. Use
containerization when the
boundary must cover more than built-in local bash. Explicit evidence workflows
cannot treat missing required evidence as a verified result.
Providers
Provider integrations and published packages
OMK keeps routing separate from control and evidence. Codex, Claude Code,
OpenCode Zen/Go, Kimi, GLM/ZAI, native xAI/Grok, NVIDIA NIM, and local providers
can participate through omk-ai while the run contract stays stable.
Native xai keeps subscription OAuth and XAI_API_KEY billing separate. See
provider setup,
provider resilience, and
Grok integration.
Published packages
| Package | Purpose |
|---|---|
open-multi-agent-kit | Interactive coding-agent CLI and control plane |
omk-agent-core | Agent runtime, tool execution, and DAG scheduling |
omk-ai | Unified multi-provider LLM API |
omk-protocol | Versioned run contracts and semantic reducers |
omk-adaptorch-wpl | Work Packet Loop runtime |
omk-book-to-skill | Optional document-to-skill compiler |
omk-tui | Differential-rendered terminal UI library |
npm install omk-agent-core
npm install omk-ai
npm install omk-protocol
omk install npm:omk-book-to-skill@0.98.3
npm install omk-tui
Repository understanding
Optional indexes, retrieval settings, and trust limits
v0.97.0 shipped the OpenWiki policy and workflow, but no versioned corpus or
integrity checker. The following integrity/output guards shipped in v0.98.0;
the generated corpus remains optional and is not bundled:
openwiki/— absent. The previous untracked corpus was removed after the hardened gate proved it carried fabricated evidence: 8 frontmatter symbols that no declared source path defines (AgentLoop,getModel,DeepWall,loadExtensions,createExtensionRuntime,main), 45 references to@omk/*package names this repository does not publish, and a restatement of this README'sScope -> Route -> Verify -> Replayloop as a strict engine state machine, which is not what the source implements. CI regenerates the corpus; nothing is lost.scripts/check-openwiki.mjs— shipped integrity checker. Aninterruptedcorpus now fails unlessopenwiki/.manual-review.jsonbinds a review to the exact corpus digest, and every frontmatter symbol must bind to one of that page's ownsource_pathsas a whole identifier.scripts/check-openwiki-output.mjs— output gate. The scheduled workflow may write, upload, and open a PR foropenwiki/and nothing else, so a model reading this repository cannot reachAGENTS.md,CLAUDE.md, or the workflow that runs it. The gate runs once before the artifact leaves the read-only generating job and again before the PR, because the publishing job holds write permissions the first one does not..understand-anything/— optional local structural graph used by Pi Lens; it is not published or injected into prompts by default. To reach a session, attach it through OMK's MCP client like any other server; there is no second, bespoke path for it.
Source and tests remain authoritative. Shipped guards do not turn a generated index into authority: treat corpus pages as local advisory data and recheck source.
Retrieval
A corpus no session can read is documentation of a plan, not a feature, so the
pages are now candidates for prompt budgeting. Enable contextBudget.openwiki
alongside contextBudget.enabled
(settings)
and each page becomes a low-priority evidence item ranked against the turn's
query. Pages compete for leftover budget and can never displace instructions or
skills; most turns carry titles and declared symbols alone, and a page's text
arrives only when the query earns it.
Admission mirrors scripts/check-openwiki.mjs rather than restating it. A
complete corpus at the current HEAD offers page text; one whose HEAD has
moved offers titles only and is marked stale; an interrupted corpus is refused
unless a review binds to its exact digest. The default is off, and with the
setting off the prompt is byte-identical to one built without a corpus.
OMK + AdaptOrch
OMK is this local, MIT-licensed coding agent. AdaptOrch is a separate proprietary evidence service. Neither requires the other: installing OMK does not create an AdaptOrch account or make calls to it by default.
For an optional integration, see the WPL package and clients and MCP setup. The WPL package exposes state, client, and adjudication primitives, not an automatic verification loop for every CLI prompt.
AdaptOrch's reports carry correctness_claim=false; they are not semantic
correctness proofs or OMK harness benchmark results.
Review AdaptOrch plans
· Claim boundary
The AdaptOrch name and marks identify that separate proprietary product and appear here with permission. They are excluded from this repository's MIT grant — see LICENSE.
Prior art
Research references, not OMK benchmark results
The design decisions behind OMK's context, routing, memory, and orchestration layers are grounded in published work rather than invented in isolation. Each row below was retrieved and read directly; claims are at abstract level, which is the evidence grade this table asserts and no more.
| Paper | Mechanism it establishes | OMK implementation or design reference |
|---|---|---|
| arXiv:2608.22752 — The Compaction Cliff in Long-Running AI Agent Memory | Uniform summarization erodes rules and episodic logs at the same rate; measured safety-rule retention falls to 53% after one compaction and 10% after five. Type-tagged deterministic operators fix it. | Type-aware compaction triage: rule-typed items survive N rounds byte-identical |
| arXiv:2608.23023 — Most of the LLM Routing Gap Is Task Type | Most routing gain is reachable with a fixed task-type table; run-to-run flips must not be credited as wins. | Frozen task-class table plus the 2-run stability rule in the promotion gate |
| arXiv:2506.16655 — Arch-Router: Aligning LLM Routing with Human Preferences | Indirection: a classifier emits a label, a policy table maps label to decision, so models change without retraining. | classifyTaskV4 plus TASK_CLASS_THINKING_LEVELS |
| arXiv:2605.09894 — Deterministic vs. LLM-Controlled Orchestration | Holding model, prompts, and tools constant and varying only execution control, deterministic orchestration matched accuracy, improved worst-case robustness, and cut tokens up to 3.5x. | Deterministic scheduler and planned lanes; execution control is never delegated to the model |
| arXiv:2608.15565 — Admission Without Answers | Label-free admission on execution success alone admits substantial contamination; an accept/abstain/escalate decision is required. | Verified-memory admission design (spec 019), abstain is not stored |
| arXiv:2608.23471 — InjecMEM: Memory Injection Attack on LLM Agent Memory Systems | Single-interaction memory injection is a reproduced attack frame against agent memory. | Retrieved memory is injected only as provenance-tagged data, never fused into instruction position |
Entries include implemented mechanisms and design proposals; check the runtime status guide for availability. The wider survey, including approaches not adopted, is working material that is not published with the repository.
Documentation
- Documentation index
- Usage
- Turn metrics and harness evaluation
- Providers and models
- Automation and SDK
- Run protocol
- Runtime algorithms and direction
- Specification index
- Sessions and recovery
- Security
- Containerization
- Public skill catalog
- Changelog
- Release notes for v1.0.0
Development
npm ci --ignore-scripts
npm run build
npm run check
npm test
npm run release:local
Direct dependencies are pinned, CI installs with --ignore-scripts, and the
published CLI includes a generated npm-shrinkwrap.json. Read
CONTRIBUTING.md and the
development guide before sending a
change.
FAQ
Why use OMK instead of Claude Code?
Use it for provider choice within one CLI session, or to build workflows against its public runtime and evidence APIs. For a single-provider workflow, your current agent may be sufficient. Try the read-only task above before moving existing work.
How is this different from OpenCode with plugins?
OMK is a separate runtime with its own CLI, sessions, tool scheduler, and SDK.
One reason to choose it is to build your own acceptance workflow: define
required test observations in the run protocol,
then have your automation reject fail or inconclusive results. Receipt
integrity and freshness still need their own configured checks.
For adding a tool or prompt to an existing OpenCode setup, a plugin may be the smaller change. OMK's protocol is opt-in, not proof of better performance.
Does multi-agent mean better results or automatic verification?
Not automatically. Subagents require setup, and verification must be part of the chosen workflow. Its result covers the declared checks, not all behavior. See what runs by default and evidence and limits.
Recent releases
Release notes and historical corrections
Historical correction: the immutable v0.97.0 notes below announced a versioned OpenWiki corpus, but that release still ignored
/openwiki/and did not contain the corpus or checker. See the current repository-understanding section above for the shipped guards and optional-corpus boundary.
Release v1.0.0
Added
- Bundled Neo skills: six public skills ship in
resources/neo/skillsand load when no user, project, or explicit skill supplies a name (OMK_BUNDLED_SKILLS=0or--no-skillsto disable), plus anomk neosubcommand and an ACP conversation-only mode (--mode acp). - Subagent lane execution settlement: lane results model settled/failed/unsettled, a shared permit pool tracks unsettled children across dispatch instances, heavy-lane admission narrows the width gate, and permit weights validate explicitly.
- In-memory run usage ledger (
run-usage-ledger,run-usage-operation): reserves capped budgets per attempt, records transports and cumulative usage idempotently, binds settlement to the attempt admitted at entry (caller input mutation cannot redirect it), and retains reservations for unknown usage — accounting only, not a hard financial limit. terminal-browserextension example: ports the Claude Code plugin to OMK, rendering a real browser in a kitty-graphics overlay via the bridge HTTP API;/browsercommand and open/close tools.- Strict-evidence approval adapter in
guardrails/binding protocol-level evidence reports to host approval decisions.
Fixed
- Empty streamed completions (success-shaped stop with zero usable output) classify as dead streams: they no longer reset the retry budget, pin the UI in a retrying state, or rotate to a live route in the same model family (ox-alpha/union-alpha rotation). Anthropic-messages base URLs carrying a version suffix are normalized so
/v1/messagesnever doubles.
Added (previous cycle work)
--thinking ultrais now a first-class Astra selector level. GPT-6 Astra maps it to the documentedmaxeffort rather than clamping it away or sending an inventedultrawire value.- The status rail's USAGE section now covers
commandcode: it calls Command Code's/alphawhoami, credits, subscription, and usage-summary endpoints with the stored API key and renders the 5-hour, weekly, and monthly credit meters with reset times, or the plan name when rolling windows are absent.
Fixed
- Missing ESM named-export errors such as
does not provide an export named 'MAX_FRAME_BYTES'classify as configuration, not as an orphan tool-call protocol fault. The Next action tells the operator to restart OMK;/newdoes not reload provider modules. - The status rail's Devin USAGE meters now match the CLI
/usagesurface: credit-billed plans no longer render proto-default 0% remaining as exhausted 1D/7D windows, andGetUserStatusunary gzip bodies decode.
Release notes live in RELEASE_NOTES_v1.0.0.md.
Release v0.99.0
Breaking Changes
- Checkout-only TB tooling now emits
selectionVersion: 2andomk-tb21-audit-report-2. Selection totals can benullwhen estimates are unknown, and audits reject missing or invalid start/finish timestamps. The input manifest remainsomk-tb21-manifest-1. Update report consumers and freeze new task selections before comparing runs; see selection compatibility and audit rules.
Added
-
Verified command DAGs accept an explicitly approved
writer.maxConcurrentTasks: 2and release ready dependants without an unrelated-task barrier. Omission keeps serial execution and legacy contract digests. Task-bound execution IDs and draining preserve cancellation/recovery boundaries; final verification still uses one fixed candidate. See Verified Run. -
Added the Devin SWE-2 harness: a
devin-harnessdomain loadout auto-applied when thedevinprovider is active (OMK_DEVIN_HARNESS=0disables it, independently ofOMK_GROK_HARNESS), per-turn<active_skills source="devin-harness">grants selected from the live inventory, an optional~/.omk/agent/devin.mdoperator overlay, and the canonical Devin SWE-2 harness guide.devin/swe-2now carries a 1,000,000-token local context budget that selects the account catalog's 1M-context lane; a lane that declares a smaller window fails the request instead of shrinking the budget. -
The status rail's USAGE section now covers
devin: it callsGetUserStatuswith the stored CLI session token (OAuth orDEVIN_API_KEY) and renders the plan's daily/weekly quota meters with reset times, or the plan name and credit balances when the account reports no quota windows.
Changed
- Grok and Devin harness dispatch share
provider-harness-dispatch.ts(loadout runtime injected, outside thesdk.tsimport cycle) andharness-skills.ts; thegrok-harnessanddevin-harnessprofiles live indomain-loadouts-provider-harness.ts.tryGrokHarnessDispatch()andselectGrokHarnessSkills()keep their public signatures and behavior.
Fixed
-
A background task result delivered with
triggerTurnwhile the session was sleeping in retry backoff started a second top-level run:sendCustomMessageonly checkedisStreaming, notisRetrying(unlikeprompt()). When the retry woke up,agent.continue()threwAgent is already processing, and the runtime-failure handler closed the run journal that the competing run still owned, so that run later died withrun journal received agent_end without run_startedand the session was wedged until a model switch. Custom messages now queue during retry backoff exactly as during streaming, and a run that never owned the journal (rejected withAgent is already processingwhile another run is live) no longer finishes or clears it. -
Codex SSE response-header waits now respect
retry.provider.timeoutMs, with the existing 10-second minimum, rather than aborting every large request at a fixed 10 seconds. This does not extend an outer run deadline. -
Resource completion descriptions remove decorative leading
[OMX]/[OMO]labels without changing source metadata, invocation names, or enabled tools; marker-only descriptions displayOMK resource.
Release notes live in RELEASE_NOTES_v0.99.0.md.
Release v0.98.5
Added
- Added
/debugruntime inspection, explicit metadata-only local reports with/debug save, and structured failure cards with expandable details. UI entry observations do not infer build revisions or authorize retries. - Added opt-in verified-run CLI/SDK paths with protected verification, immutable candidate recovery, input-checkpoint writer restart, and static DAG task retry. These paths retain approval, ownership and budget boundaries; they do not apply artifacts to the original workspace automatically.
Fixed
- Strengthened execution ownership and shared-budget boundaries. Pre-commit checks preserve the selected index, including partially staged files, instead of expanding the commit.
- Execution-ownership wrappers retain lazy, context-sensitive tool timeouts and stale-context rejection instead of fixing the timeout at registration.
Release notes live in RELEASE_NOTES_v0.98.5.md.
Acknowledgments
OMK builds on pi — Mario Zechner's
MIT-licensed coding-agent harness — and began from the
oh-my-pi fork. The vendored tree was
removed in this release line; OMK 0.9x is OMK-native (see
specs/constitution.md), and the design debt to both
projects stands. Thank you.
License
MIT