Jevia documentation

jevia harness presetsjevia harness setup codex --preset codex \  --model fast=your-fast-model \  --model balanced=your-balanced-model \  --model strong=your-strong-model

Built-in shell-free templates cover Codex, Claude Code, OpenCode, and Gemini CLI. A preset supplies only the command and non-interactive argument shape; you still choose model IDs, credentials, permissions, and verification. The preview is offline and changes no files.

Apply, validate, and run

# Review the generated TOML, then save itjevia harness setup codex --preset codex \  --model fast=your-fast-model \  --model balanced=your-balanced-model \  --model strong=your-strong-model --apply
# Validate templates and local executable paths without launching anythingjevia harness check codexjevia harness check codex --json
# Route and launch the configured harnessjevia run codex "investigate the failing integration test"

Changing an existing adapter also requires --replace. Extra arguments for the configured harness can follow -- on jevia run. Jevia executes argument arrays directly without shell expansion. Use explicit --command and repeated --arg values when a preset does not match your installed harness or when connecting another agent.

CLI 0.1.6: additional verification is opt-in. CLI 0.1.4–0.1.5 enabled test discovery by default; existing explicit checks are preserved. Set auto_verify = true only if you want root Rust/Node test discovery, or configure your own optional verifier. Recording itself works with Python, Go, and mixed-language projects without tests. Passing tests is evidence, not proof of every requirement.

CLI 0.1.6 native capture supports Claude Code 2.1.251+, tested Codex 0.158.x on macOS/Linux (with normal hook trust), and OpenCode v1 ≥ 1.18.33. Unsupported versions and remote sessions keep process-level observations. Capture is best-effort: reported models, switches, and tool activity do not prove which model solved a task. Raw prompts, tool contents, and transcripts are not retained. Inspect execution.observations for coverage and recorded events. Back up history and upgrade to CLI 0.1.6 and SDK 0.1.2 together for schema 6. See the capture contract and limits.

Optional verification runs when the agent process/session finishes, not after each internal message or tool call. Jevia does not install the agent or test runner, supply credentials, bypass agent permission prompts, or retry failed work. Prepare project dependencies first. See the CLI setup and verification reference for supported tests, deadlines, and opt-in settings.

import { JeviaClient } from "jevia";
const jevia = new JeviaClient({ cwd: process.cwd() });const task = "fix the flaky integration test";const route = await jevia.route(task);
const result = await runYourHarness({  task,  tier: route.tier,  runId: route.run_id,});
// Optional: your adapter may expose a known outcome; no verifier is required.if (result.outcome === "success" || result.outcome === "failure") {  await jevia.feedback(route.run_id, result.outcome);}
// Recorded outcomes are included automatically in the next decision.const next = await jevia.route("fix another parser regression");

SDK 0.1.2: optionally call recordExecution() after app-owned work finishes to save execution facts and bounded events. These are application-reported observations, not verified success. Later route() calls automatically reuse the history; feedback and extra verification remain optional. Exact retries are idempotent; existing supervised executions cannot be overwritten. Do not call this after jevia run, which records automatically. Requires CLI 0.1.6+ and SDK 0.1.2+ with schema 6. See the SDK recording example.

For SDK integrations, map Jevia's tier to your harness model and let your application run the work. Feedback and verification are optional. SDK routing does not launch an agent or run tests. If your application knows the result, it can report it without a verifier; no human feedback prompt is required. Skipping feedback still records the route with an unknown outcome and does not block later routing.

Your adapter can call Codex, Claude Code, OpenCode, Gemini CLI, Cursor Agent, Copilot CLI, Aider, Goose, Amp, or a custom runner. The optional result.outcome field above comes from your own adapter; Jevia does not infer it from a successful function return. Report only known outcomes, and do not submit feedback again after a supervised CLI run.

Unknown outcomes are not quality labels. Finished process-only runs still supply observations; active and routed-only runs do not. The SDK does not instrument agents your application launches outside jevia run. [router].history_limit bounds each history window: default 20, maximum 100, or 0 to disable it. This is decision context, not model training or a guarantee of better choices. Live requests send eligible historical task text, outcome metadata, and bounded native summaries to Jev; feedback reasons, session IDs, and raw event lists stay in storage. [privacy].store_task_text = false omits task text from new records, not older history or the current routing request.

The SDK invokes the local CLI through its shell-free JSON interface. Install the CLI first and keep it on PATH; npm installation never runs a binary downloader. Pass an AbortSignal in method options when the caller needs cancellation.

Configure storage from Node.js

