oh-my-field — Evidence-backed agent capability packaging

See It Work · In 10 Minutes

Same model. Same input. One capability makes the difference.

Two self-contained demos record a stronger run, promote it into a capability, then hand that capability to a smaller target model. The bare target prompt fails the contract — the same target with OMF passes.

Input task/messy_orders.csv 8 rows · 4 should survive

order_id,customer,email,amount,ordered_on,fulfilled
 1003 , Alice Park ,Alice.Park@Example.COM ,"$1,200.50",12/31/2025,Yes
1001,Bob Lee,bob@foo.io ,$99.9,2025-01-05,no
                                                       ← blank row, dropped
1002, Carol Diaz,carol@bar.com,"2,000","Jan 5, 2026",TRUE
1001,Bob Lee (resubmit),bob2@foo.io,$5.00,2025-02-02,y ← dup order_id, dropped
1005,Dan,,$10.00,03-15-2026,1                          ← no email, dropped
,Eve,eve@baz.com,$50,2026-04-01,0                      ← no order_id, dropped
1004, Frank Wu , FRANK.WU@MAIL.com ,1200,2026-02-20,

The contract: shape {"records":[…]} · exactly six keys · ISO dates · numeric amount_usd · boolean fulfilled · lowercased emails · blanks, dupes & rows missing order_id/email dropped · sorted by order_id. Easy to almost get right — which is exactly why a bare prompt fails the contract.

FAIL

Bare Haiku

Same model, prompt only — no capability.

[
  {
    "order_id": "1003",
    "customer": "Alice Park",
    "email": "Alice.Park@Example.COM",
    "amount": "$1,200.50",
    "ordered_on": "12/31/2025",
    "fulfilled": "Yes"
  },  ← + dup 1001, blank & no-email rows kept
]

$ python check.py … FAIL: <root>: type list != dict

PASS

Haiku + OMF capability

Same model, now carrying the distilled Opus run.

{ "records": [
  {
    "order_id": 1003,
    "customer": "Alice Park",
    "email": "alice.park@example.com",
    "amount_usd": 1200.5,
    "ordered_on": "2025-12-31",
    "fulfilled": true
  }  ← 4 of 8 rows, sorted by order_id
] }

$ python check.py … PASS: output matches the golden normalized.json

4 / 4 PASS with capability

1 model · Haiku, unchanged

0 mocks · real omf CLI

$ omf import-run claude_code --log opus_run.log \
    --goal "normalize a messy orders CSV into strict JSON" \
    --model claude-opus-4-1 --outcome success
$ omf promote $EVIDENCE_ID --name csv_normalize
$ omf health csv_normalize

Three real steps — import the recorded run as evidence, promote it into a capability, check its health — then run the dual test.

bash examples/10min-happy-path/run.sh

View the example

Practical finance workflow

Codex portfolio backtest: gpt-5.5 → gpt-5.4-mini

The finance variant swaps CSV cleanup for a six-month portfolio backtest. OMF carries the rebalance-cost, drawdown, volatility, and Sharpe calculation details from a stronger Codex run to a smaller target model.

FAIL

Bare Codex gpt-5.4-mini

Same portfolio case, no capability contract.

# Portfolio Backtest Report

Summary table produced,
but required lines are missing:
- Period: 2026-01 through 2026-06
- Strategy: 60.00% US Equity / 30.00% Core Bonds / 10.00% Gold
| 2026-04 | -3.14% | $983,663.77 | -3.14% | $5.78 |

$ python check.py … FAIL: missing required backtest result lines

PASS

Codex + portfolio_backtest

Same model, now carrying the distilled gpt-5.5 run.

- Ending value: $1,018,749.79
- Total return: 1.87%
- Annualized volatility: 7.58%
- Sharpe ratio: 0.52
| 2026-04 | -3.14% | $983,663.77 | -3.14% | $5.78 |

$ python check.py … PASS: report contains the required portfolio backtest results

6 monthly rows checked

10 bps rebalance cost modeled

0.52 Sharpe ratio contract

$ omf import-run codex --log gpt55_run.txt \
    --goal "produce a portfolio backtest report" \
    --model gpt-5.5 --outcome success
