xray — a suit for coding agents

4.1 — a suit that survives the context window
Bifrost is the live board. Goggles views one plane. A search runs inside that card.
0xRay is a three-subsystem autonomous engine. The suit is the wear. Inference remembers. External Governance judges. The Autonomous Engine runs the work. The host you already run wears it: Grok, OpenCode, Hermes, OpenClaw, or Cursor. Memory, judgement, and payments come on with the suit. When the window closes, the next session wakes with the job, the page, and the laws.
Bifrost turns each pull request, issue, and comment into one card and a line in the right seat's inbox, then wakes that seat. Confer still completes only on a real yes. A foundry is built from mills and hangars. The mill builds and ships. The hangar is the shop.
The product is the skeleton you wear.
Your AI Power Suit
Your AI Power ⚡️ Suit 🦾 — an exoskeleton that blocks AI slop from becoming real damage.
- Bone — three-subsystem engine: Inference · External Governance (Dynamo / Codex) · Autonomous Engine (thinDispatch)
- Always on — Codex 11 / 29 / 69, destructive shell, no new MCP/skill/handler surface
- Temperament —
frontier|guided|strict|auto— how loud the engine is, not whether governance exists - Wear — Grok, OpenCode, Hermes, OpenClaw, plus Cursor project hooks. One SSOT gate
- Muscle — Repertoire is preferred. Vendored 0.2.9 ships on. Dest is named laws, not hangar
repo-*or git slugs. Station is the wake ticket — not a substitute for Repertoire.
npm install 0xray
npx 0xray wear
Wear links vendored @0xray/repertoire and writes the consumer suit, including when npm did not run the install script. When that script does run, it symlinks vendored @0xray/repertoire into node_modules, prints npx 0xray wear, and does not write .mcp.json or the chat bridges. Wear writes the consumer suit: managed AGENTS.md, .xray config, seven MCP servers, and the OpenCode, Grok, Hermes, and OpenClaw bridges (install-bridges.cjs). Inside a git checkout, wear also fastens Cursor project hooks. Repertoire is preferred — vendored 0.2.9 ships on: factory + stack laws, in-process routing, extra host MCP repertoire. Not an eighth xray-* server. Dest is a judgment index. Explicit opt-out only: "enabled": false, "provider": "repertoire". Do not pin 0.1.8.
Quick Start
npm install 0xray
npx 0xray wear
npx 0xray status
npx 0xray setup --git-hooks # optional: git hooks only
npx @0xray/foundry inspect --skip-live # mill receipt (chat is not a receipt)
Manual per-platform install (idempotent, same bridges wear writes):
npx 0xray opencode install
npx 0xray grok install # 7 MCPs servers + project .grok/plugins/0xray (not machine last-wins)
npx 0xray hermes install
npx 0xray openclaw install
npx 0xray skill:install # starter skills
Autonomy command (default operating model)
When the suit is worn, autonomy-command is ON by default: lead dev takes helm, phased todos, best subagent per task, per-suite test triage, loop until green. No keywords required. Slash: /autonomy-command
Docs: guides/autonomy-command · Skill: src/skills/autonomy-command/SKILL.md
What's New Since 3.1
Consolidations
- Install, then wear, then setup where needed — Wear links vendored
@0xray/repertoireand writes the suit.postinstall.cjs, when npm runs it, symlinks vendored@0xray/repertoireintonode_modulesand prints one line:npx 0xray wear.wearandunwearset up or remove the Cursor suit.npx 0xray setupwrites.mcp.jsonand the OpenCode, Grok, Hermes, and OpenClaw bridges (install-bridges.cjs); git hooks only with--git-hooks. Mill target is the consumer project, not npm global prefix or_npx. - 7-server MCP surface —
.mcp.jsonSSOT; Grok plugin and all bridges shareXRAY_MCP_SERVERS. - Dev vs consumer AGENTS —
AGENTS.md(framework) vsAGENTS-consumer.md(copied to consumer projects on install). - Release pipeline —
npm run release:patch|minor|major→ reconcile → gate → artifacts → tag → publish.
Removals / Deprecations
- StringRay / strray-ai branding retired (3.1.1).
hermes bridgeCLI removed — usenpx 0xray hermes install..opencode/xray/fallback removed from auto-reflection-generator (3.1.1).- ~180 stale
@versionJSDoc tags and "xray 2.0" command doc strings cleaned (3.2.0). advanced-features/removed. The live Grok hook ispre-tool-use.js.- PostProcessor soft-deprecated since 3.0 (
enablePostProcessor: falsedefault).
Three-Subsystem Architecture
┌─────────────────────────────────────────────────┐
│ Inference │
│ Proposals · Reflection · Memory routing │
├─────────────────────────────────────────────────┤
│ External Governance (Dynamo) │
│ Codex enforcement · Resonance/Isotopic · SSOT │
│ 3 deliberation MCPs: code-review, security, │
│ researcher (within 7-server consumer surface) │
├─────────────────────────────────────────────────┤
│ Autonomous Engine (thinDispatch) │
│ 7-flow · AsideContext · Confidence gate │
└─────────────────────────────────────────────────┘
- Inference — proposals, reflection, execution planning. Optional memory-routing enrichment (v3.3).
- External Governance — Dynamo Solar SSOT; CodexPolicyService; weighted PHI/TAU deliberation.
- Autonomous Engine — thinDispatch 7-flow routing; orchestrator confidence gate (v3.3.1).
Consumer Install (wear)
Wear links the vendored repertoire, including when npm did not run the install script. Wear then:
- Copies
AGENTS-consumer.md→AGENTS.md. Does not write consumer-rootSKILLS.md. - Fastens mill plant (
mill+inspect). Fasten is foundry-plant/0: builtin plant is mill+inspect only.foundry.json"plant": "@0xray/blip"(aliases"plant": "blip"/"plant": "sound") fastens whatever that mill package declares — organs (looker, vibe, mixer) live in the mill, not an xray catalog. Nested mill@0xray/[email protected]. CLI shimsfoundry blip|soundstill exist on foundry 0.1.11+; fasten is the new cut. Not a 45-skill / 42-agent costume dump.foundry.json"costume": trueis the opt-in dump. - Seeds
.gitignorefrom.gitignore.default(if absent) - Deploys
.xray/config (codex.json,features.json,config.json) then overlays their plant - Writes project
.mcp.jsonwith 7 MCPs servers (npx -y 0xray mcp …) - Installs 4 chat bridges: OpenCode, Grok, Hermes, OpenClaw, plus Cursor
.cursor/hooks.json(PPE + wiring; mill plant, not costume) - Factory shop plant (
shop-extract,shop-witness,shop-pinfrom groover-hangar) may coexist when worn. Extra shops:foundry.jsonshopPlant. Not costume. - Inside a git checkout, fastens Cursor
.cursor/hooks.jsonand the hook scripts, and keeps an unwear snapshot. Outside a git checkout, skips those hooks and prints one warning.npx 0xray setup --git-hooksis what installs git hooks.
See llms.txt for the agent map. Catalog of 45 skills lives in SKILLS.md — that is the exo catalog, not default consumer wear.
Seven MCP Servers (consumer)
All registered via npx -y 0xray mcp <cmd> — no brittle dist/ paths:
The framework repo also ships additional internal .server.ts implementations for orchestration pipelines — these are not part of the 7-server consumer .mcp.json surface.
Agents
42 YML agent surfaces in src/opencode/agents/*.yml — zero manual registration. Invoke via @agent-name in OpenCode.
Core governance agents:
See AGENTS.md and SKILLS.md for the full agent and skill catalog.
Memory Routing + Repertoire (preferred, v3.3+)
Wear Repertoire. It is the long-term judgment organ. Station holds the ticket across compact. Dest is named invariants, not keywords. Pluggable memory_routing in features.json (validated by features.schema.json) ships on:
"memory_routing": {
"enabled": true,
"provider": "repertoire",
"module_path": "node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js",
"config": {
"signalsPath": ".xray/state/repertoire/curated_signals.json",
"statePath": ".xray/state/repertoire/inference-state.json",
"feedbackDir": ".xray/state/repertoire/feedback"
}
}
External hosts (Hermes/Grok): add repertoire-mcp to .mcp.json — see Repertoire docs. Preferred. Not optional flavor.
Explicit opt-out only: "memory_routing": { "enabled": false, "provider": "repertoire" }.
Docs: memory routing · Repertoire · features.json · all features since 3.1
Integrations
Governance & Codex
- 70 terms in
.xray/codex.json— core, architecture, testing, performance, security, operations, governance (Codex 69: no new MCP/skill/handler surface; Codex 70: current copy before edits) - CodexPolicyService — Governance-owned SSOT for codex loading
- Pre-governance gate blocks non-compliant proposals
- Active codex snapshot via
get_active_codexMCP tool - frameworkLogger structured logging (never
console.*)
Testing
npm test
npm run pack:tmp-proof # pack → tmp fasten + hangar inspect
npm run release:gate # full release gate (before upload)
npm run release:npm # gate + prepare + npm publish --access public
Release
The 4.1 line is on npm. Do not run release:major to ship a 4.x fix (that becomes 5.0.0). Do not put a scripts.publish lifecycle that re-runs the gate after the registry PUT. Patch number lives in package.json + CHANGELOG.
npm run release:gate
npm run release:npm # after gate is green; uses npm publish --access public
npm run release:patch # version bump pipeline (not for an already-bumped package.json)
Pipeline: reconcile-version → release-gate (build + test + consumer smoke) → CHANGELOG/README/AGENTS artifacts → commit → tag → npm publish.
License
MIT — see LICENSE
xray — a three-subsystem autonomous engine. The suit is the wear.