OMK//CONTROL — the provider-neutral multi-agent control plane for coding workflows.

자유는 제약의 부재가 아니라, 보장의 존재다.
Freedom is not the absence of constraints — it is the presence of guarantees.

Models execute. OMK routes, verifies, measures, and controls.

New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See CONTRIBUTING.md.

Most ways of running an AI coding agent force you into one of two cages.

The walled garden. One vendor's model, one vendor's tools, one vendor's rules. You are a tenant inside someone else's runtime, and your "freedom" ends exactly where their API does.

The chaos box. A model that can run anything, verify nothing, and still cheerfully declare done while the build is on fire. Unlimited power, zero accountability.

OMK hates both. We think an operator should be free to use any model, any skill, any workflow — and free to actually trust the result. OMK is the control plane that makes those two freedoms compatible.

Every freedom OMK hands you is guarded by a constraint that keeps it honest. These constraints are not cages — they are the rails that make the freedom safe to use at full speed.

That is the whole thesis in one line: models execute; OMK routes, verifies, measures, and controls. The model's freedom to act is bounded by the operator's freedom to know what actually happened.

Ten short captures of the control plane doing its job.

These are stylized terminal animations representative of the real flows — the live OMK//CONTROL TUI is even busier.

One global install, one omk, and the control plane wires the DAG scheduler, arms the evidence ledger, discovers 822 skills, connects 20 MCP servers, and registers every provider you own.

!omk plan turns a fuzzy objective into a bounded DAG: owned paths, ordered waves, and an acceptance predicate attached to every node before a single line of code is written.

!omk-loop fans independent work out across concurrent lanes on the resource-claim DAG. Independent work runs in parallel; conflicting and unknown operations stay sequential. Every lane lands an evidence receipt.

Providers stay interchangeable. The Bayesian router and refusal-learner pick the best arm for the task, but the execution, evidence, and operator model never change when you swap models.

The Correctness Wall intercepts the write and runs the acceptance predicates. One red predicate blocks completion — a green-looking reply is never a release signal.

!skill: routes to the right lane and loads the minimum necessary — usually one to three skills. A skill is loaded when it earns its place in the task, not because it happens to be installed.

/mcp reports the health and latency of every configured server. The control plane sees every integration — there are no silent failures.

/compact runs context-budget v2 with headroom: raw tokens are compressed while the goal, the checkpoint, and the evidence are preserved. Compact context, full memory of what matters.

omk session doctor detects unterminated turns and orphan results, then plans a dry-run repair against the tamper-evident replay ledger. An interrupted run is a recoverable state, not a loss.

Ship extensions, skills, prompts, and themes as ordinary pinned OMK packages. Extensibility without teaching every contributor a separate runtime.

npm install -g open-multi-agent-kit --ignore-scripts

Then run it:

omk --version
omk

Or without a global install:

npx --ignore-scripts open-multi-agent-kit

Library packages:

npm install omk-agent-core   # Agent runtime with tool calling and state management
npm install omk-ai           # Unified multi-provider LLM API
npm install omk-tui          # Terminal UI library with differential rendering

This is the home of the omk agent harness project including our self extensible coding agent.

• open-multi-agent-kit: Interactive coding agent CLI
• omk-agent-core: Agent runtime with tool calling and state management
• omk-ai: Unified multi-provider LLM API (OpenAI, Anthropic, Google, …)

To learn more about omk:

• Project demos from Mario
• Browse all public Skills
• Read the documentation, but you can also ask the agent to explain itself

The OMK//CONTROL startup surface is the default operator view. The header reads omk v<package.version> · OMK//CONTROL, using the installed workspace package version as its source of truth.

The default dark TUI theme uses the omk-control-grid-dark Night City palette and keeps the control sidebar focused on route, evidence, loop, MCP, runtime, skills, and context budget state.

OMK is not another model shell. It is the control plane around the models you already use: provider routing, scoped tools and MCP, evidence gates, parallel execution, and an operator-visible terminal surface.

