Jervis Relay

Jervis Relay is a collection of independently installable coding-agent skills. Each skill turns the same implementation brief into a native CLI invocation, captures a normalized result, and leaves the working tree for the orchestrator to review and land.

The project is inspired by delegate-skills, with one generated, dependency-free runtime instead of duplicated relay implementations.

Skills

| Skill | Runtime / CLI | Notes | |---|---|---| | codex-delegate | Codex | Native sandbox-aware model/effort/speed controls | | opencode-delegate | OpenCode | Model/variant and permission-aware delegation | | claude-delegate | Claude Code | Model/effort and permission-aware delegation | | gemini-delegate | Gemini CLI | Model selection and permission-aware delegation | | agy-delegate | AGY | Capability-probed controls | | grok-delegate | Grok Build | Model/effort controls | | pi-delegate | Pi | Model/thinking controls | | qoder-delegate | Qoder CLI | Model/reasoning controls | | cursor-delegate | Cursor Agent | Model and permission controls | | commandcode-delegate | Command Code | Uses cmdc on Windows and cmd elsewhere; plan/yolo modes | | omp-delegate | OMP CLI | Tool-policy delegation | | zcode-delegate | ZCode | Desktop-bundle discovery, plan/yolo, attached briefs | | openhands-delegate | OpenHands | Headless full-access only; Windows via WSL | | kiro-delegate | Kiro CLI | Effort, trust-tools, and resumable sessions | | continue-delegate | Continue CLI (cn) | Read-only/write/full tool policies and resume | | goose-delegate | Goose | Provider/model plus autonomy-mode mapping | | cline-delegate | Cline | Plan/auto-approval and command policy mapping | | aider-delegate | Aider | Model/reasoning controls with dry-run read-only mode | | copilot-delegate | GitHub Copilot CLI | Model, tool allow/deny, and resumable sessions | | vibe-delegate | Mistral Vibe | Native config-backed model selection | | kimi-delegate | Kimi Code | Model and permission-aware delegation | | native-delegate | Jervis Native | Direct provider APIs with repo-scoped tools; no external coding CLI | | custom-delegate | Configured command | Declarative command/argv/brief/output mappings | | relay-delegate | Profile-selected runtime | Profiles, automatic routing, pipelines, and fallbacks | | relay-setup | Setup only | Discovery, recommendations, and managed host instructions |

Jervis Relay supports both external coding CLIs and provider-native execution. It never stores credentials; provider adapters read credentials from the configured environment at runtime. Exact model IDs, provider authentication, and external CLI login state remain provider-owned.

Provider-native execution

Jervis Native lets Relay call supported providers directly while keeping tool execution repo-scoped and auditable:

npx jervis-relay providers --json
npx jervis-relay models list --provider deepseek --json
npx jervis-relay native run --provider deepseek --model deepseek-chat --brief brief.md --cd .
npx jervis-relay native run --provider deepseek --model deepseek-chat --brief brief.md --stream-provider --cd .

The provider registry includes native OpenAI, Anthropic, and Gemini transports, OpenAI-compatible providers, and local OpenAI-compatible runtimes such as Ollama, LM Studio, and vLLM. The same generic transport can also be supplied by a pinned extension manifest. Jervis Native exposes read/list tools in read-only mode and adds scoped file writes plus direct executable+argv commands in workspace-write; shell interpreters and dangerous Git landing/history commands are blocked by policy.

Requirements and installation

• Node.js 18 or newer.
• Git.
• The delegated CLI installed and authenticated by the user.

Install the published package in a project and use the common CLI:

npm install --save-dev jervis-relay
npx jervis-relay setup --dry-run --cd .
npx jervis-relay setup --scope project --assign feature=claude:sonnet --assign complex=claude:opus --install-host-instructions --yes --cd .
npx jervis-relay auto --brief brief.md --cd .

Install one bundled skill into all host agents detected by the skills installer:

npx skills add ./node_modules/jervis-relay --skill codex-delegate --agent '*' --copy -y

Or install all relay skills globally for the current user without resolving a package path:

npx --yes jervis-relay@latest install-skills --global --all --yes

