jcr

# JCR · Jev Capability Resolver [](https://jcr.niazmorshed.dev) JCR gives an agent one tool to find the documented commands it needs for a task. It uses [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) to search a nested capability tree and return the context attached to selected operations. Skills made it easier to load instructions when they are needed. But an agent can still read several files to find a few commands, then carry those files through the rest of the task. JCR moves that lookup into a resolver. The main agent gets the selected instructions while the search stays outside its context. I built this around a proposed capabilities format for **deterministic commands** from any provider. Skills can describe a workflow and the judgment it needs. Capabilities can document the individual operations used along the way. The format is independent of Jev, and I would like to explore whether it should become an open standard with the community. **[Read the article and watch the demo](https://jcr.niazmorshed.dev)** · [Quick start](#quick-start) · [Capability format](#capability-format) · [Benchmarks](#benchmarks) · [Contributing](#contributing) This repository includes the resolver, a capability catalog, a stdio MCP server, Claude and Codex comparison harnesses, and 50 benchmark scenarios. JCR returns documentation. It does not execute commands. The included harnesses also stop at explaining the steps needed to carry out a task. ## Quick start Use Node.js 22 or newer and npm. Clone the repository and install its dependencies. ```bash git clone https://github.com/NiazMorshed2007/jcr.git cd jcr npm ci cp .env.example .env ``` Run the remaining commands from the repository root. Fill in the keys in `.env` for the mode you want to run. For an API-key setup, the requirements are as follows. | Entry point | Keys | | ------------------------- | --------------------------------------------------------------- | | Resolver without an agent | `TYPESAFE_API_KEY`, plus `OPENAI_API_KEY` for compound requests | | Claude in skills mode | `ANTHROPIC_API_KEY` | | Claude in JCR mode | `ANTHROPIC_API_KEY`, `TYPESAFE_API_KEY`, `OPENAI_API_KEY` | | Codex in skills mode | `OPENAI_API_KEY` | | Codex in JCR mode | `OPENAI_API_KEY`, `TYPESAFE_API_KEY` | | Full comparison benchmark | All three keys | The OpenAI key in a JCR run is also used by the decomposer when Jev classifies a request as compound. Single-step requests skip decomposition. The Codex harness runs with an isolated home directory, so it does not reuse your usual Codex login. Check the catalog locally, then try the resolver. ```bash npm run capabilities:audit npm run jcr:resolve -- --agent-output "Create a Stripe customer" ``` The audit needs no API keys. Resolving requests and running agents call model APIs and incur usage charges. No Stripe, Slack, or other target-service credentials are needed to look up their instructions. The checkout is the current way to run JCR. The root package is private and is not published as an npm library. ## Running an agent Pass a request and choose a provider and mode interactively. ```bash npm start -- "Create a Stripe customer, then post its link in Slack" ``` For scripts or a specific harness, set the provider and mode explicitly. ```bash npm run claude:jcr -- --prompt "Refund the duplicate charge pi_123" npm run codex:jcr -- --prompt "Create a Linear issue for the failing build" npm run codex -- --mode skills --prompt "Deploy this project to Railway" npm run claude -- --mode skills --claude-model haiku --prompt "Create a Stripe customer" ``` Run one request through skills first and JCR second with the same provider. The comparison prints context, cost, timing, and tool usage. ```bash npm run compare -- claude "Create a Stripe customer, then post its link in Slack" ``` `compare` uses the models configured in `.env`. The agent CLI also accepts `--claude-model`, `--codex-model`, and `--metrics-file <path>`. Requests can come from positional text, `--prompt`, or stdin. Run `npm start -- --help` for the full options. | Mode | Claude harness | Codex harness | | -------- | ---------------------------------------------------------- | ---------------------------------------- | | `skills` | Project skills through `Read`, `Glob`, `Grep`, and `Skill` | Local `skill_loader.load_skill` MCP tool | | `jcr` | `resolve_capabilities` MCP tool | `resolve_capabilities` MCP tool | Skills are bundled under [`.agents/skills/`](.agents/skills/) and linked from `.claude/skills/`. In JCR mode the harness does not expose the skill catalog or filesystem tools to the agent. These are different discovery mechanisms with different tool access, which matters when interpreting comparisons. ## How resolution works For a request such as creating a customer and posting its link in Slack, the resolver first separates the required operations. It can then search the payments branch for one step and the communication branch for another. Each search opens progressively narrower groups until it reaches individual items. 1. **Classify the request.** Jev chooses whether it needs one external action or several. 2. **Split compound requests.** The configured OpenAI model breaks the request into steps while preserving the details and dependencies. Single-step requests skip this call. 3. **Search each step in parallel.** At each node, Jev ranks its direct children using their names and descriptions, with a no-match option. Questions for the open paths in one step's search round are batched together. 4. **Keep promising paths.** A beam search scores each path using the geometric mean of its routing probabilities. By default it keeps up to three paths whose score is at least 60% of the best, allowing close alternatives to be explored further. 5. **Return the selected context.** The agent receives item paths and their `context` text. Search trails, discarded branches, and scores stay in diagnostics. Several close matches can be returned for the agent to choose between. Too many close item matches produce an ambiguity response. No-match and depth-limit outcomes are explicit, so the caller can narrow the request or ask for clarification. The commands being documented can be deterministic. The model-based choice of which command fits a request is probabilistic. ## Capability format A capability is an item with routing metadata and a self-contained instruction payload. The catalog is a directory tree containing `index.json` and `items.json` files. It has no dependency on a specific provider or agent SDK. A minimal catalog looks like this. ```text capabilities/ git/ index.json items.json ``` `git/index.json` describes the group. ```json { "id": "git", "name": "Git", "description": "Inspect and manage version-controlled repositories." } ``` `git/items.json` contains its operations. ```json [ { "id": "list-tracked-files", "name": "List tracked files", "description": "List file paths tracked by Git in the current repository.", "context": "Run git ls-files from the repository root.\nRequires Git and an existing checkout.\nReturns tracked file paths, one per line. Does not include untracked files." } ] ``` When this item is selected, the agent-facing output is the path followed by the documented context. ```text git/list-tracked-files Run git ls-files from the repository root. Requires Git and an existing checkout. Returns tracked file paths, one per line. Does not include untracked files. ``` Groups can contain subgroups, items, or both. Nesting is unlimited in the **format**. If a group gets too large, split its commands into subgroups and repeat at any level, such as `git/repository/files/...`. The current resolver has a separate budget of **16 routing rounds per step**, defined in [`src/jcr/resolve.ts`](src/jcr/resolve.ts). It reports a depth-limit result when that budget is exhausted. Nodes with more than 240 children are handled by chunking and reranking finalists, but smaller, meaningful groups are the recommended way to organize a growing catalog. ### Authoring rules The loader and `npm run capabilities:audit` enforce the following structure. - The catalog root contains only group directories. It has no `index.json` or `items.json` of its own. - Every directory below the root has an `index.json` with exactly `id`, `name`, and `description`. All three are non-empty strings, and `id` matches the directory name. - An optional `items.json` is an array. Each item has exactly `id`, `name`, `description`, and `context`, all non-empty strings. - Item IDs contain no path separators and are unique within their node. A direct item and a child directory cannot share an ID. - Every node has at least one item or subgroup. Only the two JSON file types and child directories are allowed inside it. Write names and descriptions that distinguish neighboring operations. Put the actual command or endpoint, parameters, prerequisites, required credentials, and expected result in `context`. Use placeholders for runtime values. The agent does not receive parent-node descriptions as execution instructions, so each item's context needs to stand on its own. The bundled catalog has **11 groups, 960 nodes, and 11,360 items**, with a maximum node depth of 6 and a largest direct child set of 175. The audit prints updated counts after changes. It validates structure and skill mappings, not the completeness or freshness of provider documentation. ## Using JCR in another harness The tool is named `resolve_capabilities` and takes one argument. ```json { "request": "Create a Stripe customer, then post its link in Slack" } ``` Pass the complete request, including dependent steps. The tool returns text containing the selected paths and contexts, grouped by step for compound requests. A harness can use those instructions with its own execution tools. It remains responsible for supplying values, managing credentials, handling dependencies between actions, and checking their results. ### MCP server Launch [`src/jcr/server.ts`](src/jcr/server.ts) as a stdio MCP server. For a client that supports a command, arguments, working directory, and environment, use these settings. | Setting | Value | | ----------------- | ----------------------------------------------------------------- | | Command | `node` | | Arguments | `["--env-file=.env", "--import", "tsx", "src/jcr/server.ts"]` | | Working directory | Absolute path to your JCR checkout | | Environment | `CAPABILITIES_DIRECTORY` set to the absolute path of your catalog | The equivalent shell command, run from the repository root, is below. ```bash CAPABILITIES_DIRECTORY="$PWD/capabilities" \ node --env-file=.env --import tsx src/jcr/server.ts ``` The server waits for an MCP client on stdin. Use `jcr:resolve` for a human-facing CLI instead. Unlike the CLI, the server does not load `.env` itself, which is why the launch command includes `--env-file`. The local integration functions are in [`src/jcr/tool.ts`](src/jcr/tool.ts). `handleCapabilityResolution(request, { capabilitiesDirectory })` returns the agent-facing text, while `createJcrSdkServer` wraps the same handler for the Claude Agent SDK. These are source-level entry points within this checkout. ### Diagnostics and configuration Omit `--agent-output` to inspect the full resolution and usage metrics. ```bash npm run jcr:resolve -- "Create a Stripe customer" ``` For an MCP session, setting `JCR_METRICS_FILE` writes resolution details and metrics as NDJSON. Its parent directory must already exist. | Variable | Purpose | Default | | --------------------- | --------------------------------------- | -------------------------------------------------- | | `CLAUDE_MODEL` | Claude agent model | `haiku` | | `CODEX_MODEL` | Codex agent model | `gpt-5.6-luna` | | `TYPESAFE_MODEL` | Jev routing model | `jev-latest` | | `JCR_OPENAI_MODEL` | Compound-request decomposer | `gpt-5.6-luna` | | `JCR_BEAM_WIDTH` | Maximum retained paths per step | `3` | | `JCR_BAND_RATIO` | Minimum path score relative to the best | `0.6` | | `AGENT_MODE` | CLI mode when `--mode` is omitted | Interactive choice, or `skills` without a terminal | | `BENCH_CLAUDE_MODELS` | Comma-separated benchmark model list | `CLAUDE_MODEL`, then `haiku` | | `BENCH_CODEX_MODELS` | Comma-separated benchmark model list | `CODEX_MODEL`, then `gpt-5.6-luna` | CLI model flags take precedence over environment values. Beam width must be a positive integer, and the band ratio must be greater than zero and at most one. Invalid beam settings fall back to the defaults. A wider beam can explore more candidates and require more routing work. ## Benchmarks The latest `sol-vs-opus5-20` measurement ran **20 scenarios across four variants**. It compared skills and JCR in the Claude harness with **Claude Opus 5** and the Codex harness with **GPT-5.6-Sol**, giving **80 runs**. Both modes only looked up instructions and explained the steps required for each task. They did not execute those steps. [](web/public/jcr-benchmark-sol-opus.png) The figures below are **averages per run**, with skills first and JCR second. | Harness and model | Agent input tokens | Total cost | Wall time | | ---------------------- | ------------------ | ----------------- | -------------- | | Claude with Opus 5 | 108,585 → 15,819 | $0.3700 → $0.1222 | 105.5s → 77.7s | | Codex with GPT-5.6-Sol | 61,952 → 47,669 | $0.1377 → $0.1151 | 25.3s → 62.4s | JCR reduced average agent input by **85% with Opus 5** and **23% with Sol**. Average total cost fell by **67% and 16%**, respectively, including the agent model, Jev routing, and compound-request decomposition. Context here means cumulative input tokens processed by the main agent across the run, including cached tokens. It is not the size of a single context window. Jev input is reported separately and is not added to agent context. The timing result was mixed. Median wall time went from **86.6s to 57.5s** for Opus 5 and **23.2s to 45.4s** for Sol. One Sol JCR run took 372.6s with two resolver calls and 193 Jev calls, pulling up the mean. Sol was still slower with JCR in 19 of 20 scenarios, so the outlier explains only part of the gap. Wall time covers the whole agent run, including startup, generation, and tool calls. Runs overlapped, and output lengths differed between modes. There was only one run per scenario and variant. Repeated runs with timings for each stage would help separate resolver latency from harness behavior and API variation. All 80 runs completed without runtime errors. Every scenario integration has an installed skill, but skills and capability entries are different documents. Read these measurements as a comparison of the included instruction-lookup setups, rather than a task-execution benchmark. ### Run your own comparison Preview the same 20-scenario model matrix without calling any models. ```bash npm run bench -- \ --providers claude,codex \ --modes skills,jcr \ --claude-models claude-opus-5 \ --codex-models gpt-5.6-sol \ --limit 20 \ --concurrency 4 \ --timeout 600 \ --dry-run ``` Remove `--dry-run` to run it. You need API access to the selected models. The 600-second timeout allows room for slow runs. Concurrency is explicit so you can keep it consistent across comparisons. For a smaller first run, use one provider and one scenario. ```bash npm run bench -- --providers codex --limit 1 --batch-id first-comparison npm run bench:report -- --batch first-comparison ``` The benchmark defaults to all 50 scenarios, both providers, both modes, four concurrent runs, and a 300-second timeout per run. | Option | Use | | ----------------------------------- | ---------------------------------------------------- | | `--providers`, `--modes` | Comma-separated provider and mode selections | | `--claude-models`, `--codex-models` | Explicit model lists | | `--scenarios`, `--category` | Filter by scenario IDs or a category | | `--limit` | Take the first N scenarios after filtering | | `--concurrency`, `--timeout` | Control parallel runs and per-run timeout in seconds | | `--batch-id` | Name a result batch | | `--only-missing` | Reuse successful cells from previous results | | `--dry-run` | Print the matrix without model calls | Results and progress are written under `bench/results/`, which is ignored by Git and is not bundled with a fresh checkout. `bench:report` shows the most recent batch by default. `--batch <id>` selects one batch, while `--all-latest` combines the latest result for each scenario, provider, mode, and model across batches. Use a new batch ID and omit `--only-missing` for a fresh measurement. Reused results are keyed by scenario, provider, mode, and model, so they do not detect catalog or resolver changes. Use `bench:report -- --batch <id>` to inspect only that batch. Cost includes the main agent plus Jev and the decomposer for JCR runs. Claude cost comes from the Agent SDK. Codex, Jev, and decomposer costs use the rates in [`src/pricing.ts`](src/pricing.ts). Unpriced models appear as unavailable cost data. Check those rates when measuring a different model or publishing a new result. ## Development ```bash npm run typecheck npm test npm run capabilities:audit npm run format:check npm run check ``` `npm run check` combines type checking, formatting, tests, and the capability audit. Tests use the Node test runner and do not need API keys. Run `npm run format` to apply formatting when needed. | Path | Contents | | -------------------------------------------------------- | --------------------------------------------------------- | | [`capabilities/`](capabilities/) | Capability groups and items | | [`.agents/skills/`](.agents/skills/) | Bundled skills, linked from `.claude/skills/` | | [`bench/scenarios.json`](bench/scenarios.json) | Benchmark requests and integration metadata | | [`bench/skill-coverage.json`](bench/skill-coverage.json) | Skill mappings and exclusions | | [`src/jcr/`](src/jcr/) | Tree loader, Jev client, resolver, output, and MCP server | | [`src/harnesses/`](src/harnesses/) | Claude and Codex harness implementations | | [`src/mcp/`](src/mcp/) | Codex skill-loader MCP server | | [`src/bench/`](src/bench/) | Benchmark selection, execution, and result handling | | [`scripts/`](scripts/) | CLI entry points for resolving, comparing, and reporting | | [`web/`](web/) | Article and demo site | GitHub Actions runs the root checks and the site's lint and build on pull requests and pushes to `main`. ### Article site The [article](https://jcr.niazmorshed.dev) is a static Next.js export under `web/`. It has its own dependencies and does not need the model API keys. ```bash npm ci --prefix web npm run web:dev npm run web:lint npm run web:build npm run web:start ``` The build writes `web/out/`. Cloudflare serves it using the configuration in [`web/wrangler.jsonc`](web/wrangler.jsonc). After authenticating Wrangler and configuring the Worker name and custom domain for your account, `npm run web:deploy` builds and deploys the site. The video and poster live in `web/public/media/` with content hashes in their names and a one-year browser cache lifetime set by `web/public/_headers`. When replacing either file, use a new hash in its filename and update `demoVideo` in `web/src/app/page.tsx`. The original video remains at `web/public/jcr-demo.mp4`. ### Troubleshooting | Symptom | What to check | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Authentication or model-access error | Set the keys for your chosen mode and use a model available to your account. Compound JCR requests also need OpenAI access. | | `CAPABILITIES_DIRECTORY is required` | Set an absolute catalog path in the MCP server environment. | | Missing catalog files or `tsx` import errors | Run `npm ci` and launch from the checkout root. Confirm the MCP client's working directory. | | No match, ambiguity, or a depth-limit response | Inspect resolver diagnostics, narrow the request, and check the relevant node descriptions and tree depth. | | Audit failure | Follow the reported file path. Check required fields, duplicate IDs, empty nodes, unexpected files, and skill mappings. | | No benchmark results or missing cost data | Run a batch first and select its ID. Check model coverage in `src/pricing.ts` for cost data. | ## Contributing If a shared format for deterministic commands would be useful in your agent, [open an issue to discuss it](https://github.com/NiazMorshed2007/jcr/issues). I would especially like examples of commands that are awkward to represent, larger catalogs, and ideas for using the same format with other resolvers. JCR is one implementation to try the idea with. For a capability contribution, add or update the JSON files using the [authoring rules](#authoring-rules), include enough context to use each operation, and run `npm run capabilities:audit`. In the pull request, link the provider documentation used and describe a request the item should match. For a benchmark contribution, add a scenario to [`bench/scenarios.json`](bench/scenarios.json) with a unique `id`, a `title`, a concrete `prompt`, a `category`, and an `integrations` array. Set `compound` explicitly if needed. Keep the request focused on the instructions to retrieve. Each integration needs an installed skill mapped in [`bench/skill-coverage.json`](bench/skill-coverage.json). New skills need a mapping or an exclusion with a reason. Update the catalog tests if the scenario count changes. For resolver or harness changes, include focused tests for changed behavior and run `npm run check`. Site changes also need `npm run web:lint` and `npm run web:build`. Describe what changed and how you checked it. If reporting performance, include model names, settings, scenario selection, repeated-run details, and the measured costs of routing and decomposition. ## License [MIT](LICENSE) for JCR. Bundled third-party skills may include their own license and attribution terms in their directories.