Jevia
Jevia is an open-source, local-first, outcome-based model router for coding harnesses. It chooses a capability tier for each task, applies your safety policy, and uses recorded execution history and optional outcome feedback for future routes.
Use it with Claude Code, Codex, OpenCode, Gemini CLI, Cursor Agent, or a custom harness. Recording does not require extra tests or manual feedback; it is not tied to one programming language, model provider, or agent runtime.
CLI/core 0.1.9 improves harness-aware routing, recording reliability, and history memory use. The separately versioned Node SDK remains at 0.1.3 and supports this release. Passive recording remains available since CLI 0.1.6 and Node SDK 0.1.2. CLI 0.1.4–0.1.5 enabled extra test discovery by default; 0.1.6 makes it opt-in. Back up history and upgrade all clients sharing a store together before writing schema-6 records.
Jevia is experimental. The CLI, typed routing contract, local outcome store, harness adapters, and Node.js SDK are available today. A managed control plane is not part of this repository.
Why Jevia
Most routers stop after choosing a model. Jevia closes the loop:
task -> route -> harness -> automatic observations -> future routing context
+ optional feedback / verification -> known outcomes
- Adaptive: passive history and optional known outcomes inform later routing.
- Model-agnostic: stable tiers map to whichever models your harness exposes.
- Harness-agnostic: use the CLI directly or embed the typed Node.js SDK.
- Local-first: policy, cache, and history stay in your project or database.
- Explicit: your verifier or feedback decides success; Jevia does not grade its own work.
Quick start
Install the checksum-verified macOS or Linux binary without Rust or Cargo:
|
On Windows, use PowerShell 5.1 or newer:
irm https://jevia.dev/install.ps1 | iex
Initialize a project and check the full routing path:
For route-only integrations, optionally report a known result after executing the
work externally. This is not a required step after jevia run:
jevia doctor checks local configuration and storage without making a Jev API
request. jevia check performs one live routing round trip without saving a
synthetic run.
New SQL records and updates use the same 8 MiB per-record limit (including the newline) as JSONL recovery files. Export and archive refuse oversized legacy records without publishing a partial snapshot or deleting history. Those records remain readable; use a database-native backup before repairing them, never truncate the source to force an archive.
Run any harness
Jevia returns a capability tier. Your adapter maps that tier to a concrete model and command for the harness you already use. Start from a built-in shell-free template for Codex, Claude Code, OpenCode, or Gemini CLI:
Presets supply only the executable and argument shape; model IDs, credentials,
permissions, and verification remain yours. For any other harness, use explicit
--command and repeated --arg values as shown in the
adapter reference.
Setup previews the configuration first. Review it, repeat with --apply, then
run a routed task:
Jevia routes, executes, and records this run automatically. No manual feedback
or runs complete step is needed. Extra verification is opt-in: a process exit
remains an observed fact, not proof of task success. Existing explicitly enabled
checks are preserved. See the automatic CLI pipeline.
CLI 0.1.9 supports Claude Code 2.x >= 2.1.212, tested Codex 0.158.x
on macOS/Linux, and OpenCode v1 >= 1.18.33. Codex hooks require normal /hooks
trust review. It records reported models and tool/turn activity without storing
prompts or tool contents. Unsupported versions/remote sessions keep process facts.
Coverage is best-effort, not a claim that every model attempt or successful fix is
known. See native capture limits.
Upgrade to CLI 0.1.9 for these capture fixes. Preview Codex's
one-time hook review with jevia harness review codex, then add --launch to
review it interactively. After a real run, jevia harness health codex --require-events fails if the latest stored native capture is absent or partial.
The live smoke check tests actual
providers and preserves its recordings; it does not treat an exit code as proof
that events were captured. Older published binaries have different version gates.
Harness and verifier processes are launched directly without shell interpolation. Credentials remain in the environment instead of the project configuration.
Node.js SDK
With SDK 0.1.2 and CLI 0.1.6+, apps can optionally call recordExecution() with
finished execution facts and bounded events. Saved observations automatically
inform subsequent routes; feedback and extra verification remain optional.
jevia run already records automatically. See the
SDK recording example.
Use the typed jevia package when your application owns harness execution:
import { JeviaClient } from "jevia";
const jevia = new JeviaClient({ cwd: process.cwd() });
const route = await jevia.route("fix the flaky integration test");
const result = await runYourHarness({ tier: route.tier });
// Optional: report a known outcome from your own adapter; no verifier required.
if (result.outcome === "success" || result.outcome === "failure") {
await jevia.feedback(route.run_id, result.outcome);
}
// Recorded observations and eligible outcomes inform the next route automatically.
const next = await jevia.route("investigate another integration failure");
The SDK calls Jevia's shell-free JSON interface, so CLI and programmatic usage
share the same policy, storage, caching, and outcome rules. The CLI must already
be installed and available on PATH. Feedback and verification are optional:
skipping feedback leaves the outcome unknown, while future routes still use
recorded CLI observations and other eligible outcomes. No history argument or
manual fetch is needed. The SDK does not instrument an externally launched agent
merely because your application called route().
Routing explanations
Use jevia route "task" --explain or jevia run agent "task" --explain to
inspect cache behavior, the counts of known outcomes and passive observations,
and confidence fallback. Diagnostics go to stderr; JSON output stays unchanged.
These are observed routing facts, not the model's internal reasoning. See the
routing explanation reference.
Documentation
- Product documentation — install, adaptive routing, harness integration, SDK usage, outcomes, and operations.
- Complete CLI and operations reference — command details, storage migration, recovery, caching, and retention behavior.
- Architecture — component boundaries and routing invariants.
- Example configuration — tiers, cache, harness mapping, and verification.
- Node.js package reference — typed client API.
Run jevia <command> --help for command-specific options.
Development
Run the website separately:
See CONTRIBUTING.md for contribution and commit conventions.
License
MIT