omk CLI reference

omk exposes a workflow CLI for knowledge artifacts. Top-level commands cover the full loop: init (initialize an omk project) · install (install the official omk Agent Skill) · doctor (LLM health audit) · eval (offline A/B) · observe (online trace) · evolve (auto-iterate a skill) · sample (generate or fill test cases) · studio (browse local conversations, task trajectories, and knowledge-artifact reports).

omk init

omk init [dir]

Flags:

  --force           Allow overwriting existing project scaffold files in the target directory
  --lang <value>    Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --samples <3|20>  Number of first-party starter samples: 3 for a quick run, 20 to meet the default heuristic evidence floor

For full descriptions: omk init --help.

Initializes an omk project in the target directory: knowledge artifacts to measure (today skills/<name>/SKILL.md) plus their eval samples (eval-samples.json) — the per-directory workspace that omk eval / doctor / evolve / observe all operate on. Like a git repo, you have one per measurement target (the sample set is the measurement context, so it travels with the artifact, not globally). The default three-case A/B template is a low-cost workflow check; --samples 20 selects the first-party starter pack that meets the default heuristic evidence floor, not an a priori power plan. Starter samples are marked llm-generated and must be reviewed or replaced before serving as release evidence. The scaffold written to disk — both starter SKILL.md files, .omk/.gitignore and the starter sample pack — is generated in the resolved output language (--lang / OMK_LANG / saved settings / system locale), so an English run yields English prompts and English rubric criteria; the sample code, assertions and weights are identical in both languages. Existing scaffold files are never overwritten unless --force is explicit.

omk install

omk install omk-agent-skill            # built-in official omk Agent Skill (onboarding)
omk install omk-agent-skill --to codex
omk install ./skills/review            # install a local skill
omk install git:main:skills/review     # install from a ref of the current repo (SHA is immutable, a branch drifts)
omk install ./skills/review --dest ~/.my-agent/skills

Flags:

  --dest <value>     Custom skill root; a skill installs into <dir>/<name> (the built-in omk-agent-skill into <dir>/omk).
  --dry-run          Print install targets without writing files.
  --force            Overwrite an existing skill at the target location.
  --git-ref <value>  Remote git ref (branch / tag / SHA), default HEAD. Only with --git-url.
  --git-url <value>  Remote git repository URL (https / ssh / git@host:path). When set, the positional arg is the in-repo skill path (spec).
  --kind <skill>     Artifact.kind to install. Optional; only skill is supported.
  --lang <value>     Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --to <auto|codex>  Install target: auto (default, detect Codex/AGENTS) or codex (install directly).

For full descriptions: omk install --help.

Installs a knowledge input (skill) and distributes it to local supported coding-agent targets. Three sources: the built-in id omk-agent-skill (onboarding for the official omk Agent Skill), a local skill path (a directory or a .md), and git:<ref>:<spec> (a skill at a ref of the current repo). A registry / marketplace (resolving package names against a registry) is a non-goal.

Only skill is installable; --kind skill is optional. The default auto target writes to Codex/AGENTS when ~/.codex or ~/.agents is a directory. Use --to codex to install there without prior detection, or --dest for a custom skill root. Target lists are not accepted. See the upgrade guide when updating older scripts.

omk doctor

omk doctor                              # audit current dir / ./skills
omk doctor skills/v1.md                 # audit one skill file
omk doctor skills/ --json > r.json      # JSON for CI / external tools
omk doctor --gate; echo $?              # silent gate; exit 1 on fatal failures, warnings do not block
omk doctor --repeat 1                    # single quick pass (no sampling/merge, cheapest)
omk doctor --static-only                 # static checks only: no LLM, no samples — structural + body-deps