// Relative paths resolve from the client cwd; absolute paths also work.const target = { backend: "sqlite", path: ".data/jevia/history.db" } as const;
// Preview only: no database connection or file changes.console.log(await jevia.setupStorage(target, { importJsonl: true }));
// Stop project writers and supervisors before applying.await jevia.setupStorage(target, {  apply: true,  confirmStopped: true,  importJsonl: true,});console.log(await jevia.checkStorage());console.log(await jevia.checkStorage({ deep: true }));

// Set JEVIA_DATABASE_URL before creating the client.const target = {  backend: "postgres",  project: "my-app",  urlEnv: "JEVIA_DATABASE_URL",} as const;
console.log(await jevia.setupStorage(target)); // Preview first.

Setup stays preview-first and returns human-readable reports. Keep database credentials in the named environment variable, use signal for cancellation, and raise the client's timeoutMs for large imports. After cancellation or failure, inspect the config and destination before retrying.

Cancellation and errors

import { JeviaClient, JeviaCommandError } from "jevia";
try {  await jevia.route(task, { signal: controller.signal });} catch (error) {  if (error instanceof JeviaCommandError) {    console.error(error.message, error.exitCode, error.signal);  }}

These commands are for externally executed work or corrections. A supervised jevia run records its outcome automatically; no manual feedback step is needed afterward.

jevia feedback <run-id> successjevia feedback <run-id> failure --reason "The integration test still fails"jevia feedback <run-id> unknown --reason "No reliable verification result"jevia runs show <run-id>

What a stored run looks like

Every backend preserves the same logical record. JSONL writes one compact JSON object per line to .jevia/runs.jsonl; this example uses explicitly enabled verification and is expanded for readability. SQLite and PostgreSQL store the equivalent fields while keeping the same lifecycle and outcome-evidence semantics.

{  "schema_version": 6,  "run_id": "7b65a69a-0a6f-4a89-bd73-88f090954dd9",  "tier": "balanced",  "suggested_tier": "balanced",  "confidence": 0.84,  "probabilities": {    "fast": 0.1,    "balanced": 0.84,    "strong": 0.06  },  "fallback_applied": false,  "jev_model": "jev-latest",  "created_at_ms": 1790700000000,  "source": "live",  "task": "fix the flaky integration test",  "outcome": "success",  "execution": {    "harness": "codex",    "model": "provider/standard",    "duration_ms": 48231,    "exit_code": 0,    "observations": { "source": null, "status": "unsupported", "events": [] },    "verification": {      "command": "pnpm",      "launched": true,      "duration_ms": 6842,      "exit_code": 0    }  },  "lifecycle": {    "state": "completed",    "started_at_ms": 1790700001120,    "finished_at_ms": 1790700056193  },  "outcome_evidence": {    "source": "verification",    "recorded_at_ms": 1790700056193  }}

Move a project to SQLite

# Choose a project-relative or absolute SQLite file; preview writes nothingjevia storage setup sqlite \  --path .data/jevia/history.db \  --import-jsonl
# Stop Jevia writers and supervisors, then apply the same reviewed pathjevia storage setup sqlite \  --path .data/jevia/history.db \  --import-jsonl --apply --confirm-stoppedjevia storage checkjevia stats

Without --path, SQLite uses .jevia/jevia.db. Relative paths resolve from the discovered project root, even when the command runs in a subdirectory; absolute paths are also accepted. Omit --import-jsonlwhen the current JSONL history is empty. The source file is never deleted or rewritten.

[storage]backend = "sqlite"url = "sqlite://.data/jevia/history.db"

Share evidence with PostgreSQL

export JEVIA_DATABASE_URL="postgresql://..."
# Preview first; the URL stays in the environmentjevia storage setup postgres --project my-project --import-jsonl
# Stop writers and supervisors before applyingjevia storage setup postgres --project my-project --import-jsonl --apply --confirm-stoppedjevia storage check

Keep credentials in the environment, never in config or CLI arguments. Pass--url-env MY_DATABASE_URL to name a different variable. Jevia requires a direct or session-pooled connection, not a transaction-mode pooler.

Check, export, and import

jevia storage checkjevia storage check --deepjevia storage export --output .jevia/snapshot.jsonljevia storage import-jsonl --from <file>jevia storage import-jsonl --from <file> --apply

Routing cache

jevia cache statusjevia cache clearjevia route --no-cache "force one live routing decision"

The default cache holds 256 decisions for 15 minutes. Each hit still gets a fresh run ID. New outcomes and policy, model, or harness changes produce new cache keys; cache errors fail open to a live routing request.

Run lifecycle and recovery

jevia run agent "fix the parser" --non-interactive --timeout-seconds 300 --verification-timeout-seconds 120

History maintenance

# Preview and repair a recoverable JSONL tailjevia runs repairjevia runs repair --apply
# Preview and archive older eligible terminal recordsjevia runs archive --keep 1000jevia runs archive --keep 1000 --apply