0xRay — reference

4.1 — a suit that survives the context window Bifrost is the live board. Goggles views one plane. A search runs inside that card.

Exo, not catalog. Constitution always on. Temperament by host. Four floors. Repertoire organ on.

CLI, bridges, seven MCP servers, Codex. Product thesis: 4.0 vision. Wear: getting started.

Quick Start

npm install 0xray # postinstall: 4 chat bridges + Cursor hooks + 7 MCP servers + AGENTS.md + .mcp.json

npx 0xray status # verify
npx 0xray setup # optional extras

# Per-platform (idempotent — same as postinstall)
npx 0xray opencode install
npx 0xray grok install # 7 MCP servers + dual skill sync
npx 0xray hermes install
npx 0xray openclaw install
npx 0xray skill:install

npx 0xray --help

Requirements: Node.js 18+, npm 9+, macOS or Linux.

How It Works

0xRay uses a three-layer architecture that operates before any code change is made:

┌─────────────────────────────────────────────────┐
│ Inference │
│ Reasoning · Pattern learning · Execution │
├─────────────────────────────────────────────────┤
│ External Governance (Dynamo) │
│ Codex enforcement · Multi-agent review · SSOT │
│ 3 MCP skill servers deliberate proposals │
├─────────────────────────────────────────────────┤
│ Autonomous Engine (thinDispatch) │
│ Task routing · Multi-agent coordination │
│ Complexity-based delegation (7-flow MCP) │
└─────────────────────────────────────────────────┘

1. Inference Layer

Generates proposals, runs reflection cycles, and plans execution. Everything produced here enters the governance gate before any code is written.

2. Governance Layer (The "Gate")

Every proposal is reviewed by 3 specialized AI servers — code review, security audit, and research — using a weighted voting system (PHI/TAU matrix) to reach a consensus. Non-compliant proposals are blocked or sent back for revision. This is powered by Dynamo, a neural network that evaluates codex compliance, structural coherence, and risk before any action executes.

3. Autonomous Engine

Routes tasks to the right agents based on complexity (simple tasks go to a single agent, enterprise-grade work triggers a full multi-agent team). Handles dependency ordering, conflict resolution, and parallel execution.

Platform Installation

npm install 0xray runs install-bridges.cjs on postinstall (consumer projects only). 4.0.9: does not mill npm global prefix or npx _npx as a consumer; isolated HOME skips machine ~/.grok.

AGENTS-consumer.md → AGENTS.md
.gitignore.default → .gitignore (if absent)
.xray/ config deploy (codex.json, features.json, config.json)
Project .mcp.json with 7 MCP servers (npx -y 0xray mcp …)
Four bridges below + skill sync + optional git hooks

Platform	Install Command	What It Does
OpenCode	`npx 0xray opencode install`	Merges `opencode.json`, copies 42 YML agent surfaces
Grok CLI / Build	`npx 0xray grok install`	Plugin + `~/.grok/skills/` sync, 7 MCP servers
Hermes Agent	`npx 0xray hermes install`	`~/.hermes/plugins/xray-hermes`, consumer root marker
OpenClaw	`npx 0xray openclaw install`	`.xray/config/openclaw.json`, skill sync

note

npx 0xray hermes bridge was removed in 3.1+. Use hermes install.

CLI Reference

Core Commands

Command	Description
`install`	Install xray framework in the current project
`setup`	Set up `.mcp.json` and the OpenCode, Grok, Hermes, and OpenClaw bridges
`init`	Initialize xray configuration in the current project
`wear`	Wear the 0xray suit in this git checkout
`unwear`	Remove the 0xray suit and restore the pre-wear hooks file
`look`	dev, integration, domain, or ecosystem. The card is in LENS.md.
`goggles`	Same organ as `look`
`confer`	Turn confer on or off in `.xray/features.json`. A missing key stays off until this runs
`status`	Show comprehensive xray framework status
`monitor`	Current picture of the worn suit (activity, inference state, repertoire, version)
`validate`	Validate consumer wear (pack paths, Cursor hooks, mill plant)
`health`	Check framework health and system status. Alias: `check`
`pulse`	Print one line: worn CLI, repertoire, inference age, activity, lens, plant
`report`	Generate framework activity and health reports
`fix`	Run the postinstall setup for common framework issues
`doctor`	Diagnose framework issues (does not fix them)
`debug`	Print package root and current directory
`capabilities`	Show framework capabilities. Alias: `caps`
`archive-logs`	Archive log files without framework boot (for git hooks)