Select one workflow or host with --skill <name> and --host <host>. Use --dry-run to inspect the installer invocation first.

Agent Skills remain available, but they are optional. setup --install-host-instructions adds a managed block to AGENTS.md (or repeated --host-file targets), so a host can invoke jervis-relay auto directly without a delegate skill.

From a source checkout, list or install skills directly:

npx skills add . --list
npx skills add . --skill codex-delegate
npx skills add . --all

Every skills/<name> directory is self-contained and may be copied or installed by itself.

Documentation

The VitePress documentation in docs/ covers npm and global installation, installing skills inside host agents, every adapter, configuration, artifacts, custom agents, GLM, security, and release operations.

npm run docs:dev
npm run docs:build

Quick start

Create brief.md:

Implement the requested feature and run the repository test suite.
Do not commit, push, or open a pull request.

Inspect the installed CLI and dispatch:

node skills/codex-delegate/scripts/relay.mjs --cd /path/to/repo --capabilities
node skills/codex-delegate/scripts/relay.mjs --cd /path/to/repo --brief brief.md

The relay prints the final message to stdout and the absolute result.json path to stderr. The orchestrator must inspect the result, review the diff, and rerun tests. The implementer is never asked to commit and Jervis Relay never auto-commits, pushes, or opens a pull request.

Public contract

Jervis Relay 1.x is intentionally CLI-first. The supported public surface is the jervis-relay executable, .jervis-relay.json configuration, bundled skills, pinned extension manifests, and the published JSON Schemas/artifact formats. Files under src/runtime/ are shipped so the bundled skills can run, but they are internal implementation details and are not a supported JavaScript import API. This keeps the 1.x SemVer contract focused and leaves room to introduce a deliberate programmatic API later without freezing internal modules prematurely.

Multi-model pipeline quick start

Copy examples/multi-model-pipeline.jervis-relay.json to .jervis-relay.json, adjust model IDs for your installed CLIs, then inspect routing before spending tokens:

npx jervis-relay pipeline implement --brief brief.md --cd . --dry-run
npx jervis-relay pipeline implement --brief brief.md --cd .

The default example demonstrates a high-quality planner, cheaper executor, the planner model returning for read-only review, safe cross-provider fallbacks, budgets, capability preflight, and balanced routing.

Verification and landing readiness

A successful agent process is not automatically considered verified or ready to land. Results include an additive delivery contract with independent implementationStatus, verificationStatus, landingReady, blockers, and evidence.

Run executable/argv verification gates from a JSON policy:

{
  "requireDiff": true,
  "consensus": { "mode": "all" },
  "gates": [
    { "name": "tests", "executable": "npm", "args": ["test"] },
    { "name": "lint", "executable": "npm", "args": ["run", "lint"], "required": false }
  ]
}

npx jervis-relay codex --brief brief.md --verify-file verify.json --cd .
npx jervis-relay codex --brief brief.md --verify-preset ci --cd .

Verification policies support required/optional gates, timeouts, repo-scoped working directories, requireDiff, and all or at-least consensus. A required verification failure can return a non-zero CLI exit while preserving the implementation result as completed.

Queues, reviews, and parallel worktrees

jervis-relay queue run queue.json supports sequential or parallel task fleets. Parallel execution requires detached Git worktrees. reviewEach can run a read-only review after each completed task, while finalReview reviews the final shared or integrated workspace. Queue-level verification uses the same verification gate engine.

For parallel worktrees, add an explicit integration stage:

{
  "schema": "jervis-relay.queue.v1",
  "concurrency": 2,
  "isolation": "worktree",
  "integration": { "strategy": "overlay" },
  "tasks": [
    { "id": "backend", "brief": "Implement backend", "agent": "native", "provider": "deepseek", "model": "deepseek-chat" },
    { "id": "frontend", "brief": "Implement frontend", "agent": "claude" }
  ],
  "finalReview": { "agent": "codex" },
  "verification": { "gates": [{ "name": "tests", "executable": "npm", "args": ["test"] }] }
}