$ omf promote $EVIDENCE_ID --name portfolio_backtest
$ TARGET_MODEL=gpt-5.4-mini TARGET_REASONING=medium \
    bash examples/10min-codex-backtest/run.sh

The checker rejects missing rows, duplicate rows, and conflicting metrics, so the demo succeeds only when the target report satisfies the backtest contract.

bash examples/10min-codex-backtest/run.sh

View the finance example

The Problem

Agent work should compound, not disappear.

Strong agent runs contain domain context, safe commands, validation checks, failures, human decisions, and artifacts. Too often that knowledge is trapped in a chat transcript or terminal log.

oh-my-field turns "the agent did this once" into "this team can reuse and verify this capability again."

Without OMF

Agent run

Chat history

Gone

With OMF

Agent run

Evidence

Capability

Reuse

What OMF Is

A packaging and verification layer around external agents.

OMF is not an agent runtime. Codex, Claude Code, Hermes, Pi, Odysseus, OpenCode, or your own agent does the real work. OMF records, packages, and tracks portability.

01

Capture evidence

Import logs, diffs, test results, command history, user feedback, and generated artifacts from real agent work.

02

Promote capability

Structure repeatable work into runtime-neutral instructions, context policy, harnesses, provenance, and review metadata.

03

Validate transfer

Keep format conversion separate from actual target-side validation so teams can prove portability instead of assuming it.

Capability package capabilities/<name>/

capability.yaml Canonical metadata & provenance

instructions.md Runtime-neutral agent instructions

harness.yaml Verification & approval boundaries

README.md Human-readable capability card

contracts/ Task, artifact, validation & replay contracts

validators/ Generated contract validator

CLI-first surface

Install, activate, and start packaging work.

Persistent CLI install

$ pipx install oh-my-field
$ omf --help

Try without installing

$ uvx oh-my-field --help

Agent activation

$ omf install skill --runtime codex
$ omf install skill --runtime claude_code
$ omf install skill --runtime hermes
$ omf install skill --runtime pi
$ omf install skill --runtime opencode
$ omf install skill --runtime odysseus --project /path/to/odysseus

MCP-capable clients

$ omf install mcp --client codex
$ omf mcp serve

One-step runtime adoption

$ omf runtime install codex
$ omf runtime conformance codex

Development install

$ git clone https://github.com/Baekpica/oh-my-field.git
$ cd oh-my-field && uv sync --all-extras --dev
$ uv run omf --help

Product Flow

From one useful run to a portable capability.

Click any step to see the corresponding OMF commands. The cycle runs automatically.

Agent runtime

Codex, Claude Code, Hermes, Pi, Odysseus, OpenCode, a local agent, or another external runtime does the work. OMF observes and records without replacing the runtime.

Codex Claude Code Hermes Pi Odysseus OpenCode Generic MCP stdio

Import run / capture evidence

OMF preserves logs, diffs, checks, decisions, and artifacts as immutable, hashed evidence. Runs can be tracked live (agent-assisted) or imported from existing artifacts after the fact.

Promote capability package

The repeatable parts become a runtime-neutral package with instructions, context policy, harnesses, and integrity metadata. Not just a prompt — a full evidence-backed capability card.

Export, adapt, validate

The capability is exported to a target runtime, imported into a project, and validated by an actual target-side run. Exported ≠ imported ≠ validated — OMF tracks each state separately.

omf init

$omf init

✓ Initialized .omf/ in current directory

$omf install skill --runtime codex

✓ Skill installed → AGENTS.md patched

Command Reference

Every command, at a glance.

The full OMF CLI, organized by workflow stage. All commands share the same omf entry point.

omf initSetup

Create the repo-local OMF field. Writes .omf/config.yaml, .omfignore, and all artifact directories.

omf init

omf doctorSetup

Inspect and validate the current field configuration and artifact integrity.

omf doctor

omf --versionSetup

Print the installed OMF version as a root option. Add --json for machine-readable output.

omf --version
omf --version --json

omf install skillActivation

Install the OMF meta-skill for a target agent runtime so the agent knows when and how to call OMF during ordinary work.

