This project lets a coding agent set up Jev routing for Codex. Jev can choose
a model and reasoning depth for a task when you select jev/auto; you can still
select a model yourself. The repository includes an installer, an embedded
router, and checks that report what actually worked on your computer.
Current status: public alpha. The installer supports a fresh Codex profile on macOS, Linux, and Windows. It cannot migrate an existing profile or replace an existing router. An agent may run inside Codex, Claude Code, Gemini CLI, or another coding environment, but the installed integration currently targets Codex only.
The current source release is v0.1.0-alpha.1. See the changelog for routing changes and verification limits.
You need:
- Codex CLI, Python 3.11+, Node.js 22.19+, npm, and a supported per-user service
manager (
launchd,systemd --user, or Windows Task Scheduler). The gateway environment needs CPython 3.10–3.14; uv can provide Python 3.12. - A TypeSafe or OpenRouter API key for Jev's routing decisions. The installer asks for it in a hidden terminal prompt and stores it outside this repository.
- A fresh Codex profile and free service ports. If your intended profile or router is already in use, the agent should stop and explain the conflict.
- A Codex/ChatGPT sign-in if you plan to use native GPT models. You complete sign-in and approve session sharing yourself after installation.
OmniRoute is optional. If you already have a working OmniRoute gateway, the installer can connect to it using a protected auth file. During installation you choose your own provider/account order and model mappings, or supply an existing protected configuration. See provider configuration. If you do not have one, choose no and use native Codex routing. This installer does not create an OmniRoute gateway or provider accounts.
Send the agent the repository link and this request:
Install
https://github.com/teo-nex/jev-codex-harnessfor a fresh Codex profile. ReadAGENT_INSTALL.mdandAGENTS.mdfirst. Check my intended profile, service ports, prerequisites, and disk space before changing anything. Stop and tell me if migration of an existing profile or router is needed; do not silently pick another profile. Run the interactiveonboardinstaller for a fresh profile. Ask me whether I already have OmniRoute and let me choose my provider order and exact model IDs. Let me enter the TypeSafe or OpenRouter key only in the local hidden prompt, never in chat. Afterwards, tell me what passed, what remains untested, and which steps I must complete in Codex before calling the installation working.
The agent performs preflight, preparation, a dry run, installation, and local verification. It cannot approve Codex hooks, sign in to your account, or grant native session sharing on your behalf. Those steps require your review.
On macOS or Linux:
git clone https://github.com/teo-nex/jev-codex-harness.git
cd jev-codex-harness
./install.sh onboardOn Windows, in PowerShell:
git clone https://github.com/teo-nex/jev-codex-harness.git
Set-Location jev-codex-harness
.\install.cmd onboardThe Windows .cmd entry point also works with the default Restricted PowerShell
execution policy; it does not change that policy. install.ps1 remains available
where script execution is already enabled.
The wizard asks for a fresh profile path, whether your Jev key is from TypeSafe or OpenRouter, and whether to use an existing OmniRoute gateway. For OmniRoute, it can build your protected provider sequence interactively. It checks for structural blockers before asking for the key. Keep the checkout at a stable path: installed services and hooks refer to it. See the installation guide for non-interactive commands, protected files, and rollback.
- Open a fresh Codex session in the installed profile. Use
/hooksto review and trust the new hooks. - Sign in if needed. For native GPT routing, explicitly enable session sharing
for this profile as described in the installation guide:
python -m harness.cli --codex-home PROFILE session status, then, after owner approval,python -m harness.cli --codex-home PROFILE session enable --allow-sharing. Use the harness's Python and replacePROFILEwith the installed path. - Select
jev/autowhen you want automatic routing. Your previous default model is preserved, so the installer does not switch you tojev/auto. - From the repository root, run
python3 -m harness.cli --codex-home /path/to/new-profile verify --live --manual-model MODEL_IDwith a model available to that profile (py -3instead ofpython3on Windows). The installation guide explains what each check proves.
A green installer result means the local files and services passed their checks. Call the setup verified only after a real response completes through the intended Codex profile. Browser, Computer, and context-compaction behavior need separate checks in a client that exposes those capabilities.
- A Codex adapter and installer for fresh profiles on macOS, Linux, and Windows.
- A local Jev router with native Codex routing and an optional user-configured OmniRoute provider order. Reasoning profiles can map Jev's chosen effort to supported levels on each configured destination model.
- An optional CanvasTTY browser broker on macOS when its helper is already installed. CanvasTTY and visible terminal workers are not installed by this kit.
- Coding workers through the Codex CLI on macOS, Linux and Windows, with
explicit
allowed_files, deterministic write guards and Jev patch review. CanvasTTY is not required. See worker permissions. - An optional 30-minute idle compaction launcher for managed Codex CLI or configurable stdio clients, independent of model choice. It does not attach to existing desktop chats or replace their launchers.
- A 24-hour API-price comparison after real routed work. It estimates what the observed tokens would cost at listed API prices; it does not measure money paid, subscription savings, or equal task quality.
The support matrix shows what has and has not been tested on each operating system. GitHub Actions runs offline installation checks with synthetic credentials on all three. CI does not prove a first installation with your credentials, hook trust, OAuth, or a completed live model response.
Run commands from the checkout with python -m harness.cli --codex-home PROFILE.
Use py -3 instead of python on Windows.
For catalog queries, also supply --omniroute-auth-file FILE before the
subcommand, or set JEV_OMNIROUTE_AUTH_FILE to that protected file's path.
| Control | Command or configuration |
|---|---|
| Provider/account order and models | routes show, routes apply --config FILE, routes reorder ID ... |
| Safe edits and recovery | Config validation, durable backups, crash recovery, routes rollback |
| Advertised model IDs | catalog, routes check --catalog; warnings for missing IDs and cross-family aliases |
| Request diagnostics | explain: route, requested/effective effort, attempts and timings without prompt or credential export |
| Project restrictions | Native-only, allowed providers, no paid fallback, required final Astra |
| Failure handling | Connection/first-token/idle/total/attempt budgets and isolated account/model cooldowns |
| Acceptance | acceptance --offline-recovery; live response/tool/effort checks require explicit --live |
Project policies, request budgets and failure cooldowns are described in Providers. Opt-in fresh-client acceptance is documented in Installation; offline versus live evidence is recorded in Improvements.
- Agent installation protocol and adapter contract
- Installation details, CI scope, and support matrix
- Reasoning effort routing and source provenance
- Provider/model routing audit
- Security policy and contributing guide
The guarded Jev coding workers implementation is included in the XERJ Corpus Hub with author attribution.
The root project is MIT licensed. The embedded router retains its own MIT license and attribution. Keep API keys, OAuth files, provider state, and runtime logs out of Git.