Flags:

  --concurrency <value>  Concurrency across the repeated passes. Default = --repeat (full parallel; passes are independent, cuts wall-clock). Set 1 for serial. Cost unchanged; only raises peak concurrency (lower it if rate-limited).
  --dimensions <value>   Custom dimensions config file (YAML), appended after builtin 7. Each is either promptSection (LLM audit) or endpoint (POST skill snapshot to your service). Note: endpoint sends the full SKILL.md + sub-files to that URL — only enable for trusted configs/URLs.
  --effort <value>       LLM reasoning effort: low / medium / high / xhigh / max.
  --executor <value>     Executor name. Defaults to codex inside Codex tasks; OMK_EXECUTOR sets an environment preference. A test fixture path is also accepted in tests.
  --fix                  Interactive fix: use LLM agent to fix skill issues reported by doctor.
  --gate                 Silent mode: only emit stderr summary on fail. Exit code carries the signal.
  --global               Write to global ~/.oh-my-knowledge/doctor instead of project .omk/doctor
  --json                 JSON output to stdout, for CI / external script consumption.
  --lang <value>         Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --model <value>        LLM model name. Codex reads the local configured model; OMK_MODEL sets an environment preference.
  --output-dir <value>   Report output dir, default project-level .omk/doctor (--global for global).
  --repeat <value>       Health-check repeat count (self-consistency). Default 2: runs 2 passes in parallel, unions findings, merges same root cause via an LLM pass, tags k/N support. Set 1 for a single quick pass (no sampling/merge, cheapest).
  --static-only          Static checks only (no LLM, no samples.json): readability / frontmatter / existence of scripts·CLI·files·env referenced in the skill body. For CI without LLM creds / offline.
  --timeout <value>      Single-session LLM timeout sec, default 600 (10 min).

For full descriptions: omk doctor --help.

By default doctor runs static rules first (skill readability, frontmatter, body dependencies), then the LLM health audit. A single LLM session emits per-dimension grades, findings, and suggestions for the 7 builtin dimensions; results are sorted fail→warn→pass→skipped with errors first within each dim. Dimensions are extensible — call registerHealthDimension in your own code and the new section is folded into the same LLM call's prompt and report (order = registration order). To browse a visual report, run omk studio and pick the latest run.

Custom dimensions via --dimensions <yaml>: each entry is either an LLM dimension (promptSection — folded into the health LLM call) or an endpoint dimension (endpoint — doctor POSTs the skill snapshot to your service and maps the response). The two are mutually exclusive per dimension. Endpoint dimensions are "online" checks (run alongside the LLM audit), letting you do deep checks that prompts can't express — e.g. calling an external security-audit service.

dimensions:
  # LLM dimension
  - id: tone-check
    displayName: Tone check
    severity: warn
    promptSection: Check that the skill copy is polite and unambiguous.
  # endpoint dimension
  - id: deep-security-audit
    displayName: Deep security audit
    severity: fatal
    endpoint: https://my-service.com/audit   # POST here
    headers: { Authorization: "Bearer xxx" }  # optional auth headers
    params: { env: production }               # optional, passed through verbatim
    includeFiles: true                        # optional (default true): bundle references/scripts
    maxFileBytes: 204800                      # optional: per-file byte cap (default 200KB; larger files truncated)
    maxTotalBytes: 2097152                    # optional: total files byte cap (default 2MB; collection stops beyond)
    allowPrivateHost: false                   # optional: allow private/loopback endpoint (default false — refused to prevent SSRF)

Request body (doctor → endpoint): { dimensionId, params, skill: { name, content, skillRoot, ref, files } } — files is a relative-path → content map of the skill's sub-files (text only; each file is truncated at maxFileBytes, default 200KB, and the whole files payload is capped at maxTotalBytes, default 2MB — both overridable per dimension). Response (endpoint → doctor): { status: "pass"|"warn"|"fail", message: string, hint?: string, detail?: object }. Any network error / non-2xx / protocol violation maps to a fail so problems surface instead of silently passing. Response fields are size-bounded before landing in the report (long message / hint truncated; oversized detail replaced with { truncated: true, preview }).

Endpoint URL validation: only http / https schemes are accepted, and endpoints pointing at private/loopback hosts — localhost, *.local, ::1, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (including cloud metadata 169.254.169.254) — are refused by default: doctor sends the full skill snapshot to the endpoint and echoes its response into the report, which would otherwise make it an SSRF vector. Set allowPrivateHost: true on a dimension to opt in for a trusted internal service. This is a literal hostname check (defense-in-depth) — no DNS resolution is performed, so a public domain resolving to a private IP (DNS rebinding) is out of scope.