The conservative overlay integration copies non-conflicting tracked/untracked changes and deletions into a fresh detached integration worktree. If multiple tasks touch the same path, Relay reports integration-conflict instead of attempting an ambiguous automatic merge. Final review and verification run on the integrated workspace, so a parallel queue can reach landingReady: true without creating commits.

Model registry and adaptive routing

Config v2 can define model metadata without hard-coding market prices in Relay itself:

{
  "models": {
    "example/coder": {
      "aliases": ["fast-coder"],
      "contextWindow": 200000,
      "maxOutputTokens": 20000,
      "privacy": "provider",
      "capabilities": { "coding": true, "tools": true, "vision": false },
      "pricing": {
        "inputPerMillion": 1,
        "cachedInputPerMillion": 0.25,
        "outputPerMillion": 4,
        "currency": "USD",
        "asOf": "2026-09-01",
        "source": "vendor-price-sheet"
      }
    }
  },
  "modelAliases": { "default-coder": "example/coder" }
}

Use models registered, models aliases, models inspect, models estimate, and models fit to inspect the effective catalog. Missing pricing stays explicitly unknown instead of being guessed. Pipeline/profile candidates may add routing.require constraints for input/output size, capabilities, privacy, and max estimated cost. Candidates that cannot satisfy those requirements are filtered before invocation; configs without model metadata or requirements preserve the existing routing order.

Pinned extensions and run observability

Extension SDK v1 loads JSON manifests only—no extension JavaScript is executed. Project config pins each manifest with a repository-relative path and SHA-256 digest, and the project config still requires normal content-bound trust approval. Extension v1 may contribute declarative custom agents and OpenAI-compatible providers; manifest-only evidence is reported conservatively as L1 rather than behavioral/live verification.

npx jervis-relay extensions hash extensions/example.json --cd .
npx jervis-relay extensions validate extensions/example.json --cd . --json
npx jervis-relay extensions list --cd .
npx jervis-relay extensions inspect example --cd . --json

Queues write a serialized events.jsonl timeline for task, review, integration, verification, and completion events. Use jervis-relay runs list and jervis-relay runs inspect <id|path> to discover and inspect single runs, pipelines, Native runs, and queues while deduplicating nested task/stage artifacts.

Common interface

node <skill-dir>/scripts/relay.mjs
  [--brief <file> | stdin]
  [--cd <repo>]
  [--config <file>]
  [--model <value>]
  [--effort <value>]
  [--speed <value>]
  [--mode read-only|workspace-write|full-access]
  [--session <id> | --resume-last]
  [--timeout <duration>|off]
  [--out-dir <dir>]
  [--capabilities]
  [--dry-run]

custom-delegate also requires --agent <custom-name>. --read-only and --full-access are convenience aliases for the corresponding mode.

Defaults, profiles, and layered configuration

Jervis Relay supports global and project configuration. Project values override global values. Direct delegation resolves CLI flags, agents.<agent>, defaults, then built-in defaults. Profile delegation resolves CLI flags, profiles.<name>, agents.<agent>, defaults, then built-in defaults. Config v2 project files are content-bound to a local trust approval before delegation.

{
  "version": "jervis-relay.config.v2",
  "defaults": {
    "model": "native",
    "effort": "native",
    "speed": "native",
    "mode": "workspace-write",
    "timeout": null
  },
  "agents": {
    "codex": {
      "effort": "high",
      "speed": "fast"
    }
  },
  "profiles": {
    "feature": {
      "agent": "codex",
      "effort": "high"
    }
  },
  "customAgents": {}
}

Inspect configuration paths with jervis-relay config paths, merged configuration with jervis-relay config show --effective, and Config v2 project trust with jervis-relay config trust-status. Associate .jervis-relay.schema.json with .jervis-relay.json in your editor; do not add a $schema property because the runtime intentionally rejects unknown keys. Built-in defaults are native, native, native, workspace-write, and timeout off. native means no override is passed to the agent CLI.

An explicit unsupported effort or speed exits with code 2 before spawn. The relay never ignores it or swaps models to emulate it. Use --capabilities to inspect the installed CLI and --dry-run to inspect the exact argv array.

Automatic responsibility routing