omf install skill --runtime codex
omf install skill --runtime claude_code
omf install skill --runtime hermes
omf install skill --runtime pi
omf install skill --runtime opencode
omf install skill --runtime odysseus --project /path/to/odysseus
omf install skill --runtime generic

omf install mcpActivation

Patch a client MCP config and run the stdio server for agents that support structured tool calls.

omf install mcp --client codex
omf install mcp --client claude_code
omf install mcp --client hermes
omf install mcp --client pi
omf install mcp --client opencode
omf install mcp --client odysseus --project /path/to/odysseus
omf install mcp --client generic --scope export --out .omf/mcp.json
omf mcp serve

omf runtime installActivation

Combine both activation steps for a runtime — controller skill plus MCP config in one command.

omf runtime install codex

omf runtime conformanceActivation

Verify the adoption surface: controller skill installed, MCP config present, omf on PATH, capability launchers installed, and imported targets validated.

omf runtime conformance codex

omf session startSession

Begin tracking a new agent session. Returns a session_id used for all subsequent event recording.

omf session start \
  --runtime codex \
  --model gpt-5.5 \
  --goal "triage repository issue"

omf session eventSession

Append a structured event. Types: goal, assumption, context, command, diff, test_result, artifact, user_feedback, decision, completion.

omf session event <session_id> \
  --type command \
  --summary "Ran the test suite" \
  --command "uv run pytest" \
  --exit-code 0

omf session finishSession

Mark session outcome and close it for materialization.

omf session finish <id> --outcome success

omf session materializeSession

Convert the finished session into an immutable, hashed evidence record.

omf session materialize <session_id>

omf session suggest-capabilitySession

Propose a reusable capability from a finished session before promoting the evidence.

omf session suggest-capability <session_id>

omf import-runSession

Import an existing agent run from logs, diffs, and test outputs — for when you only have artifacts after the fact.

omf import-run codex \
  --log run.log \
  --goal "triage repo issue" \
  --test-result pytest.txt \
  --outcome success

omf promoteCapability

Promote evidence into a runtime-neutral capability package under capabilities/<name>/.

omf promote <evidence_id> \
  --name repo_issue_triage \
  --description "Repository issue triage"

omf healthCapability

Check a capability's health, harness status, export/import/validation state, and suggested next action.

omf health repo_issue_triage

omf hardenCapability

Strengthen the capability's harness and eval cases based on accumulated evidence and failures.

omf harden repo_issue_triage

omf cardCapability

Render the human-readable capability card: purpose, source evidence, harness summary, portability status.

omf card repo_issue_triage

omf evalVerify

Run evaluation cases against a capability to check whether it still satisfies its harness.

omf eval repo_issue_triage

omf replayVerify

Replay a capability's harness checks against current state.

omf replay repo_issue_triage

omf learnLearn

Turn evidence and eval results into learning exports and reflection reports. Accumulated evidence becomes reviewable material, not silent training data.

omf learn repo_issue_triage
omf reflect repo_issue_triage

omf dataset-exportLearn

Emit JSONL from learning exports (fine-tuning), patch decisions (preference), and eval results. Only reviewed, passing runs become dataset entries.

omf dataset-export repo_issue_triage \
  --dataset-type all

omf capability exportPortability

Pack the canonical package into a portable .omfcap.tar.gz archive with package.yaml and MANIFEST.sha256 integrity metadata. Use --format dir for a directory export.

omf capability export repo_issue_triage \
  --target hermes \
  --out .omf/exports/rft-hermes

omf verify packagePortability

Verify an exported archive's manifest and integrity before importing it on the target side.

omf verify package \
  .omf/exports/rft-hermes.omfcap.tar.gz

omf capability unpackPortability

Inspect the contents of a .omfcap.tar.gz archive without importing it into a project.

omf capability unpack \
  .omf/exports/rft-hermes.omfcap.tar.gz

omf capability importPortability

Materialize an archive or directory package in a target project. Static --validate checks structure only — status stays needs_validation until a real run passes.

omf capability import \
  .omf/exports/rft-hermes.omfcap.tar.gz \
  --runtime hermes --validate

omf capability validatePortability

Validate with a real target run. Separates hard blockers from advisory portability risk; opt into the packaged contract validator with --run-contract-validator. Gates execution behind --approve-command-risk.