Sampling & consensus: by default omk doctor runs the audit --repeat 2 times in parallel, takes the union of findings, and merges same-root-cause findings (across differing wording) via one extra LLM clustering pass, tagging each finding with k/n support (how many of the n passes reported it). This makes repeated runs converge instead of surfacing a different subset each time. Set --repeat 1 for a single quick pass; raise it for a deeper, more stable audit. --concurrency throttles the parallelism (default = --repeat).

Static-only checks (--static-only): runs only the same static lint rules included in default doctor with zero LLM calls and without loading samples.json — skill readability, frontmatter validity, and whether scripts / CLIs / files / env vars referenced in the skill body exist. Useful for CI nodes without codex, or offline debugging. The samples-contract check is intentionally excluded (it needs samples.json); it stays as omk eval's pre-evaluation gate, alongside the same dependency check enriched there with the samples' declared requires.

omk eval

omk eval --control baseline --treatment my-skill                # single-skill necessity test (baseline = reserved "no skill" variant)
omk eval --control code-review-v1 --treatment code-review-v2    # multi-variant A/B
omk eval --config eval.yaml
omk eval --batch
omk eval gold compare <run-id> --gold-dir gold-dataset \
  --target <id> --evaluator <id> --metric <id> --minimum-alpha <value>

Runs the offline evaluation, applies the verdict gate, persists the report, and returns a ship/no-ship exit code. Bootstrap CI is enabled by default on this workflow.

eval gold compare is a separate, exploratory post-hoc calibration. --minimum-alpha is optional; when supplied, OMK assesses the Krippendorff alpha confidence-interval lower bound against that explicit threshold. Without it, the assessment is inconclusive with gold-agreement-threshold-not-configured—OMK does not assume a universal reliability cutoff. The v2 interval follows Krippendorff's reliability bootstrap: it resamples paired observed disagreement while holding expected disagreement fixed from the original ratings, so degenerate draws are not silently discarded. Perfect observed agreement has a structured “bootstrap not applicable” state rather than a fabricated interval. This assessment does not rewrite the run's preregistered release verdict or change the command's exit status.

Flags:

  --batch                         Batch mode: baseline vs each skill; repeat must be 1
  --bootstrap                     Add bootstrap CI
  --bootstrap-samples <value>     Bootstrap resamples, default 1000
  --budget-per-sample-ms <value>  Per-sample time cap ms (must be > 0; omit for no cap)
  --budget-per-sample-usd <value> Per-sample budget cap USD (must be > 0; omit for no cap)
  --budget-usd <value>            Total budget cap USD (must be > 0; omit for no cap)
  --concurrency <value>           Concurrency, default 1
  --config <value>                eval.yaml path
  --control <value>               Control variant expr (artifact identity only)
  --control-cwd <value>           Runtime context dir for control
  --dry-run                       Plan only, no real exec
  --effort <value>                Executor LLM reasoning effort low/medium/high/xhigh/max (default low; reports across efforts not strictly comparable).
  --executor <value>              Executor: codex / codex-sdk / openai-api / custom executable file path (not a command string with arguments). Defaults to codex; OMK_EXECUTOR sets an environment preference.
  --global                        Write report to global ~/.oh-my-knowledge/eval instead of project .omk/eval
  --gold-dir <value>              Gold dataset dir
  --holdout-ratio <value>         Holdout fraction 0-1 (e.g. 0.3); splits a holdout subset, compares train/holdout composite to flag overfitting
  --judge-models <value>          Judge config: executor:model[,...], e.g. codex:<model> or openai-api:<model> (≥ 2 = ensemble). Defaults to the selected executor and evaluated model.
  --judge-repeat <value>          Judge each dim N times
  --lang <value>                  Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --layered-stats                 Emit layered stats
  --mcp-config <value>            MCP config path
  --model <value>                 Evaluated model
  --no-debias-length              Disable length-debias (default on)
  --no-diagnostic                 Disable the diagnostic projection over Core failures, missing evidence, exclusions, and stable reason codes.
  --no-gate                       Disable verdict gate
  --no-judge                      Skip LLM judge
  --no-serve                      Do not start report server
  --no-strict-baseline            Disable baseline isolation
  --output-dir <value>            Report output dir (default project .omk/eval)
  --repeat <value>                Predeclare the independent run count for the Evaluation Series
  --report-only                   Produce the report and print verdict, but always exit 0 (no CI gate).
  --resume <value>                Reuse a fully verified Core runId; fail closed when rejected
  --retry <value>                 Per-sample retry count
  --samples <value>               Samples path. Auto-discovers eval-samples.json / eval-samples.yaml at project scope or for a single directory-skill treatment; an explicit path may be a JSON / YAML file or split directory.
  --skill-dir <value>             Skill dir, default skills
  --skip-connectivity             Skip LLM connectivity preflight
  --skip-doctor                   Escape hatch: skip the doctor health-check gate (on by default). Use when sandbox mocks supply deps; caller owns garbage-in risk.
  --strict-baseline               Force baseline isolation (default true)
  --threshold <value>             Verdict threshold, default 3.5
  --timeout <value>               Per-sample timeout sec, default 120
  --treatment <value>             Treatment variants, comma-separated (artifact identity only)
  --treatment-cwd <value>         Runtime context dirs for treatments, comma-separated, index-aligned with --treatment (blank = none)
  --trivial-diff <value>          Trivial diff tolerance; 0 disables tolerance
  --verbose                       Verbose logging

