Omk

OMK is a lightweight, MIT-licensed AI coding agent for your terminal, written in TypeScript. Switch models in one session, add subagents when you need them, and mark a goal done only when your own check passes. It is a standalone CLI, so it can serve as an open-source alternative to a single-provider agent such as Claude Code.

Requires Node.js 22.19 or newer:

npm install -g open-multi-agent-kit --ignore-scripts
cd your-project
omk

The first run opens /login (subscription, API key, or local model). To try it without a global install: npx --ignore-scripts open-multi-agent-kit. Details in Quick start.

Why OMK

An AI saying “done” is not an acceptance check. With /goal verify, you choose the command that checks your goal. OMK runs it after each settled turn and completes the goal only when it passes on the current workspace. A later edit makes that evidence stale. The result is only as strong as the check you choose.

/goal Fix the failing test without changing its assertions.
/goal verify node --test check.test.mjs

Use a test that exists in your project, or follow the small, reproducible goal demo. This is an explicit workflow; ordinary prompts do not enable the gate.

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.

At a glance

• Done means a passing check. /goal verify <command> completes a goal only when your check passes on the current workspace.
• One session, many models. Switch with /model mid-conversation; resume later with /resume or omk -c.
• Sandboxed by default. Built-in bash runs under sandbox-exec or bwrap, without network, and fails closed.
• Opt-in power. Subagents, MCP servers, skills and extensions load only when you configure them.
• Honest evidence. Claims below link to the docs that back them, and the limits are stated next to them.

flowchart TD
  P["Prompt or goal"] --> A["Agent loop"]
  A --> S["Settled turn"]
  S --> R["Response"]
  S -->|"goal verification configured"| V["Run acceptance check"]
  V -->|"pass on current workspace"| D["Goal complete"]
  V -->|"fail"| A

The loop uses your selected model and available tools. Subagents, MCP, skills, and extensions depend on your configuration.

Quick start

Install from npm (Node.js 22.19 or newer), then start in your repository:

npm install -g open-multi-agent-kit --ignore-scripts
cd your-project
omk

Or run npx --ignore-scripts open-multi-agent-kit without a global install.

Or install the standalone binary, which needs no Node.js (macOS, Linux):

curl -fsSL https://github.com/dmae97/omk/releases/latest/download/install.sh | sh

The script checks the download against the release's SHA256SUMS and installs to ~/.omk/bin; add that folder to your PATH as it tells you. Windows builds are attached to each release.

1. On a first run OMK opens /login for you: sign in with a subscription or an API key. An existing Claude Code or Codex CLI login can be reused with omk provider adopt.
2. Run /model to choose another available model at any time.
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.

Ready to see a test-backed goal? Try the goal demo, then share your result or a reproducible failure in a GitHub issue. If this workflow is useful, star OMK to help other developers find it.

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 (sudo apt install bubblewrap on Debian and Ubuntu). It blocks network access and fails closed if the backend is missing. omk doctor checks the runtime, credentials, the model a first session would pick, and the sandbox, and prints the fix for this machine. See Bash sandbox setup, the safety boundary and the full quickstart.

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.

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.

Context, cache and memory

OMK manages several distinct resources. A prompt-cache boundary, a local cache, and the process's RAM are not the same thing; provider cache hits and costs depend on the provider and the request.

For one process, opt into context budgeting and keep its cache in session memory:

OMK_CONTEXT_GOVERNOR=1 OMK_CONTEXT_GOVERNOR_CACHE=memory omk

Memory-only changes where entries are kept; it is not a guarantee of lower RAM use. Cache effectiveness, memory use, latency and cost depend on the workload. Measure them before claiming an improvement; turn metrics show what can be recorded.

Evidence and limits

One dated comparison is available below: OMK and mini-SWE-agent on Terminal-Bench 2.1 with the same base model. The observed success-rate difference is not statistically significant, and the time budgets differed. It does not establish overall harness superiority, multi-agent gains, 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:

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.

Terminal-Bench 2.1 · R8

75.8% observed success · approximately 23% lower recorded model cost per graded trial. OMK took longer: 482 s median, compared with 376 s for mini-SWE-agent. Both used xAI grok-4.7 at reasoning effort xhigh in a 2026-10-05–06 KST run of 89 tasks, with 3 trials per task per harness.

The +4.2 percentage-point success difference is not statistically significant (95% task-level paired-bootstrap CI: −1.9 to +10.2 pp). OMK alone had 150 s extra per trial for snapshots, so the time budgets were unequal. This result covers the 1.3.0 evaluation build 78cc483, including unmerged changes, rather than the published npm package. It is not an official leaderboard result.

• The difference is +4.2 percentage points with a 95% confidence interval of [−1.9, +10.2] (task-level paired bootstrap). The interval includes zero, so this is not a statistically significant improvement.

• OMK cost about 23% less per trial but was slower: 482 s median per trial against 376 s.

• Audit corrections: trials that tried to read Terminal-Bench sources or answers score 0, which turned 4 mini-swe-agent passes and 1 OMK pass into failures. prove-plus-comm is excluded from both sides because our OMK adapter failed to start in that task's working directory. Two transient provider errors were retried; no trial was excluded.

