README.md

omapi-overlay — a Nix flake overlay: stock omp, thin omapi wrap, skills input, optional Jev gates.

What it is · Quick start · Packages · Jev · Skills · Platforms · Status · Contributing

Wraps oh-my-pi (omp), itself a fork of Pi by @mariozechner.

---

This flake overlays stock omp with a thin omapi command, a skills flake input, and optional Jev gates for cursor-agent. Humans and widgets call omapi. There is no omp source tree in this repository.

What it is

	This overlay
Command you call	omapi
Engine	Stock omp — host omp / $OMP_BIN, or the documented release pin
Skills	Flake inputs.skills only
Jev	Optional jev-router + cursor-agent-jev (shadow by default)
Consume via	overlays.default, homeManagerModules.default, or packages.<system>.*

What it is not

Claim	Reality
An omp source fork	No omp sources here. Features come from upstream omp.
A rebuilt omp	The wrap is omapi. Install omp from omp.sh or use omapi-pinned.
A skills product repo	Skills are a flake input. This tree ships a bootstrap stub only.
A Jev lab or key store	The router is Choice-only. Keys stay in the process environment.

Quick start

From a clone:

nix build .#omapi
nix build .#jev-router
nix build .#cursor-agent-jev

Default omapi wraps a host omp (or $OMP_BIN). If neither is present, it exits 127 and tells you so.

To put the pinned upstream binary in the Nix store (~180–240 MB):

nix build .#omapi-pinned

Flake input (Home Manager)

{
  inputs.omapi-overlay.url = "github:VirtualMachinist/omapi-overlay";
}

{
  nixpkgs.overlays = [ inputs.omapi-overlay.overlays.default ];
  home-manager.users.you = {
    imports = [ inputs.omapi-overlay.homeManagerModules.default ];
    programs.omapi.enable = true;
  };
}

programs.omapi.enable installs omapi and, by default, jev-router and cursor-agent-jev. It also symlinks the skills input to ~/.config/omp/agent/skills.

Packages

Package	What it is
omapi	Thin wrap of host omp / $OMP_BIN. Fail-closed if neither exists.
omapi-pinned	Same wrap, targeting a fetchurl pin of oh-my-pi v18.2.6. Not omp source.
jev-router	Node router: asks Typesafe Choice, prints a JSON verdict. Loop-stop (continue / stop / escalate) plus jev-router --check for a shadow diff check.
cursor-agent-jev	Runs jev-router, then execs cursor-agent (cursor-agent must already be on PATH). Shadow never blocks; active honors continue/auto only.

Jev

Jev is a shadow-first decision gate in front of cursor-agent. Shadow logs a Choice and never blocks. TYPESAFE_API_KEY is runtime-only — set it in the process environment; the flake does not bake it.

# TYPESAFE_API_KEY must already be in the environment
JEV_MODE=shadow cursor-agent-jev "<intent>" -- <cursor-agent args>

Variable	Role
JEV_MODE=shadow	Default. Log the Choice; always run cursor-agent.
JEV_MODE=active	Honor continue / gate: auto only. stop / escalate exit 2 (no exec).
JEV_BYPASS=1	Kill switch: skip the router and run cursor-agent.
JEV_ROUTER	Override the router binary.
JEV_STEP_DIGEST	Optional step / trajectory digest for the loop-stop Choice.
TYPESAFE_API_KEY	Runtime only. @typesafe-ai/sdk reads it.

Missing key: shadow continues unclassified; active fail-closes (escalate / hold).

Loop-stop Choice is {continue, stop, escalate} over intent + optional digest. Thresholds: omapi-loop-stop-policy@1 (conf ≥ 0.6, p ≥ 0.55, margin ≥ 0.15). choice: escalate + gate: hold is HITL — not auto-retry. How to run: docs/SPIKE-loop-stop.md.

Shadow check

jev-router --check reads git-diff evidence, applies an available-gate, asks a Choice, then applies code thresholds. The result is findings, parked, and notChecked. Empty findings are not approval.

JEV_MODE=shadow jev-router --check --intent "<task>"
# or: --diff-file packages/jev-router/testdata/skip-marker.diff

Skill: skills-stub/check. How to run: docs/SPIKE-stanley.md.

Skills

Skills are a flake input — the sole source of truth. This repo ships skills-stub so the input is a valid omp skills tree (*/SKILL.md) on day one. The stub includes bootstrap and a shadow check skill (jev-router --check). Home Manager only symlinks that store path to ~/.config/omp/agent/skills. When you have a real skills repo, change inputs.skills.url and the lock; do not copy a second skills/ tree into this overlay.

Platforms

Declared systems: aarch64-darwin, x86_64-darwin, aarch64-linux, x86_64-linux.

System	omp pin (v18.2.6)	Availability
aarch64-darwin	omp-darwin-arm64	Pin present. No hosted runner in this workflow.
x86_64-darwin	omp-darwin-x64	Pin present. Evaluated against nixpkgs-26.05-darwin (nixpkgs 26.11 dropped Intel macOS). No hosted runner in this workflow.
aarch64-linux	omp-linux-arm64	Pin present. No hosted runner in this workflow.
x86_64-linux	omp-linux-x64	Pin present. GitHub Actions evaluates all four systems and builds overlay packages here.

If a future omp release drops a slice, packages/omp-pin.nix throws for that system. A skipped CI row is a skip with a reason, not a pretend build.

nix flake check and nix build .#omapi .#jev-router .#cursor-agent-jev do not download the pin. nix build .#omapi-pinned does.

Status

• Overlay packages evaluate on all four declared systems.
• CI on this repo runs the x86_64-linux job; the other three matrix rows skip (no matching hosted runner).
• omapi-pinned is opt-in (180–240 MB fetchurl).
• Jev defaults to shadow. jev-router --check is the shadow diff check; empty findings are not approval. Loop-stop is shadow-first; active stop/escalate do not exec.
• Skills ship as skills-stub until you swap the input URL.

Contributing

Issues and pull requests are welcome. Match CI from a clone:

nix flake check -L
nix build -L .#omapi .#jev-router .#cursor-agent-jev

Do not commit secrets. TYPESAFE_API_KEY and other keys belong in the process environment, not the flake.

Credits and license

MIT. This overlay wraps stock oh-my-pi (omp). omp is a fork of Pi by Mario Zechner.

• GitHub
• Upstream omp
• omp.sh