For full descriptions: omk eval --help.

--repeat creates one preregistered Evaluation Series with a fixed number of independent Runs. Set the count before looking at results and report every member Run. It is not safe to keep launching new Runs after an unfavorable verdict and stop at the first favorable one; that is unadjusted optional stopping. --retry is separate and applies only to operationally failed sample attempts under the sealed retry policy.

Studio opens the validated Core run rather than a second report model. The run detail projects operational, evidence, and conclusion status separately; shows numeric observations, Analysis results, Decision reason codes, cost, coverage, and provenance; and links every view back to immutable Core artifacts. Diagnostic post-processing is limited to authenticated Core failures, missing evidence, exclusions, and stable reason codes. For the sandbox-mock semantics behind mocks / environment / tripwire / mocksStrict, see Sample design guide · sandbox fields.

omk observe

omk observe defaults to the skill-health report. Subcommands also support the observation inbox (ingest / inbox / show), knowledge maintenance (knowledge) and cross-window entity-link review (entity-links).

A. Skill-health report (default)

# ChatGPT desktop / Codex CLI
omk observe ~/.codex/sessions --last 7d

# Claude Code
omk observe ~/.claude/projects/-Users-you-Documents-my-project
omk observe ~/.claude/projects/my-project --last 7d
omk observe ~/.claude/projects/my-project --from 2026-04-01T00:00:00Z --to 2026-04-15T23:59:59Z
omk observe ~/.claude/projects/my-project --skills audit,polish
omk observe ~/.claude/projects/my-project --kb /path/to/project

Flags:

  --from <value>        Start time ISO, overrides --last
  --global              Write to global ~/.oh-my-knowledge/observe/health instead of project .omk/observe/health
  --kb <value>          KB root, enables KB-aware analysis
  --lang <value>        Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --last <value>        Time window (7d / 24h / 30m)
  --output-dir <value>  Health report output dir, default project-level .omk/observe/health (--global for global)
  --skills <value>      Filter to specific skills, comma-separated
  --to <value>          End time ISO

For full descriptions: omk observe --help.

Normalizes real Codex rollouts, Claude Code and OpenClaw sessions, and markdown conversation logs into source-neutral Trace IR, then produces skill-health reports: knowledge usage, gap signals, execution stability, tokens, and latency. This is production observation, not production scoring.

B. observe inbox: reviewer loop

Parses, aggregates, and de-noises real session traces into a per-observation list a human can review. The base pipeline is local-only and LLM-free; --llm-enhanced-review is an explicit optional model call.

# 1. Parse traces, aggregate signals, write to .omk/observe/inbox/
omk observe ingest ~/.codex/sessions
omk observe ingest ~/.claude/projects/my-project
omk observe ingest ~/.claude/projects/my-project --output-dir ./custom-dir