Official skill distribution uses OMK packages. Build a package once, install it through omk, pin it, scope it to a project when needed, and enable or disable its resources from the same control plane. This README intentionally does not send users through a separate skills launcher.

# Global, pinned OMK package
omk install npm:open-multi-agent-kit@0.92.0

# Project-local, pinned Git package
omk install -l git:github.com/dmae97/open-multi-agent-kit@v0.92.0

# Inspect and control the installed resources
omk list
omk config
omk update --extensions

A skills-only package is an ordinary OMK package:

{
  "name": "omk-workflows",
  "keywords": ["omk-package"],
  "omk": {
    "skills": ["./skills"]
  }
}

Use the minimum necessary skills per turn—usually one to three. A skill is loaded when it earns its place in the task, not because it happens to be installed.

• Control, not lock-in. Keep providers interchangeable while retaining one execution, evidence, and operator model.
• Evidence before completion. A green-looking response is not a release signal; declared predicates and fresh verification are.
• Parallelism with boundaries. Independent work can run concurrently while owned paths, side effects, and evidence remain explicit.
• Extensibility without a fork. Ship skills, extensions, prompts, and themes as OMK packages instead of teaching every contributor a separate runtime.

The proof standard is operational: evaluate OMK against your own task completion, verification coverage, setup time, and recovery behavior. We do not claim an unmeasured benchmark win over another harness.

• Persistent GitHub star nudge on interactive startup: first installs and anyone who has not confirmed a star keep seeing a nag banner every launch until they star https://github.com/dmae97/omk and run /star (writes global githubStarred: true in ~/.omk/agent/settings.json). /star reset brings the nag back. Project settings cannot silence it.

Release notes live in RELEASE_NOTES_v0.94.1.md.

• diagnostics is now a default-active tool for new sessions (LLM-callable alongside read/bash/edit/write). It stays registered-but-inactive for sessions that pin their own tool list; opt out per session via activeToolNames or excludedToolNames.
• Persistent skill-catalog cache (src/core/skills-catalog-cache.ts): per-dir fingerprint walk (readdir/stat only) gates a JSON catalog at <agentDir>/cache/skill-catalog-v1.json. Repeat session starts skip all SKILL.md reads on unchanged trees (measured on this host: 105 ms cold → 41 ms warm for the full scan). Any add/edit/delete under a scanned tree invalidates exactly that dir; corrupt cache degrades to a clean miss. Atomic tmp+rename writes.
• Hermetic test environment (test/setup-env.ts): machine-level OMK_* and provider credential variables are scrubbed before every worker, so test results no longer depend on the developer shell (safety-gate suites saw env-disabled gates; live e2e suites ran against expired credentials instead of skipping). LIVE_E2E=1 keeps provider keys when running the live suites on purpose.
• diagnostics tool (src/core/tools/diagnostics.ts): compiler-backed diagnostics via the project's own checkers — tsc --noEmit, pyright/ruff, go vet, cargo check — normalized to SEVERITY path:line:col message, per-language fail-soft (skipped instead of tool errors), 5 s TTL cache, 50-item cap, path/language auto-detect. Registered in createAllToolDefinitions and exported from the SDK (createDiagnosticsTool, createDiagnosticsToolDefinition).
• Interactive sandbox promotion: session.setBashSandboxMode("audit" | "enforce" | "off") switches the session sandbox at runtime (next spawn), with a sandbox_audit mode-change ledger entry; session.bashSandboxMode reads the effective mode. SessionBashRuntime.setSandboxMode backs it.
• Default-on bash sandbox (opt-out). Session bash now carries a default audit-mode sandbox preflight (workspace-write rooted at the session cwd, OS temp dir as extra write target). Spawns stay unwrapped but every decision lands in the replay ledger as a sandbox_audit event — a tamper-evident trail no other harness ships. OMK_BASH_SANDBOX=enforce activates the real OS backend (macOS sandbox-exec / Linux bwrap, auto-detected) and fails closed when unavailable; =0 disables. New onSpawnDecision observer on BashSandboxPreflight, plus createWorkspaceSandboxPolicy() / resolveBashSandboxMode() SDK exports.
• Git-aware verified-bash scope. Session bash receipts now bind the git toplevel plus the sorted dirty set (staged/modified/untracked, capped at 32 paths, 1 s TTL cache) instead of an empty artifact set, so captureWorkspaceFingerprint records HEAD and a scope-limited dirty digest. Exported as resolveSessionWorkspaceScope().

