README.md

September 18, 2026 · View on GitHub

OMK, Open Multi-Agent Kit. Scope the work. Route the right agents. Verify every release. The mark shows a four-stage control loop with three routed lanes.

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.

npm version npm downloads per month
latest GitHub release
MIT license supported Node.js version

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.

  1. Run /login to authenticate a supported subscription or API-key provider.
  2. Run /model to choose an available model.
  3. 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.

CapabilityFresh-install behaviorWhere to start
File editing, shell commands, saved sessionsBuilt in; tools run when called by the agentUsage, sessions
Tool-call schedulingdag-v2 schedules resource conflicts within the agent loop; it does not launch a teamRuntime algorithms
SubagentsOptional extension; load it and supply agent definitionsSubagent setup and examples
MCP servers, extra skills and extensionsRequire configured servers or installed resourcesMCP, skills, extensions
Protocol verification and advisory judgingExplicit API/workflow opt-in; not a gate on ordinary promptsRun protocol
Context budgetingOff by defaultSettings
AdaptOrch integrationOptional and separate; no service calls by defaultOMK + 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 coveredRegression evidenceScope
Missing test observations produce inconclusive; a required failing test produces failProtocol testsExplicit protocol evaluation, without a waiver
Changed artifacts, wrong command bindings, or missing ledger evidence block acceptanceEvidence binding testsStrict evidence gate and selected workspace scope
A relevant workspace mutation after verification makes the receipt staleFreshness testsConfigured 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.

OMK//CONTROL terminal dashboard showing model routing, tools, and session status

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.

Animated OMK control loop showing Scope, Route, Verify, and Replay

The v0.98.3 SDK rejects incomplete first-party judge responses and exposes deterministic ties; it is not an automatic TUI judge.

  1. 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.
  2. Route work to models, agent skills, MCP tools, and extensions without changing the evidence contract.
  3. Verify declared checks in explicit evidence workflows. Required failing checks block those workflows; advisory judging cannot replace them.
  4. 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

PackagePurpose
open-multi-agent-kitInteractive coding-agent CLI and control plane
omk-agent-coreAgent runtime, tool execution, and DAG scheduling
omk-aiUnified multi-provider LLM API
omk-protocolVersioned run contracts and semantic reducers
omk-adaptorch-wplWork Packet Loop runtime
omk-book-to-skillOptional document-to-skill compiler
omk-tuiDifferential-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's Scope -> Route -> Verify -> Replay loop 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. An interrupted corpus now fails unless openwiki/.manual-review.json binds a review to the exact corpus digest, and every frontmatter symbol must bind to one of that page's own source_paths as a whole identifier.
  • scripts/check-openwiki-output.mjs — output gate. The scheduled workflow may write, upload, and open a PR for openwiki/ and nothing else, so a model reading this repository cannot reach AGENTS.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 writes and runs code. AdaptOrch checks what it wrote. correctness_claim: false — it ran, and this is what happened.

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.

PaperMechanism it establishesOMK implementation or design reference
arXiv:2608.22752The Compaction Cliff in Long-Running AI Agent MemoryUniform 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.23023Most of the LLM Routing Gap Is Task TypeMost 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.16655Arch-Router: Aligning LLM Routing with Human PreferencesIndirection: 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.09894Deterministic vs. LLM-Controlled OrchestrationHolding 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.15565Admission Without AnswersLabel-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.23471InjecMEM: Memory Injection Attack on LLM Agent Memory SystemsSingle-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

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/skills and load when no user, project, or explicit skill supplies a name (OMK_BUNDLED_SKILLS=0 or --no-skills to disable), plus an omk neo subcommand 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-browser extension example: ports the Claude Code plugin to OMK, rendering a real browser in a kitty-graphics overlay via the bridge HTTP API; /browser command 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/messages never doubles.

Added (previous cycle work)

  • --thinking ultra is now a first-class Astra selector level. GPT-6 Astra maps it to the documented max effort rather than clamping it away or sending an invented ultra wire value.
  • The status rail's USAGE section now covers commandcode: it calls Command Code's /alpha whoami, 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; /new does not reload provider modules.
  • The status rail's Devin USAGE meters now match the CLI /usage surface: credit-billed plans no longer render proto-default 0% remaining as exhausted 1D/7D windows, and GetUserStatus unary 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: 2 and omk-tb21-audit-report-2. Selection totals can be null when estimates are unknown, and audits reject missing or invalid start/finish timestamps. The input manifest remains omk-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: 2 and 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-harness domain loadout auto-applied when the devin provider is active (OMK_DEVIN_HARNESS=0 disables it, independently of OMK_GROK_HARNESS), per-turn <active_skills source="devin-harness"> grants selected from the live inventory, an optional ~/.omk/agent/devin.md operator overlay, and the canonical Devin SWE-2 harness guide. devin/swe-2 now 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 calls GetUserStatus with the stored CLI session token (OAuth or DEVIN_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 the sdk.ts import cycle) and harness-skills.ts; the grok-harness and devin-harness profiles live in domain-loadouts-provider-harness.ts. tryGrokHarnessDispatch() and selectGrokHarnessSkills() keep their public signatures and behavior.

Fixed

  • A background task result delivered with triggerTurn while the session was sleeping in retry backoff started a second top-level run: sendCustomMessage only checked isStreaming, not isRetrying (unlike prompt()). When the retry woke up, agent.continue() threw Agent is already processing, and the runtime-failure handler closed the run journal that the competing run still owned, so that run later died with run journal received agent_end without run_started and 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 with Agent is already processing while 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 display OMK resource.

Release notes live in RELEASE_NOTES_v0.99.0.md.

Release v0.98.5

Added

  • Added /debug runtime 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