# 2. Read the inbox (default: top 20, sorted by severity / confidence / lastSeen)
omk observe inbox
omk observe inbox --limit 50
omk observe inbox --skill audit                    # filter by skill
omk observe inbox --by-skill                       # rollup view (one row per skill)
omk observe inbox --explore 10                     # sample 10 long-tail items from medium/low
omk observe inbox --explore 10 --include-noise     # explicitly include the noise bucket
omk observe inbox --llm-enhanced-review            # run LLM enhanced chain review explicitly
omk observe inbox --json                           # JSON output for automation

# 3. Inspect a single observation with its event triplet (surrounding messages)
omk observe show <inbox_id>

observe inbox --json returns an object with schemaVersion: 1. The existing kind identifies the view: observe-inbox-query (items), observe-inbox-by-skill (rows), or observe-llm-enhanced-review (records). Empty results use the same envelope. Consumers that reject unknown fields must allow schemaVersion; existing result fields and persisted observation files are unchanged.

Every observation carries:

• confidence and attributionConfidence — signal credibility plus skill-attribution credibility, displayed side by side
• severityReasonCode — stable structured reason code for the assigned severity; human-readable reasons are generated by CLI / studio rendering
• messageWindow — 3 messages before / trigger / 3 messages after, plus resolutionAfter (whether the agent recovered)
• evidence.{messageIndex,messageUuid,toolUseId} — anchors for round-tripping back to the original jsonl

Persisted experience reports use schemaVersion: 4: the timeline evidence kinds gain observed_effect — a file change the runtime observed, shown as its own row rather than folded into the tool call that triggered it, because most such changes are command side effects instead of model-initiated edits. Reports written in an older scheme such as 3 are no longer read: re-run omk observe on them to refresh. Review state is stored separately and timeline row ids derive from the evidence itself, so re-running re-attaches reviews to the same evidence and no dual-read branch is kept.

Supported trace formats: Codex rollout JSONL (.jsonl), Claude Code session JSONL (.jsonl), Qoder session JSONL (.jsonl), OpenClaw session JSONL (.jsonl), and markdown conversation logs (.log).

C. Knowledge maintenance

omk observe knowledge captures sources locally, generates candidates with the selected model, and supports entity/knowledge review, revisions and source inspection. schema and study are zero-model-call inspection operations; generate sends selected content. Follow the knowledge maintenance guide, including its capability tiers, and inspect omk observe knowledge --help for operation-specific flags.

D. Cross-window entity-link review

omk observe entity-links previews source/configuration locally, explicitly sends one confirmed propose invocation, and retains human accept/reject decisions. Matching names do not merge identities; failure or unknown execution does not authorize a resend. Use the cross-window review steps and omk observe entity-links --help before dispatching.

omk agents

omk agents list                          # which coding agents are installed on this machine
omk agents list --json                   # full inventory report for scripts
omk agents collect --limit 40            # map their session logs into unified Trace IR
omk agents extract --session <runId>     # draft candidate knowledge from one collected session

Flags:

  --dir <value>                Inventory and collection dir; defaults to the global ~/.oh-my-knowledge/observe/agents.
  --end-record <value>         extract: last record index, inclusive.
  --executor <value>           extract: generation executor, using OMK runtime configuration.
  --generation-policy <value>  extract: complete generation-policy JSON; omitted means one invocation. Bounded retries require explicit invocation and token budgets; the policy sets the output cap.
  --json                       Print complete JSON instead of a readable summary.
  --knowledge <value>          extract: knowledge workspace; defaults to the global knowledge dir.
  --lang <value>               Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --limit <value>              Per-run session file cap for collect.
  --model <value>              extract: generation model, using the configured model.
  --session <value>            extract: a runId from the collection report.
  --start-record <value>       extract: zero-based nonempty record index, inclusive.

For full descriptions: omk agents --help.