• API provider registry is now a process-wide singleton (globalThis-anchored in omk-ai/api-registry). Symlinked workspace dist copies consumed natively and the same files inlined by vite-node used to keep separate registries, so registerFauxProvider (and any runtime registration) was invisible to streamers resolving through the other copy — surfacing as "No API provider registered for api: ..." in agent loops. Also removed a stale nested packages/agent/node_modules/omk-ai copy (0.92.0) that shadowed the workspace build.

• Extracted SessionCompactionService (src/core/session-compaction-service.ts): the compaction state machine — capture/lock, barrier evaluation, emergency tail repair, provenance capture, transaction begin, envelope commit — moved out of AgentSession (5,271 → 4,911 lines), which now delegates through thin one-line wrappers. Transaction symbols import from compaction/transaction.ts directly so the compaction/index.js vi.mock pattern in suites keeps working.

• Extracted SessionBashService (src/core/session-bash-service.ts): the full bash surface — executeBash (prefix/loadout/safety-floor/headless gate), recordBashResult with the streaming-deferral queue, abortBash, flushPending — moved out of AgentSession, which now delegates one line each. Ordering contract (queue while streaming, flush on turn end) is pinned by the bash-persistence suite.

• Extracted SessionBashRuntime (src/core/session-bash-runtime.ts) from AgentSession: verified-evidence executor, default sandbox preflight (audit/enforce), git-aware workspace scope, and the receipt-bound bash orchestration (executeVerified) now live in one lazily-initialized unit; the session delegates. No behavior change.

• Verified bash is default-on (opt-out). When an AgentSession has a replay ledger, LLM-callable bash and interactive/RPC executeBash bind through executeVerifiedBash (executor: "bash-tool", receipts under <sessionFile>.evidence). Set OMK_VERIFIED_BASH=0 for the legacy unverified path. Adapter gains env/onData fan-out and createVerifiedBashOperations() so session PI_* env and live streaming stay intact without import cycles. See SDK — Evidence and Environment Variables.

Release notes live in RELEASE_NOTES_v0.94.0.md.

• Ported upstream Pi 0.82.0 bash session environment: the LLM-callable bash tool now receives PI_SESSION_ID, PI_SESSION_FILE, PI_PROVIDER, PI_MODEL, and PI_REASONING_LEVEL (parent-env spoofing is stripped; disable per tool via createBashTool(cwd, { exposeSessionEnvironment: false })). See Environment Variables.
• Ported upstream Pi 0.82.0 bash_execution_update session events: direct RPC bash commands stream output chunks correlated with the command id. See RPC.
• Ported upstream Pi 0.81.1/0.82.0 summarization resilience: compaction and branch-summary calls now follow retry settings with exponential backoff (new summarization_retry_scheduled / summarization_retry_attempt_start / summarization_retry_finished session events, surfaced in TUI and RPC), run with prompt caching disabled, and use fresh routing session IDs. See Compaction.
• Ported upstream Pi 0.82.0 abortable provider retries in omk-ai: SDK-level retries are replaced by retryProviderRequest with abortable backoff sleeps, retry-after caps now fail fast instead of clamping, and transient DNS/transport errors are classified retryable.
• Subagent capability enforcement: agent frontmatter may declare skills/mcp/hooks plus enforceCapabilities: true to spawn with --no-skills + resolved --skill paths; enforceCapabilities now correctly parses YAML booleans/numbers/strings (parseEnforceFlag), the skill catalog scan skips archived corpus trees (e.g. system-prompts-leaks) so real skill names resolve to their real paths, and the MCP allowlist is synced to the live configured server set. Includes deterministic OMK-native domain profiles for the capability router and 16 coercion unit tests (examples/extensions/subagent/agents.test.ts).