Responsibilities map task-language match terms to a profile or pipeline. Profiles own the provider/model selection, so two responsibilities may use different models from the same provider or entirely different providers:

{
  "version": "jervis-relay.config.v2",
  "profiles": {
    "feature": { "agent": "claude", "model": "sonnet" },
    "complex": { "agent": "claude", "model": "opus" },
    "tests": { "agent": "codex", "model": "gpt-5" }
  },
  "responsibilities": {
    "feature": { "profile": "feature", "match": ["implement", "feature", "fix"], "default": true },
    "complex": { "profile": "complex", "match": ["architecture", "migration", "complex"], "priority": 20 },
    "tests": { "profile": "tests", "match": ["test", "coverage", "ci"], "priority": 20 }
  }
}

Use jervis-relay auto --brief task.md --dry-run to inspect the selected responsibility, model, and exact delegated argv. Matching is local and deterministic; no model is called to choose another model.

See examples/project.jervis-relay.json and examples/custom-agent.jervis-relay.json.

Multi-model planner/executor pipelines

Use a configured pipeline when one model should plan and another should implement. The planner is always forced to read-only; the executor defaults to workspace-write. Each stage may select any built-in or configured custom agent, so the two stages may use the same CLI/provider with different models or different providers entirely.

{
  "pipelines": {
    "implement": {
      "planner": {
        "agent": "claude",
        "model": "opus",
        "effort": "high",
        "fallbacks": [{ "agent": "claude", "model": "sonnet", "effort": "high" }]
      },
      "executor": {
        "agent": "claude",
        "model": "sonnet",
        "effort": "medium",
        "fallbacks": [{ "agent": "codex", "model": "native" }]
      },
      "budget": { "maxCost": 5, "maxTokens": 200000 }
    }
  }
}

Run it with:

npx jervis-relay pipeline implement --brief brief.md --cd .
npx jervis-relay pipeline implement --brief brief.md --cd . --dry-run

The planner receives the original brief and its final message is appended as an explicit handoff to the executor. After the executor finishes successfully, Jervis Relay automatically runs a final read-only reviewer using the exact same agent, model, effort, speed, and timeout selection as the planner. The reviewer inspects the resulting repository state and reports whether the implementation is approved or needs changes. The executor must still verify the planner guidance against the repository. Model names are passed through to the selected CLI exactly as configured; use that CLI's capability/model discovery to choose valid IDs.

Each pipeline run also writes a unified pipeline-result.json artifact. It records pipeline status/timing plus per-stage selection, usage, cost, git, artifacts, and final messages for planner, executor, and reviewer. When stage costs are reported by their CLIs, the pipeline cost is their numeric sum. Use --out-dir <dir> to place the pipeline artifact tree explicitly. Each stage may declare an ordered fallbacks array, including a different agent/provider. Pipelines may also set prefer to quality, cost, speed, balanced, or order. Candidates can declare routing hints such as { "quality": 100, "cost": 10, "speed": 35 }; quality/speed sort higher-first, cost sorts lower-first, and order preserves the configured sequence. Jervis Relay intentionally does not infer these values from model names, so routing stays provider-agnostic and predictable; candidates without the selected hint remain after scored eligible candidates in their original order. With balanced, Jervis Relay also reads project-local .jervis-relay/routing-history.json and blends observed success rate, average latency, and average reported cost with the static routing hints. History starts influencing ranking after at least two samples and ramps to full confidence at five runs. Balanced weighting is role-aware: read-only planner/reviewer routing emphasizes quality and observed success, while workspace-write executor routing gives more weight to cost and speed without dropping success/correctness signals. The history file is local-only, gitignored by default, and updated after real attempts; no telemetry is sent anywhere. Read-only stages may advance through fallbacks after failure; write-stage fallback is blocked once the failed attempt has touched repository files. The reviewer always inherits the exact planner candidate that actually succeeded. Optional budget.maxCost and budget.maxTokens gates stop the pipeline between stages when reported cumulative usage exceeds the configured limit; budget exit code is 3. Before any model invocation, every planner and executor primary/fallback candidate is capability-preflighted using the same resolved defaults and CLI inspection layer as --capabilities; unavailable or incompatible CLIs and unsupported resolved model, effort, speed, or mode combinations are skipped without spending model tokens. If either required stage has no eligible candidate, the run fails fast as routing_failed before the planner is invoked. The unified result records a preflight array per stage with the resolved selection, eligibility, skip reasons, executable/version, and discovered capabilities. pipeline --dry-run exposes the same routing metadata without invoking a model. See examples/multi-model-pipeline.jervis-relay.json.

