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 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 · [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.

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.

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.

npm start -- "Create a Stripe customer, then post its link in Slack"

For scripts or a specific harness, set the provider and mode explicitly.

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.

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 . 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.

1. Split compound requests. The configured OpenAI model breaks the request

into steps while preserving the details and dependencies. Single-step requests skip this call.

1. 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.

1. 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.

1. 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.

capabilities/
  git/
    index.json
    items.json

git/index.json describes the group.

{
  "id": "git",
  "name": "Git",
  "description": "Inspect and manage version-controlled repositories."
}

git/items.json contains its operations.

[
  {
    "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.

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.

{
  "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.

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.

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 bench

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NiazMorshed2007
• Source: NiazMorshed2007/jcr
• License: MIT
• Homepage: https://jcr.niazmorshed.dev

Install and usage instructions live in the source repository linked above.