• Fixed persisted compaction envelope validation rejecting every session compacted two or more times: the writer attests the kept-window slice from the previous compaction's firstKeptEntryId, but reopen validation required the full parent branch, so any twice-compacted session crashed on open with Invalid compaction envelope source. Validation now accepts either exact form (tamper-evidence unchanged); regression tests in test/session-file-compaction-window.test.ts.
• Ported upstream Pi 0.82.0 clipboard fix: await wl-copy exit status and fall through to xclip/OSC 52 on failure instead of claiming success fire-and-forget.

Release notes live in RELEASE_NOTES_v0.93.0.md.

If you use OMK or other coding agents for open source work, publish sanitized sessions from .omk/agent/sessions.

Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks.

For Slack/chat automation and workflow integrations, use OMK extensions and MCP servers.

AdaptOrch MCP is a separate, proprietary reliability-kernel service (not part of this monorepo) that OMK can route orchestration tasks through: topology-aware DAG routing, multi-model synthesis, and consistency verification. It is versioned 0.1.0 — an MVP stage — with a public-ready free Starter tier and paid Pro/Team tiers, and is backed by a published paper (arXiv:2602.16873).

The adaptorch and adaptorch-prod MCP servers plus the adaptorch-route and adaptorch-synthesize skills ship in OMK's default omk-core-verified execution preset, so they are available from the first prompt of a default session without extra setup. Actually invoking AdaptOrch (e.g. adaptorch_run) still requires an ADAPTORCH_CONTROL_PLANE_TOKEN (a dev token is auto-set for a local control plane at 127.0.0.1:8000) and follows normal task-routing rules rather than firing on every message.

This is distinct from packages/adaptorch-wpl in this monorepo, the stable Work Packet Loop package shipped as a runtime dependency of open-multi-agent-kit since v0.91.0 — see that package's own README for details.

OMK does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.

If you need stronger boundaries, containerize or sandbox OMK. See packages/coding-agent/docs/containerization.md for three patterns:

• OpenShell: run the whole omk process in a policy-controlled sandbox.
• Gondolin extension: keep omk and provider auth on the host while routing built-in tools and ! commands into a local Linux micro-VM.
• Plain Docker: run the whole omk process in a local container for simple isolation.

See CONTRIBUTING.md for contribution guidelines and development.md for project setup.

npm install --ignore-scripts  # Install all dependencies without running lifecycle scripts
npm run build        # Build all packages
npm run check        # Lint, format, and type check
./test.sh            # Run tests (skips LLM-dependent tests without API keys)
./omk-test.sh        # Run OMK from sources (can be run from any directory)

We treat npm dependency changes as reviewed code changes.

• Direct external dependencies are pinned to exact versions. Internal workspace packages remain version-ranged.
• .npmrc sets save-exact=true and min-release-age=2 to avoid same-day dependency releases during npm resolution.
• package-lock.json is the dependency ground truth. Pre-commit blocks accidental lockfile commits unless OMK_ALLOW_LOCKFILE_CHANGE=1 is set.
• npm run check verifies pinned direct deps, native TypeScript import compatibility, and the generated coding-agent shrinkwrap.
• The published CLI package includes packages/coding-agent/npm-shrinkwrap.json, generated from the root lockfile, to pin transitive deps for npm users.
• Release smoke tests use npm run release:local to build, pack, and create isolated npm and Bun installs outside the repo before tagging a release.
• Local release installs, documented npm installs, and omk update --self use --ignore-scripts where supported.
• CI installs with npm ci --ignore-scripts, and a scheduled GitHub workflow runs npm audit --omit=dev plus npm audit signatures --omit=dev.
• Shrinkwrap generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed.

MIT