list reads the agent registry against your PATH and home directory and writes inventory.json. The registry is the built-in entries merged with a local extension file, ~/.oh-my-knowledge/agents.json (contract agent-catalog-v1): declaring your own host's install directories and log roots there makes it detectable and collectible without changing code, and an extension entry with the same identity replaces the built-in entry wholesale. Built-in entries cover public products such as Codex, Claude Code, Qoder and OpenClaw. collect walks each installed agent's declared log roots, parses every session log into the same Trace IR that observe uses, and writes one normalized artifact per session under ~/.oh-my-knowledge/observe/agents/traces/<agentId>/<traceId>.json, plus collection.json (contract agent-collection-v2) describing what was found, collected, skipped and failed. It is incremental: a file whose digest and mtime already appear in the previous report is skipped, so a second run normally collects nothing new. extract archives one collected session as an evidence snapshot and asks the configured executor for candidate knowledge — the same entities / evidence contract as omk observe knowledge.

Records the adapter cannot turn into events no longer share a single count. collection.json buckets them per session: unknownEventCount is unsupported format — the adapter cannot read the record at all, which is a real capability gap; duplicateViewCount is duplicate view ignored — another view already carried the same fact, or the record is a cumulative snapshot, so mapping it again would double count and no event is produced on purpose. A second write is now matched by native identity: mapped events record every call and item id they saw in sourceIds, and the per-family count ceiling is only the fallback when identity cannot be established. unmappedEvidenceCount is evidence pending mapping — the record family is recognized but what event it should become is undecided, and the raw record stays in the artifact. Families whose semantics are decided no longer sit in that bucket: Codex FileChange becomes observed_effect (an effect the runtime observed, not a model-initiated call, so it never enters tool counts), SubAgentActivity becomes agent_activity, entering review becomes lifecycle, web search now carried by Extension reuses the WebSearch mapping, and a shell result view's exit code and duration merge into the tool_result of the same call — when one bridge call runs several commands, each result view attaches only when exactly one call contains its commands, durations sum across that group, and the exit code is filled only when every member reports one and the group agrees, otherwise omitted rather than guessed. When one raw record exceeds 8 KB the artifact keeps only a leading excerpt plus its byte count and digest, while the family name and the record's own id always survive: the log file remains the evidence, addressed by sourceIndex and the session's sourcePath. The buckets are disjoint and add up to the single unrecognized total this report used to print; merging a gap and a deliberate omission into one number would suggest you had seen everything. Bucketing is a collection-time derivation, and its scheme version is recorded in unknownDispositionRulesVersion: when the previous report uses a superseded scheme such as agent-collection-v1, its counts are not carried over, the run recollects everything, says so in limitations, and replaces the old file wholesale rather than migrating it field by field; extract refuses a superseded report instead of refining from stale counts.

Two properties are deliberate. Detection never executes a detected binary — installation is inferred from the filesystem and PATH only, so an inventory run cannot trigger third-party code. Collection never moves, truncates or deletes a log you own: originals stay where they are and remain the evidence, while every derived artifact is written on the OMK side. Capacity ceilings (files per run, bytes per run, bytes per file) are enforced rather than guessed at; when a ceiling cuts a run short, the run stops cleanly and says so in limitations, so a truncated count is never presented as complete.

The extension file has exactly the built-in registry's capabilities: its fields are product names and home-relative paths, with no absolute-path field and no way to execute anything. A missing file simply means "no extension entries", but a file that exists yet cannot be read, is malformed JSON, or points outside your home directory fails the run. A partial registry would silently drop a host from the inventory, so this path chooses failure over continuing.

The Agents page in omk studio (/agents) renders exactly these two reports: which agents are installed, where their logs live, how many sessions and events were collected, how the unrecognized records split across the three buckets, and which counts were cut short by a capacity ceiling. The page never rescans your machine and offers no collect or extract buttons — those stay commands you run, so refreshing a page cannot change the evidence.

omk evolve

omk evolve <skill>                  # multi-round auto-iteration on a skill
omk evolve skills/foo.md --rounds 10 --target 4.5