GLM through OpenCode or Claude Code

First configure and authenticate the provider in the delegated CLI itself. For OpenCode, select Z.AI or Z.AI Coding Plan with /connect, then use /models to obtain the exact provider/model ID. Put that ID in agents.opencode.model; examples/glm-opencode.jervis-relay.json shows the shape.

For Claude Code, configure Z.AI's Anthropic-compatible endpoint and model mappings in Claude Code settings, then leave Jervis Relay's Claude model at native. This preserves the provider's current mapping; examples/glm-claude.jervis-relay.json documents the boundary. See the official OpenCode provider guide and Z.AI Claude Code guide.

1.0 compatibility notes

• This is the first stable release, so there is no pre-1.0 migration path to preserve. Future breaking changes to the documented CLI/config/schema contracts require a major version.
• Exact model IDs are provider/CLI-owned and are passed through rather than hard-coded by Jervis Relay. Use --capabilities, provider model discovery, and pipeline --dry-run before live dispatch.
• CLI feature support is version-sensitive. Capability preflight rejects unavailable/incompatible candidates instead of silently dropping requested model, effort, speed, or mode settings.
• Kimi support targets the current 0.29.x command shape verified during release hardening; older CLI shapes may require upgrading Kimi or using a custom adapter.
• src/runtime/ remains internal in 1.x; do not depend on direct imports from it as a public API.

Safety and results

• Custom agents are declarative JSON only: command, argv arrays, brief transport, output paths, and capability mappings. No JavaScript is loaded and no shell expression is evaluated.
• Windows .cmd shims are invoked through a narrowly quoted command wrapper; unsafe CMD metacharacters are rejected. Native executables always receive argv directly.
• A per-working-tree lock prevents parallel workspace-write or full-access relays. Use separate Git worktrees for parallel tasks.
• An explicit timeout or relay signal terminates the delegated process tree before the final Git snapshot.
• Artifacts default to the system temporary directory. result.json is written atomically.
• Git snapshots preserve the baseline and final HEAD, pre-existing changes, touched files, commitViolation, and readOnlyViolation.

The normalized schema is jervis-relay.result.v1. Post-launch statuses are completed, failed, timeout, aborted, and <agent>_unavailable.

workspace-write means the safest useful mapping exposed by that CLI. Isolation strength is not identical across agents: Codex exposes a native sandbox, while some CLIs expose approval or permission modes. Always inspect the Git evidence.

Verification status

Built-in agent adapters and generated skills are covered by contract, dry-run, fake-transport/fake-CLI, standalone, lifecycle, pipeline, queue, provider, and schema tests. Verification evidence is deliberately conservative: manifest/contract evidence does not become live behavioral evidence automatically, Jervis Native records behavioral fake-provider evidence separately from fake CLI evidence, and pinned extensions default to L1 manifest evidence. Live authenticated dispatch remains opt-in and is never inferred from discovery alone.

Release hardening is run in split groups to stay within process-runner limits; the generated tree must also pass npm run build:check. CI continues to exercise the supported Node/platform matrix defined by the repository workflows.

Development

Shared source lives in src/runtime and src/references. Never hand-edit generated runtime or reference files under skills/.

npm run build
npm test
npm run validate
npm run check
npm run release:check # includes docs and tarball installation verification
npm run test:live # opt-in; set JERVIS_RELAY_LIVE_AGENT first

npm run build:check fails when generated copies differ from shared source. See AGENTS.md for repository conventions.

npm run test:live is skipped unless JERVIS_RELAY_LIVE_AGENT names an installed, authenticated CLI. It creates and preserves a temporary Git repository and never runs against your current working tree.

License

MIT. See LICENSE.