reasoning-router
AGENTS.md4 starsChanged 35 days agoMITView on GitHub
reasoning-router is a pre-alpha npm-workspaces monorepo that generalizes opencode-jev-router to multiple agent harnesses and multiple classifiers. It contains the port of opencode-jev-router (see "Layout"). docs/architecture.md frames the problem and the open design questions. Use Node.js 24.x from the repo root. CI (.github/workflows/ci.yml) runs install, typecheck, lint, test, and smoke:package on pushes to main and on pull requests, plus the plugin and Pi smokes as separate jobs. The plugin smoke needs openssl and an existing /tmp/opencode; set OPENCODE_V2_BIN or OPENCODE_V2_VERSION to…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- add-classifierSkill
- run-evalsSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Use Node.js 24.x from the repo root.
- Very specific: line 67
Create only the packages listed under "Packages" in docs/architecture.md: @reasoning-router/core, @reasoning-router/opencode, …
- Very specific: line 79
Never run npm publish or changeset publish locally.
- Very specific: line 88
Do not modify opencode-jev-router from here.
- Very specific: line 93
Every README.md has a Simplified Chinese README_CN.md, a Japanese README_JA.md, and a Korean README_KO.md beside it.
- Distinctive: line 101
Use the terms from OpenAI's and Anthropic's localized docs: effort is 推理强度 / 推論強度 / 추론 수준, classifier is 分类器 / 分類器 / 분류기, and prompt cache …
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working on this repo
reasoning-router is a pre-alpha npm-workspaces monorepo that generalizes
opencode-jev-router to
multiple agent harnesses and multiple classifiers. It contains the port of
opencode-jev-router (see "Layout"). docs/architecture.md frames the
problem and the open design questions.
Commands
Use Node.js 24.x from the repo root.
| Task | Command |
| Install dependencies | npm ci |
| Typecheck, lint, and test | npm run check |
| Typecheck | npm run typecheck |
| Lint and format check (Biome) | npm run lint |
| Apply lint fixes and formatting | npm run format |
| Run tests (Vitest) | npm test |
Build every package to dist/, in dependency order | npm run build |
| Pack, install, and run the packages | npm run smoke:package |
| Install the packed plugin in OpenCode 2.0.18 | npm run smoke:plugin:v2 |
| Install the packed extension in Pi 1.0.4 | npm run smoke:pi |
CI (.github/workflows/ci.yml) runs install, typecheck, lint, test, and
smoke:package on pushes to main and on pull requests, plus the plugin
and Pi smokes as separate jobs. The plugin smoke needs openssl and an
existing /tmp/opencode; set OPENCODE_V2_BIN or OPENCODE_V2_VERSION to
test another OpenCode V2. The Pi smoke needs openssl and runs the pinned
Pi devDependency; set PI_BIN (and PI_VERSION, the version it reports) to
test another Pi.
Orca runs ./scripts/setup.sh from orca.yaml and waits for it to finish
before starting an agent. The script runs npm ci, copies local .env* files
(except .env.example) from the main checkout into a new worktree, and creates
.env from .env.example if none exists. If present, it links
.scratch/shared and AGENTS.local.md. It never overwrites existing files.
Layout
packages/core(@reasoning-router/core): validation, rewrite, lineage, forwarding, logging, model registry, and the classifier interface.packages/classifiers(@reasoning-router/classifiers): every classifier, as presets selected byclassifier.provider.packages/opencode(@reasoning-router/opencode): the OpenCode V2 plugin.packages/pi(@reasoning-router/pi): the Pi extension.packages/proxy(@reasoning-router/proxy): the standalone proxy, run as thereasoning-routercommand.- Each package has
src/,test/, and atsconfig.build.jsonthat compilessrc/todist/. Packageexportsresolve the@reasoning-router/sourcecondition tosrc/*.ts, which the roottsconfig.jsonandvitest.config.tsenable, so typecheck and tests run against source without building. scripts/: package, plugin, and Pi smoke tests.tsconfig.base.json: shared compiler options for packages to extend.biome.json: lint and format configuration..changeset/: Changesets configuration (independent versions).
Conventions
- The classifier (the component that picks the reasoning effort, such as Jev) is configuration. Do not make shared code depend on Jev or any single classifier provider; provider-specific code and dependencies stay out of the core.
- Create only the packages listed under "Packages" in
docs/architecture.md:@reasoning-router/core,@reasoning-router/opencode,@reasoning-router/classifiers,@reasoning-router/pi, and@reasoning-router/proxy. Harness adapters use the bare harness name. Add a classifier as a preset inclassifiers, not as a new package. Follow the "Porting" decisions indocs/architecture.mdwhen porting code into them. - Reach every classifier over HTTP. A classifier that runs a local model (such as Laya) is a server the user runs; never install, download, load, or start a model, its weights, or its runtime from these packages, and add no model runtime dependency.
- Each test lives in the package whose code it covers.
- Never run
npm publishorchangeset publishlocally; releases go through.github/workflows/release.yml. Add a changeset (npx changeset) to any PR that changes a package's published behavior. Onmain, the workflow opens a "Version Packages" PR that applies pending changesets; merging it publishes the new versions to npm with provenance through npm trusted publishing, so no npm token is stored. If npm stages a release instead of publishing it, a maintainer approves it withnpm stage approve. A new package has no trusted publisher, so its first version is published manually by a maintainer. - Do not modify
opencode-jev-routerfrom here; read it for reference only. - Make the smallest change that works. Add no speculative abstractions and no configuration without a current requirement.
- Record reversible decisions in the commit message and, when they affect
contributors, under "Decisions" in
docs/architecture.md. - Every
README.mdhas a Simplified ChineseREADME_CN.md, a JapaneseREADME_JA.md, and a KoreanREADME_KO.mdbeside it. Any change to a README must make the same change to every translation in the same commit, and a new README needs all three translations. Translations link to each other's_CN/_JA/_KOcounterparts. In a translation, put<a id="..."></a>with the English anchor above any heading that is linked to, so#fragmentlinks keep working, and point links to a package directory at that directory's translated README. Use the terms from OpenAI's and Anthropic's localized docs: effort is 推理强度 / 推論強度 / 추론 수준, classifier is 分类器 / 分類器 / 분류기, and prompt cache is 提示缓存 / プロンプトキャッシュ / 프롬프트 캐시 (CN / JA / KO). Chinese writes "token", not 令牌.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