Flags:

  --concurrency <value>           Eval concurrency, default 1
  --edit-budget <value>           Max fraction of skill lines a round may change (default 0.2). Over-budget candidates are rejected before evaluation, saving eval cost
  --effort <value>                Reasoning effort: low/medium/high/xhigh/max
  --executor <value>              Executor name. Defaults to codex inside Codex tasks; OMK_EXECUTOR sets an environment preference.
  --improve-mode <agent|rewrite>  Improvement strategy (default: agent)
  --improve-model <value>         LLM that rewrites the skill; defaults to the evaluated model
  --judge-models <value>          Judge model (single judge required), executor:model format. Defaults to the selected executor; Codex reuses the evaluated model.
  --lang <value>                  Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --model <value>                 Evaluated LLM. Codex reads the local configured model. Also used to generate samples when none exist.
  --no-edit-budget                Disable the edit budget (allow arbitrarily large single-round edits)
  --no-reject-memory              Disable rejected-edit memory (do not feed rejected edits back into the next prompt)
  --rounds <value>                Max iteration rounds, default 5
  --samples <value>               Existing sample source; otherwise discover skill-local then project samples, generating only when neither exists
  --skip-doctor                   Skip doctor gate (escape hatch; user takes garbage-in risk)
  --snapshot-only                 Produce candidates under evolve/ without writing the source. By default, write back only after a final Core gate passes.
  --target <value>                Target composite score; stop when reached. If omitted, runs all rounds.
  --timeout <value>               Per-sample timeout sec, default 600

For full descriptions: omk evolve --help.