Skills

Command	Description
`skill:install`	Browse and install starter skill packs
`skill:install <source>`	Install skills from registry or any GitHub repo
`skill:registry list`	List all configured skill sources
`skill:registry add --name X --url Y`	Add a custom skill source
`skill:registry remove --name X`	Remove a skill source

MCP Servers (7 consumer servers)

Command	Description
`mcp governance`	Proposal governance, codex snapshot
`mcp skills`	45 knowledge skills + skill invocation (13 tools)
`mcp orchestrator`	thinDispatch 7-flow, task delegation
`mcp enforcer`	Codex compliance enforcement
`mcp researcher`	Codebase exploration
`mcp code-review`	Code review deliberation
`mcp architect-tools`	Architecture decisions
`mcp-list`	List available community MCP servers. Alias: `mcp:list`
`mcp-status`	Show installed MCP servers. Alias: `mcp:status`
`mcp-install <name>`	Install an MCP server from the registry. Alias: `mcp:install`
`mcp-remove <name>`	Remove an installed MCP server. Alias: `mcp:remove`

Platform Integration

Command	Description
`opencode install`	Install as OpenCode plugin
`grok install`	Install as Grok CLI plugin
`hermes install`	Install as Hermes Agent plugin
`openclaw install`	Install OpenClaw integration

Plugins

Command	Description
`plugin list`	List installed plugins
`plugin install <name>`	Install a plugin from npm, a local path, or `examples/plugins/<name>`
`plugin enable <name>`	Enable a plugin
`plugin disable <name>`	Disable a plugin
`plugin status <name>`	Show plugin details
`plugin uninstall <name>`	Remove a plugin

Inference & Self-Improvement

Command	Description
`inference:run`	Run full self-improvement cycle: collect → propose → govern → verify
`inference:improve`	Run inference improvement cycle
`inference:tuner`	Start/stop the autonomous inference tuner

Other Commands

Command	Description
`analytics`	Pattern analysis, insights, and consent management
`antigravity status`	Show status of all installed skills
`storyteller [type]`	Generate reflections, sagas, or narratives
`publish-agent`	Package agents for the AgentStore
`credible init`	Initialize Credible Pod infrastructure (planned)

Configuration

Feature Flags (`features.json`)

Every subsystem is configurable via features.json (located at xray/features.json):

{
 "memory_routing": {
 "enabled": true,
 "provider": "repertoire"
 },
 "token_optimization": {
 "enabled": true,
 "max_context_tokens": 20000,
 "context_compression": { "enabled": true, "threshold_tokens": 15000, "compression_ratio": 0.4 }
 },
 "multi_agent_orchestration": { "enabled": true, "max_concurrent_agents": 3 },
 "autonomous_reporting": { "enabled": false, "auto_schedule": false, "interval_minutes": 60 },
 "security": { "enabled": true, "vulnerability_scanning": true },
 "analytics": { "enabled": true, "default_limit": 100 },
 "pattern_learning": { "enabled": true, "learning_interval_ms": 3600000 },
 "complexity_thresholds": { "simple": 15, "moderate": 25, "complex": 50, "enterprise": 100 }
}

Toggle any feature on/off with enabled: true/false. The framework reloads configuration automatically.

Governance Setup

Governance is your quality gate. Configure it under inference_governance in features.json:

{
 "inference_governance": {
 "enabled": true,
 "endpoint_url": "https://your-governance-endpoint/governance",
 "request_timeout_ms": 10000,
 "min_confidence_threshold": 0.5,
 "decision_logic": {
 "pass_confidence_min": 0.9,
 "revision_confidence_max": 0.89
 }
 }
}

The governance pipeline works in three stages:

3 AI reviewers (code-review, security-audit, researcher) analyze each proposal independently
Dynamo cross-checks against the 69-term Codex for compliance, security, and coherence
Weighted voting (PHI/TAU matrix) produces a final decision: approve, revise, or reject

⚠️ Privacy Notice: All proposals submitted to the governance endpoint are public by default. They are not persisted on-chain unless the onChain: true flag is set. 0xRay framework self-governance proposals (tagged 0xray) save on-chain by default; project proposals do not. Set onChain: false or omit the field for non-public governance checks.

Agents (organs)

42 YML surfaces in src/opencode/agents/*.yml. They are organs. The product is the exo. Core governance: @enforcer @orchestrator @architect @security-auditor @code-reviewer @refactorer @testing-lead @bug-triage-specialist @researcher. Full list: Agents.

MCP Servers

Seven consumer servers via npx -y 0xray mcp <cmd>. Extra *.server.ts files in the repo are not an 8th consumer MCP (Codex 69). See MCP.

Skills (45)

Knowledge skills (src/skills/*/SKILL.md) loaded by xray-skills. Includes xray-orchestrator. autonomy-command is the default operating model (orchestrator skill + lead_dev_mode), not a 46th skill dir.

api-design, architect-tools, architecture-patterns, auto-format, backend-engineer, boot-orchestrator, bug-triage, code-analyzer, code-review, content-creator, database-engineer, devops-engineer, enforcer, framework-compliance-audit, frontend-engineer, frontend-ui-ux-engineer, git-workflow, growth-strategist, hermes-agent, inference-improve, lint, log-monitor, mobile-developer, model-health-check, multimodal-looker, orchestrator, performance-analysis, performance-engineer, performance-optimization, processor-pipeline, project-analysis, refactoring-strategies, researcher, security-audit, security-scan, seo-consultant, session-management, state-manager, storyteller, strategist, tech-writer, testing-best-practices, testing-strategy, ui-ux-design, xray-orchestrator

Install more skills: npx 0xray skill:install

Testing & Reliability

Four-floor consumer e2e against the 4.0 line:

Suite	Status
OpenCode E2E	34/0
Grok CLI E2E	63/0
Hermes E2E	39/0/2 (npm 4.0.0 pack)
OpenClaw E2E	96/0/1 (npm 4.0.0 pack)
Consumer smoke	`release-gate.mjs` — pack → install → 7 MCP + 4 chat bridges + Cursor hooks + organ on

Next Steps

# 1. Check your installation
npx 0xray status

# 2. Install skill packs (adds agent expertise)
npx 0xray skill:install

# 3. Read the station card after compact / host-swap
# .xray/state/STATION.md

# 4. Agent surfaces
# AGENTS.md (copied on postinstall)

# 5. Run a health check
npx 0xray health

Resources

Docs — Full documentation site
Self-Hosting Dynamo — External governance service
GitHub — Source code, issues, discussions
npm — Package registry

License

MIT

0xRay — self-healing, governed, autonomous. Catch AI mistakes before they ship.

Quick Start​

How It Works​

1. Inference Layer​

2. Governance Layer (The "Gate")​

3. Autonomous Engine​

Platform Installation​

CLI Reference​

Core Commands​

Skills​

MCP Servers (7 consumer servers)​

Platform Integration​

Plugins​

Inference & Self-Improvement​

Other Commands​

Configuration​

Feature Flags (features.json)​

Governance Setup​

Agents (organs)​

MCP Servers​

Skills (45)​

Testing & Reliability​

Next Steps​

Resources​

License​