• OMK failed all three pytorch-model-recovery trials because the CLI rejected an instruction starting with a dash and a space (fixed in #84). Without that task the difference is +5.4 pp [0.0, +10.7].

• Not a leaderboard run: 3 trials instead of the official 5, our own network allowlist and apt cache proxy, and OMK alone had 150 s extra for a workspace snapshot used in rescoring.

• Costs count only the graded attempt, excluding prior failed retry attempts and 42 auxiliary model calls made by code inside one mini-SWE-agent task. They are not total experiment spend.

Method, per-difficulty results, audit and reproduction notes: Terminal-Bench 2.1 report.

Editable figure · Original report review

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

OMK's provider-neutral coding-agent CLI also exposes a multi-agent control plane for explicitly configured workflows. The stages describe 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.

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.

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

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

npm install omk-agent-core
npm install omk-ai
npm install omk-protocol
omk install npm:[email protected]
npm install omk-tui

Repository understanding

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.

Prior art

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.

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.5.10
• Latest public release: GitHub Releases. The source-version notes linked above can describe a candidate until its tag workflow completes.

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

What is OMK?

OMK (Open Multi-Agent Kit) is an open-source coding agent CLI for the terminal. It reads files, edits code, and runs commands in your repository. You can switch models inside one session, add subagents when a task needs them, and use /goal verify so a goal only counts as done when your chosen check passes. It is MIT-licensed and written in TypeScript.

How do I install OMK?

With Node.js 22.19 or newer, run npm install -g open-multi-agent-kit --ignore-scripts, then omk in your project. Without Node.js, use the standalone installer on macOS or Linux: curl -fsSL https://github.com/dmae97/omk/releases/latest/download/install.sh | sh. See Quick start.

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

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.5.10

Fixed

• Bound adaptive-effort tool-call deduplication state. If its limit is reached, the adaptive wrapper passes through the configured reasoning effort for the rest of its lifetime; other limits may still apply.
• A compaction is no longer stamped earlier than the messages it covers when the wall clock steps backward (observed on WSL2 as ~6.8 second resyncs). Previously the compacted history's old usage still counted after compaction, so the next prompt was rejected with context_input_capacity_exceeded. The compaction timestamp now follows the newest message on its branch for steps up to one minute.
• Usage estimates, input admission and compaction gates now use active-branch entry order to distinguish covered messages from new responses. Assistant usage and overflow errors arriving after compaction while the wall clock is still recovering are no longer discarded as stale; repeated compactions are distinguished by entry ID even when their timestamps match.

Release notes live in RELEASE_NOTES_v1.5.10.md.

Release v1.5.9

Added

• A default-on deepseek_harness built-in for native DeepSeek and recognized DeepSeek model IDs on gateways. It adds scoped execution guidance and projects oversized successful tool results to Unicode-safe head/tail excerpts at 80% context pressure, preserving original session history. OMK_DEEPSEEK_HARNESS=0 independently disables it. No upstream runtime, credentials, session-log uploads, or protocol changes are introduced. See DeepSeek harness.
• Project context documents. omk init --project creates missing PRD.md, ARCHITECTURE.md, DESIGN.md, RULES.md, TASKS.md and PROGRESS.md without overwriting files, and the project-directory walk loads each once as context. A bare omk launch in an otherwise empty Git repository root creates them too; OMK_PROJECT_CONTEXT_BOOTSTRAP=0 disables that bootstrap. See User context setup.
• Acceptance diagnostics behind OMK_GOAL_DIAGNOSTICS (flag, default off, spec 094). After a failed /goal acceptance check, the repair follow-up carries a bounded excerpt of the check output anchored at the first error line, falling back to head/tail (#170).

Changed

• Seventeen OMK_* harness flags are now on by default: OMK_EDIT_DIAGNOSTICS, OMK_EXEC_TRUNCATE_MIDDLE, OMK_JSON_SESSION_INFO, OMK_GOAL_AUTONOMY, OMK_SKILL_ADMISSION, OMK_SKILL_AUTO_LOAD, OMK_EVIDENCE_LIFECYCLE, OMK_ADAPTIVE_EFFORT, OMK_DOMAIN_ROUTING, OMK_GOAL_OUTPUT_RECALL, OMK_LANE_READY_QUEUE, OMK_LANE_FAILURE_SCOPE, OMK_RTK_OUTPUT, OMK_SESSION_CONTROL, OMK_VERIFIED_MEMORY, OMK_RESPONSE_REASONING_CAP and OMK_PREFIX_BOUNDARY. Set any of them to 0, false or off to restore the 1.5.8 behavior; with all of them off the G0 session hash is unchanged. OMK_EVIDENCE_LIFECYCLE now deletes only verified goal-recall files (observe deletes nothing), subagent workers keep OMK_SKILL_AUTO_LOAD and OMK_ADAPTIVE_EFFORT off, and an unset OMK_SESSION_CONTROL never fails startup. There is no on/off benchmark for these defaults yet (#279, #281).
• Evidence receipts store commands verbatim. Command credential redaction and its credential preflight are removed; existing v3 receipts with commandRedaction and commandBinding remain readable. Keep secrets out of command lines and pass them through the environment or credential storage (#223).
• The GitHub Copilot default model is now gpt-6.1-sol. Copilot retired gpt-5.4, which left Copilot without an automatic default during first-run onboarding.

Fixed

• A durable goal whose approved acceptance check passed no longer stays active on a loaded host. The goal workspace binding now allows each git call 10 seconds instead of the 1.5 second per-bash-call bound, which git status could exceed and which then refused completion as an unavailable workspace scope. A git that hangs past the longer bound still fails closed; the bash tool scope keeps its 1.5 second bound.
• Repeated local skill searches reuse unchanged document term frequencies instead of tokenizing the entire catalog again. Changed bodies are retokenized, input bounds are revalidated, and scores, exclusions and ranking order remain query-specific.
• Local safe-context-window rejections during tool turns now enter bounded overflow compaction recovery instead of being classified as invalid provider responses. Auto-compaction opt-out and the hard input ceiling remain unchanged.
• A per-call bash timeout now also bounds the outer tool timer, so a requested timeout longer than the fixed 300 second limit is no longer cut short. Extension tools and session wrappers receive the same bound.
• Lock ownership no longer depends on the wall clock alone. The durable goal journal lock uses a 30 second stale window and a lost lock fails the write instead of crashing the process; the sync auth.json lock uses the same 30 second window as OAuth refresh, so a live refresh lock is no longer taken over; the trust store lock is reclaimed by owner pid and released only by its owner; and omk session doctor repair takes the session owner lease and refuses a live session with session_in_use.
• Goal evidence is pinned to its generation and a complete workspace scope, stale autocomplete acceptance is rejected, and next-suggestion cost ceilings, stream identity and request lifetimes are aligned.
• The status sidebar reads the current session's shared usage reader after /new or resume instead of the first session's.
• omk run cancel reads the run journal in reader mode, so an owner appending at the same time no longer makes it fail with integrity; persistent concurrent change reports concurrent_change.
• Durations, throttles, in-memory caches and deadlines now use a monotonic clock, so a wall-clock step (seen on WSL2) no longer makes them fire early, late or never. This covers the double Ctrl+C and Esc windows, the working timer, the bash output throttle, the subscription usage, diagnostics and workspace scope caches, edit diagnostic budgets, OAuth device-code polling and the TUI input drain. npm run check now rejects new wall-clock durations and proper-lockfile locks without an explicit stale window.

Security

• Goal-recall evidence deletion refuses to run when .omk/goals/recall or one of its parents is a symlink.
• npm audit --omit=dev is clean again. undici is updated to 8.12.3 (EventSource memory, SRI token and content-encoding advisories), and a root override moves zod to 4.6.7 for every SDK and the sandbox example (oversized constrained collection advisory; no fixed 3.x release exists).
• The optional Gondolin example now uses Gondolin 0.14.0 with undici 6.29.1. Gondolin no longer depends on node-forge, so the temporary CVE-2026-85393 runtime guard is removed; a regression suite replays the malformed signatures against Gondolin's real cached-leaf verification. The example now requires Node.js 22.19.0 or later. Replace previously copied example directories. See Gondolin signature security.

Release notes live in RELEASE_NOTES_v1.5.9.md.

Release v1.5.8

Added

• Goal autonomy behind OMK_GOAL_AUTONOMY=1 (flag, default off). /goal budget <usd|-> [<deadline ISO>|-] sets a user-only cost and deadline budget that includes subagent lane cost; the goal stops with budget-limit, deadline, outcome-unknown or scope-changed, steering pauses it, and only /goal resume restarts it. Stop reasons are custom entries; the omk.goal.v1 schema is unchanged (#266, #268).
• Strong-only skill auto-load behind OMK_SKILL_AUTO_LOAD (flag, default off), with an observe-only skill-autoload.jsonl log (#262).
• Evidence recall delete-after-use behind OMK_EVIDENCE_LIFECYCLE=delete (flag, default off; observe only records) (#263).

With all new flags off, behavior is the same as 1.5.7.

Fixed

• Evidence recall delete recovery can no longer fail session_start (#264).
• session_info JSON test no longer flakes (#265).

Changed

• Research count scripts for spec 117 and 119 on synthetic fixtures (#267), NaN/Infinity tolerance (#269), header comment fix (#271).
• Spec 118 D3 measurement addendum, design only (#272).
• AGENTS.md lists the goal autonomy flag.

Release notes live in RELEASE_NOTES_v1.5.8.md.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first, run npm run check and npm test before opening a pull request, and report security issues as described in SECURITY.md.

Star OMK

If a check-backed “done” is useful to you, a star on GitHub helps other developers find OMK.

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.

OMK + AdaptOrch

AdaptOrch is a separate, optional product and is not called by default. See OMK + AdaptOrch for the optional integration and TRADEMARKS.md for the name and marks.

License

MIT