Auto-iterates a skill through repeated eval → judge → rewrite loops until it hits --target or exhausts --rounds. Cost scales with rounds × samples × variants; a typical run takes minutes to tens of minutes. Original skill files are versioned under skills/evolve/*.r0.md.

The CLI completion summary reports the whole evolve process cost: rewrites, optional sample fixes, and all evaluations performed during selection. In the merged evolve report, meta.totalCostUSD is deliberately narrower: it is the measurement cost represented by the retained round results. The end-to-end amount is persisted separately as meta.evolve.processCostUSD. Either value is a lower bound when its corresponding *CostReported flag is false.

omk evolve is a one-shot loop: it runs the doctor gate before each round by default (--skip-doctor to bypass), and if the target skill has no eval samples yet, it auto-generates a batch first (equivalent to running omk sample) before evolving. So for a brand-new skill, omk evolve skills/foo.md alone walks the full "doctor → generate samples → self-iterate" path. Existing samples are used as-is, never regenerated.

--snapshot-only leaves the source unchanged and keeps the winning version under evolve/ for you to review and apply manually.

The default agent mode uses prompt omk.evolve-agent/v2: the model returns omk.skill-edits/v1 JSON ({"summary":"…","edits":[{"oldText":"…","newText":"…"}]}), and OMK applies unique text matches to a candidate in memory. Custom executors that previously edited files directly must return this response instead. Invalid or unchanged candidates consume no additional evaluation calls. The rewrite mode still returns the full skill text and keeps its existing prompt.

The baseline snapshot preserves source bytes exactly, including leading and trailing whitespace; measurements that formerly trimmed this whitespace need a new baseline. Directory candidates inherit assets from the accepted snapshot. Before final evaluation and writeback, OMK checks that the original carrier, including its assets, is unchanged. Only a passing final Core decision permits atomic source publication; a detected concurrent change leaves the source untouched and candidates under evolve/. Publication preserves permissions and symlink targets, using same-filesystem temporary files under the carrier-excluded .omk/ directory.

omk sample

omk sample <skill>                  # generate or fill eval-samples test cases for one skill
omk sample --batch                  # generate for skills missing eval-samples

Flags:

  --append                    Append newly generated samples to the existing samples file (colliding sampleId auto-suffixed, original json/yaml shape kept). Single-skill mode only; not supported with --batch / --from-traces. Without it, an existing file errors out. Often paired with --focus.
  --batch                     Batch mode: scan --skill-dir, generate samples for any skill missing them.
  --count <value>             Number of samples to generate. Defaults to LLM auto-selection by skill type.
  --executor <value>          Executor name. Defaults to codex inside Codex tasks; OMK_EXECUTOR sets an environment preference.
  --focus <value>             Generation focus (NL hint). Steers LLM toward certain sample types.
  --from-traces               from-traces mode: recycle observe-inbox failure signals into draft regression samples (provenance: production-trace) for review.
  --lang <value>              Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --model <value>             Generation LLM model name. Codex reads the local configured model; OMK_MODEL sets an environment preference.
  --no-mock                   Skip mocks. Automatically enabled when the executor cannot intercept tools, preventing impossible mock_hit assertions.
  --observations-dir <value>  Observe inbox dir (from-traces mode), default project .omk/observe/inbox.
  --skill <value>             Only draft from observe-inbox signals for the specified skill (from-traces mode only).
  --skill-dir <value>         Skill root dir, default skills. Used by batch mode.

For full descriptions: omk sample --help.

One-shot generation. Auto-stamps provenance on generated cases. Generated assertions use English, numbers, or code tokens so they compare cleanly across bilingual outputs.

omk studio

omk studio
omk studio --port 7799
omk studio --host 0.0.0.0                          # LAN access (default: 127.0.0.1)
omk studio --reports-dir ~/.oh-my-knowledge/eval
omk studio --observations-dir .omk/observe/inbox    # observe inbox data directory
omk studio --no-open
omk studio --port 7799 --takeover                  # explicitly replace a verified OMK listener

Flags:

  --agents-dir <value>        Agent inventory / collection reports dir (optional, default global ~/.oh-my-knowledge/observe/agents, where `omk agents` writes)
  --analyses-dir <value>      Observe-health reports dir (optional, default project .omk/observe/health, falls back to global)
  --dev                       Dev mode: child process with hot reload
  --doctors-dir <value>       Doctor reports dir (optional, default project .omk/doctor, falls back to global)
  --global                    View only global eval, observe/health, doctor, and observe/inbox directories under ~/.oh-my-knowledge/
  --host <value>              Bind address, default 127.0.0.1 (or OMK_REPORT_HOST). 0.0.0.0 / :: explicitly exposes to the network
  --lang <value>              Output language zh|en. Priority: CLI > OMK_LANG env > saved settings > system locale > zh.
  --no-open                   Do not auto-open browser
  --observations-dir <value>  Observe-inbox data dir (optional, default .omk/observe/inbox)
  --port <value>              Listen port, default 7799. Pass 0 for OS-assigned
  --reports-dir <value>       View only this Core reports dir (optional; default aggregates current project + global)
  --takeover                  Explicitly replace a verified OMK service on the same address/port; by default, port conflicts fail without stopping it

For full descriptions: omk studio --help.

Starts the local knowledge workbench. The homepage indexes local Codex conversations directly and prioritizes running work. Select a conversation and task to inspect its four-lane Task Trajectory, then cross-check the semantic trajectory against knowledge access, normalized events, and source records. Running tasks support live following; stale unclosed tasks are labeled End status not recorded. This browsing path does not require omk observe ingest first.

The primary navigation is Observe → Measure → Knowledge, with page routes /observe, /measure, and /knowledge. Observe lists conversations and task trajectories; Measure presents Core evaluations; Knowledge provides the library, candidate review, and carrier maintenance, with doctor and observation records available as needed. Visit /observe/inbox for the observation reviewer queue. Old page addresses are no longer served. CI gates use omk eval's exit route, while automation should read the Core report artifacts.

Studio defaults to loopback and has no built-in authentication. Choosing --host 0.0.0.0 explicitly exposes its data and mutation APIs to the network; access control belongs to the deployment's trusted network or authenticated proxy. All responses set nosniff, Referrer-Policy: no-referrer, and a CSP that blocks base-URL changes and plugin objects while supporting Next scripts and host embedding. JSON APIs reject oversized bodies immediately with 413 and close unfinished request connections.

Port conflicts (BREAKING-CLI): startup now fails without probing or stopping the existing listener, including another project's OMK service. Stop it yourself or choose another port. Only explicit --takeover permits replacement: the service at the same address and port must answer the OMK health check and acknowledge shutdown; neither request follows redirects. Unverified services are never stopped. This policy also applies to evaluation previews; they do not automatically take over a running Studio. Development mode forwards --takeover only when you pass it.

The startup URL comes from server.start() and uses the actual bound port. The separately printed listener address may be a wildcard (0.0.0.0 or [::]), which is not a browser destination. For wildcard listeners, Studio also prints non-internal interface candidates matching the bound address family, with bracketed IPv6 addresses. These are network interface candidates, not a claim of LAN or public reachability: routing, containers, NAT, and firewalls still determine access. Use the printed local URL on this machine; an explicit interface bind prints that interface's actual address.