omf capability validate repo_issue_triage \
  --target hermes \
  --run-command "hermes-code --skill repo_issue_triage" \
  --run-contract-validator \
  --approve-command-risk

omf dashboardOperations

Serve the local operating dashboard (alias omf web): Overview, Runtimes, Capabilities, and Workflows tabs over a stdlib, CSRF-guarded HTTP server. No build step, no framework.

omf dashboard   # alias: omf web

omf inspectOperations

Inspect a capability or evidence record in detail.

omf inspect <id>

omf diffOperations

Compare two capability versions or evidence records side by side.

omf diff <id_a> <id_b>

omf explainOperations

Explain why a capability is in its current state. Alias: omf why.

omf why repo_issue_triage

Local Web UI · New in 0.3.2

See your whole field, not just your terminal.

OMF now ships a local operating dashboard — omf dashboard (alias omf web). A single-page UI with no web framework and no build step: it is stdlib-only, served on loopback, and every mutating route is guarded against CSRF and DNS-rebinding. Four tabs render focused slices of your field.

Before

CLI & JSON only

Capability health, portability status, and runtime adoption all lived behind omf health, omf inspect, and piped JSON.

$omf health repo_issue_triage --json

{ "status": "candidate",

"export": "exported",

"validate": "not_run" }

After

A visual operating dashboard

The same evidence, at a glance — metrics, runtime readiness, capability portability, and workflow runs. Live, themeable, local-first.

Capabilities4

Ready runtimes2

Harness pass100%

Runtimes6

127.0.0.1:8765 · oh-my-field operating dashboard

OMF dashboard Overview tab: live metrics for workflows, capabilities, harness pass rate, and ready runtimes.

OMF dashboard Overview tab (light theme): live metrics for workflows, capabilities, harness pass rate, and ready runtimes.

OMF dashboard Runtimes tab: skill and MCP adoption status for codex, claude_code, hermes, pi, odysseus, and opencode, each with preview and install actions.

OMF dashboard Runtimes tab (light theme): skill and MCP adoption status for codex, claude_code, hermes, pi, odysseus, and opencode, each with preview and install actions.

OMF dashboard Capabilities tab: per-capability health and the export, import, and validate portability matrix with inline actions.

OMF dashboard Capabilities tab (light theme): per-capability health and the export, import, and validate portability matrix with inline actions.

Runtimes tab

Adoption at a glance for every supported runtime — including OpenCode. Each card shows a local-presence probe plus skill & MCP status, with one-click preview/install. Detection reuses the conformance layer, so it never drifts from omf runtime conformance.

Capability portability

Per-capability health and the full export → import → validate matrix in one table — the same three independent status axes the CLI tracks, with inline export and validate actions.

Workflows & approvals

The Workflows tab tracks runs, the workflow graph, events, learning patches, and execution history — and surfaces approvals so risky commands stay record-don't-execute by default.

Local-first & safe

Served on loopback with a per-process CSRF token and loopback-only Origin/Host checks. Stdlib http.server, no framework, no build. The [web] extra is a documented marker — the UI works on a plain install.

$ pipx install 'oh-my-field[web]'   # quotes keep zsh from globbing the extra
$ omf dashboard                   # alias: omf web — opens http://127.0.0.1:8765

Portability Model

OMF separates conversion from proven reuse.

Four distinct states. "Can be exported" is not the same as "works on the target."

Exported

Packed into a canonical .omfcap.tar.gz archive.

omf capability export <name> --target <runtime>

Imported

Materialized inside the target project.

omf capability import <bundle> --runtime <runtime>

Validated

Passed a real target run or evaluation.

omf capability validate <name> --target <runtime>

Portable

Proven reusable in at least one target environment.

omf health <name>

Validation separates hard blockers (missing tools, unresolved remaps, failed runs, missing artifacts) from advisory portability_risk and validation_confidence. Only actionable blockers drive needs_adaptation; runtime/model/project differences lower the risk score but do not block validated.

Initial Users

Built first for technical workflows with concrete verification.

AI and agent engineers

Coding-agent power users

Infra and platform engineers

Small teams building reusable agent assets

Local and closed-network LLM users

Turn one-off agent work into reusable, verifiable,portable capabilities.