OnyxSi
OnyxSi is a zero-dependency MCP server for safe, headless codebase inspection, speculative editing, testing, and agent workflow orchestration over JSON-RPC stdio.
Inspect directories, AST skeletons, line ranges, symbols, grammars, and resolve
ref://handles (vfs_inspect).Stage in-RAM Ghost-CoW edits and patches without touching disk until commit (
vfs_mutate).Manage sandbox lifecycle, run tests in shadow workspaces, and fork/switch/score/merge MCTS branches (
ghost_sandbox).Enforce causal flight stages: declare blast radius, check drift, verify staged files, log commits, reset error budget, and bisect (
causal_flight).Register, falsify, and select orthogonal debugging hypotheses with probes (
hypothesis_branch).Persist task state, progress, logs, handoff docs, and time-travel replay under project namespaces (
wiki_task_sync).Run deterministic BM25 search, blast-radius test selection, and ALU/math computations (
graph_compute).Orchestrate multiple meta-tools as one dependency-ordered DAG in a single call (
mcp_orchestrate).
Connects to Google Antigravity as an MCP client, exposing OnyxSi's eight meta-tools for zero-copy AST inspection, RAM-buffered edits, MCTS forking, causal flight tracking, and task state synchronization over stdio JSON-RPC 2.0.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OnyxSi explore two fixes for the failing auth tests and commit the one that passes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚡ OnyxSi (Onyx-Si)
Pure Headless Zero-Dependency Autonomous Agent Kernel, ContextFS & Causal Execution Box
100% Python Standard Library · 100% Headless · Strict Token Budget · Crash-Safe Writes
Why OnyxSi • Connect MCP • Live Transcript • 8 Meta-Tools • Architecture • Benchmarks • Installation
Zero external dependencies by design. An AST auditor (src/onyxsi/auditor.py) scans the codebase at boot and rejects banned third-party imports and UI packages. The latest audit checked 45 files with 0 violations. OnyxSi needs no pip install step, compiles no native extensions, and runs without a GUI. It communicates over stdio using JSON-RPC 2.0 and persists state to Markdown and JSON files.
🎯 Why OnyxSi Exists
⚠️ The Problem in Modern Coding Agents | ⚡ The OnyxSi Solution |
Context window bloat. Dozens of narrow MCP tools burn tens of thousands of tokens before the model has read a single line of the codebase. | 8 polymorphic meta-tools, 1,593 tokens total. The whole tool surface is smaller than a typical system prompt. Output is folded into retrievable |
Destructive edits. An agent writes a file, the build breaks, and nobody knows which of forty edits caused it. | Tier-0 Ghost-CoW overlay. Every mutation lands in a zero-copy piece table in RAM. Disk is touched only after a syntax gate, a blast-radius test run, and an explicit commit. |
Linear trial and error. One hypothesis at a time, each attempt a full round-trip through the model. | In-RAM MCTS forking. Several competing fixes are explored simultaneously in RAM, scored against real test runs, and the winner is the only one that reaches disk. |
Repeat-offender bugs. The same mistake is re-introduced three weeks later because nobody wrote it down. | Autonomous AST antibody vaccine. Every commit is diffed against its own pre-image; the defective pattern that was removed becomes a permanent rule that blocks the reintroduction. |
Cross-project contamination. Two repos on one machine share task IDs, progress state, and learned rules. | Project-namespaced storage. Task state and antibody rules live under |
Lost reasoning. The agent's decision trail evaporates when the session ends. | Time-Travel Chronicle. The branch tree and frame-by-frame event log write directly to |
🎬 The Architectural Narrative
Figure 1: The Entropy of Modern Coding Agents
Coding agents commonly struggle with three structural issues:
Context Bloat: Dozens of micro-tools consume thousands of prompt tokens on definitions alone before reading a single line of code.
Destructive Edits: Unbuffered disk writes corrupt working trees during multi-step edits, leaving broken builds behind.
Amnesia & Repetition: Without cross-session memory, fixed bugs recur weeks later because reasoning trails disappear when sessions close.
Figure 2: Replacing Linear Trial-and-Error with Governed Architecture
OnyxSi replaces speculative guesswork with deterministic, bounded execution:
Efficiency: Eight polymorphic meta-tools capped at 1,593 tokens total, eliminating tool catalog bloat.
Safety: A Tier-0 Ghost-CoW overlay buffers mutations in RAM; files touch disk only after passing syntax and blast-radius checks.
Multiverse: In-memory MCTS forking tests competing fixes in parallel rather than guessing one attempt at a time.
Immunity: AST antibody memory turns fixed bugs into permanent anti-patterns right after a commit lands.
Figure 3: Seven Decoupled Layers Governed at Boot
The runtime divides into seven layers. Before startup, an AST compliance auditor scans all 45 source files to confirm zero banned imports or UI packages:
Layer 7 (MCP Daemon): Headless JSON-RPC 2.0 engine over stdio, serving eight meta-tools with zero web server dependencies.
Layers 4 & 5 (Gateway & Causal): GBNF grammar checks, token folding, four-stage flight tracking, and a three-strike error budget.
Layers 2 & 3 (ContextFS & DeltaFS): Bitplane AST scanner, token governor, memoryview piece table, and in-memory branch leases.
Layer 1 (HAL): 64MB shared-memory superblock, lock-free SPSC telemetry ring, and process sandboxing.
🧩 Subsystem Architecture & Capability Matrix
🛠️ Fixed 8 Meta-Tool Surface | 🌲 In-RAM MCTS Multiverse Forking |
Functional surface capped at 1,593 tokens• | Test competing fixes in parallel in RAM• Fork: Clones candidate fixes in memory with zero disk I/O• Test: Runs syntax gates and blast-radius tests in isolated shadow copies• Merge: Commits only the highest-scoring branch to disk and drops failed attempts cleanly |
🛡️ Autonomous AST Antibody Vaccine | ⏱️ Time-Travel Chronicle & Flight Recorder |
Automatic regression prevention from commit diffs• Diff Analysis: Evaluates changed code lines on every successful commit• Forbidden Pattern: The removed bug becomes an active AST anti-pattern• Prescribed Cure: The replacement code becomes the recommended fix• Deterministic Hashing: SHA-256 keys prevent duplicate rule entries | Verifiable reasoning trace across sessions• Project Namespaced: Task state isolates under |
📊 Empirically Verified Invariants | 🔌 Zero-Install Connection & Stdio Bridge |
Empirically verified resource ceilings• 1,593 Tokens: Combined schema footprint ceiling strictly maintained• 1,250 Tokens: Per-call output limit with folding into | Pure Python stdlib headless orchestration• Zero Installation: Runs directly from checkout with |
Related MCP server: CodeForgeX
🔌 Connect to Antigravity, OpenCode & MCP Clients
OnyxSi is a standard MCP server communicating over stdio using JSON-RPC 2.0. It requires zero package installations and runs straight from source on both Windows and Linux.
1. Google Antigravity
Antigravity natively orchestrates OnyxSi via its global configuration file (~/.gemini/config/mcp_config.json). All 8 Meta-Tools are auto-discovered from ~/.gemini/antigravity/mcp/onyxsi/:
Global Configuration (C:\Users\<user>\.gemini\config\mcp_config.json):
{
"mcpServers": {
"onyxsi": {
"command": "L:\\.Tool\\OnyxSi\\.venv\\Scripts\\python.exe",
"args": [
"L:\\.Tool\\OnyxSi\\onyxsi-mcp.py",
"--workspace",
"L:\\.Tool\\OnyxSi"
],
"env": {
"PYTHONUNBUFFERED": "1",
"PYTHONIOENCODING": "utf-8"
}
}
}
}Pre-compiled Tool Schemas: Tool schemas and execution instructions are stored directly under ~/.gemini/antigravity/mcp/onyxsi/ (onyxsi_vfs_inspect.json, onyxsi_vfs_mutate.json, etc.), allowing Antigravity to invoke each tool with zero catalog latency.
2. OpenCode v2
OpenCode v2 reads MCP servers from mcp.servers (unlike v1, which read mcp directly). Create opencode.jsonc in your project root, or add the block to ~/.config/opencode/opencode.jsonc to make it available everywhere.
Project-scoped (opencode.jsonc next to your code):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"onyxsi": {
"type": "local",
"command": ["python", "/absolute/path/to/OnyxSi/onyxsi-mcp.py", "--workspace", "."],
"timeout": { "startup": 60000, "execution": 600000 }
}
}
}
}Global (~/.config/opencode/opencode.jsonc): omit --workspace and OnyxSi targets whichever project the editor is currently in:
{
"$schema": "https://opencode.ai/config.json",
"shell": "powershell",
"mcp": {
"servers": {
"onyxsi": {
"type": "local",
"command": [
"python",
"L:\\.Tool\\OnyxSi\\onyxsi-mcp.py"
],
"timeout": { "startup": 60000, "execution": 600000 }
}
}
}
}Zero-install bridge. onyxsi-mcp.py puts the checkout's src/ on sys.path, pins stdin/stdout to UTF-8, and disables .pyc writing so the checkout stays pristine. onyxsi-mcp.cmd (Windows) and onyxsi-mcp.sh (Linux/macOS) are thin wrappers around it. No pip install, no PYTHONPATH, no virtualenv.
3. Claude Desktop / Cursor / Windsurf / VS Code
Add to your client's claude_desktop_config.json or MCP settings:
{
"mcpServers": {
"onyxsi": {
"command": "python",
"args": [
"/absolute/path/to/OnyxSi/onyxsi-mcp.py",
"--workspace",
"/absolute/path/to/your/project"
]
}
}
}4. Direct Terminal Verification
Verify the server protocol initialization directly over terminal pipes:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' \
| python onyxsi-mcp.py --workspace .onyxsi --workspace DIR # serve DIR over JSON-RPC stdio
--project-name NAME # namespace for the task wiki + antibody store
# (default: the workspace folder name)
--no-pre-flight-gate # allow vfs_mutate without causal_flight pre_flight
--telemetry-out PATH # append per-tool JSONL telemetry on shutdown
--max-index-files N # cap on indexed .py files (default: 5000)
--max-index-mb MB # per-file size cap (default: 2.0)
--max-index-total-mb MB # total index byte budget (default: 128.0)
--max-shadow-mb MB # temp shadow copy cap for tests (default: 512.0)🧪 Live MCP Transcript (Verified)
The transcript below was captured directly from an interactive session over stdio JSON-RPC. It exercises the full MCTS loop: forking competing hypotheses in RAM, testing each in an isolated shadow copy of the workspace, scoring the results, merging the winner, and writing the final state to disk.
Step 1: Open a session and stage the baseline fix
→ {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"begin"}}}
← {"status":"ok","mode":"ghost_sandbox_active","session_id":"074a5c0c"}
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"fork","branch_id":"branch_fast","hypothesis":"rename the helper, keep the body"}}}
← {"status":"ok","branch_id":"branch_fast","branches":[
{"branch_id":"main","parent":null,"hypothesis":"","active":false,"modified_files":1,"score":null},
{"branch_id":"branch_fast","parent":"main","hypothesis":"rename the helper, keep the body","active":true,"modified_files":1,"score":null}]}Step 2: Test each branch in an isolated shadow workspace
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"switch_branch","branch_id":"branch_fast"}}}
→ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"test","command":"python demo_mcts/check.py","timeout_s":60}}}
← {"status":"ok","test_result":"FAILED","mode":"shadow-workspace","exit_code":1,"duration_ms":30.9,
"shadow_files":132,"staged_files":1,
"stderr_tail":"AssertionError: add(2, 3) returned -1, expected 5\n",
"enforcement":{"workspace":"path-prefix; the command ran in a temp copy, the real workspace was not written",
"syscall":"none","network":"not isolated"}}
→ {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"switch_branch","branch_id":"branch_robust"}}}
→ {"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"test","command":"python demo_mcts/check.py","timeout_s":60}}}
← {"status":"ok","test_result":"PASSED","exit_code":0,"stdout_tail":"PASS: add(2, 3) == 5\n"}Step 3: Score, merge the winner, and commit it
→ {"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{
"cmd":"merge_best",
"scores":[{"branch_id":"main","passed_tests":0,"total_tests":1},
{"branch_id":"branch_fast","passed_tests":0,"total_tests":1},
{"branch_id":"branch_robust","passed_tests":1,"total_tests":1}]}}}
← {"status":"ok","winner":"branch_robust","score":99.9914,"scores":[
{"branch_id":"main","score":0},
{"branch_id":"branch_fast","score":-0.0024},
{"branch_id":"branch_robust","score":99.9914}],
"hint":"The winning branch is active and still in RAM; cmd=commit writes it to disk."}
→ {"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"ghost_sandbox","arguments":{"cmd":"commit"}}}
← {"status":"ok","committed_files":{"L:\\.Tool\\OnyxSi\\demo_mcts\\calc.py":118}}The file on disk after the commit:
def add(a, b):
if not isinstance(a, (int, float)):
raise TypeError('a must be a number')
return a + bStep 4: Write the decision trail to disk
→ {"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"wiki_task_sync","arguments":{
"task_id":"TASK-001","op":"replay","project_name":"OnyxSi",
"branches":[{"branch_id":"main","hypothesis":"baseline as found on disk","score":0},
{"branch_id":"branch_fast","parent":"main","hypothesis":"rename the helper, keep the body","score":-0.0024},
{"branch_id":"branch_robust","parent":"main","hypothesis":"fix the operator, guard the type","score":99.9914}]}}}
← {"status":"ok","path":"L:\\.Tool\\OnyxSi\\.onyxsi\\wiki\\projects\\OnyxSi\\tasks\\TASK-001\\TIME_TRAVEL_REPLAY.md"}Which produced TIME_TRAVEL_REPLAY.md:
# Time-Travel Replay: TASK-001
**Project:** `OnyxSi` | **Generated:** 2026-10-20T11:59:00Z | **Frames:** 0 | **Branches:** 3
## 1. ASCII Decision & State Branch Tree
```text
main [score=0.00] — baseline as found on disk
├── branch_fast [score=-0.00] — rename the helper, keep the body
└── branch_robust [score=99.99] — fix the operator, guard the type
> [!NOTE]
> **The scoring formula:** `score = (passed / max(1, total)) * 100 - drift * 50 - min(10, diff_bytes / 10000)`. The test pass ratio carries the most weight. Drift reflects trajectory divergence measured by the causal engine, and the diff penalty is capped at 10 points so a larger correct patch is not penalized over a smaller incorrect one. If omitted, `drift` defaults to the live trajectory drift.
</details>
---
<a id="-the-fixed-8-meta-tool-surface"></a>
## 🧰 The Fixed 8 Meta-Tool Surface
<details>
<summary><b>🔍 Click to expand: 8 Meta-Tools Specifications, Verified Payloads & Architectural Deep-Dives</b></summary>
<br>
OnyxSi exposes eight polymorphic meta-tools with a combined schema size of 1,593 tokens. The router enforces an 1,800-token hard ceiling at construction and refuses to start if it is exceeded.
| Meta-Tool | Operations | Purpose |
| :--- | :--- | :--- |
| `vfs_inspect` | `tree`, `skeleton`, `read`, `symbols`, `grammar`, `resolve` | Read-only inspection: directory maps, AST outlines, line ranges, exact/prefix symbol lookup, GBNF grammar export, `ref://` handle resolution. |
| `vfs_mutate` | `replace_file`, `replace_node`, `insert_after`, `slice_patch`, `merge_patches` | Stages a speculative edit in the in-RAM Ghost overlay. Disk stays untouched until commit. `merge_patches` applies non-overlapping agent patches and unifies imports. |
| `ghost_sandbox` | `begin`, `mutate`, `test`, `commit`, `discard`, `fork`, `switch_branch`, `list_branches`, `merge_best` | Ghost overlay lifecycle plus the in-RAM MCTS branch machinery. `test` runs blast-radius selection or an explicit command inside a shadow copy of the workspace. |
| `causal_flight` | `pre_flight`, `ghost_burn`, `verify`, `commit`, `reflect`, `bisect` | The 4-stage flight controller: declares blast radius, checks drift (<15%), re-parses staged files, logs the commit, resets the 3-strike budget, and binary-searches checkpoints for the culprit. |
| `hypothesis_branch` | `register`, `falsify`, `select` | Enforces orthogonal debugging hypotheses (Jaccard ≤ 0.70) with mandatory falsification probes, distilling failures into one-line negative lessons. |
| `wiki_task_sync` | `init`, `update`, `handoff`, `replay` | Project-namespaced task state: spec, progress JSON/Markdown, execution log, `AGENT_HANDOFF.md`, and the `TIME_TRAVEL_REPLAY.md` chronicle. |
| `graph_compute` | `engine=bm25` · `engine=blast_radius` · `engine=alu` (`type=eval`\|`matrix_matmul`\|`matrix_inv`\|`ieee754`) | Deterministic local compute: CSR+BM25 search, impacted-test selection, safe math evaluation, matrix algebra, IEEE-754 inspection. No LLM involved. |
| `mcp_orchestrate` | `steps[]` with `depends_on` | Runs meta-tools as one dependency-ordered DAG in a single round-trip; later steps read earlier output via `$prev.output` or `$<step>.output`. |
Every argument is validated against the declared JSON schema **before** a handler runs: unknown properties are rejected, enums are enforced, and a tool without a bound handler fails closed rather than echoing its input.
### 🔬 Verified Meta-Tool & Resource Schema Reference
The examples below show tested payloads from stdio JSON-RPC and Google Antigravity MCP sessions:
<details>
<summary><b>📋 Click to expand: Verified Payloads & Empirical Responses for all 8 Meta-Tools</b></summary>
#### 1. `vfs_inspect`: AST Outline & Read-Only Navigation
- **Operations (`action`):** `tree` · `skeleton` · `read` · `symbols` · `grammar` · `resolve`
- **Example Call:**
```json
{"name": "vfs_inspect", "arguments": {"action": "tree", "target": "src/onyxsi", "max_tokens": 500}}Verified Output: Compact hierarchical tree representation with token budget folding.
2. vfs_mutate: In-RAM Speculative Edits (Ghost-CoW)
Operations (
op):slice_patch·replace_file·replace_node·insert_after·merge_patchesExample Call:
{"name": "vfs_mutate", "arguments": {"op": "slice_patch", "path": "src/onyxsi/contracts.py", "start_line": 1, "end_line": 1, "code": "# contracts\n"}}Verified Output: In-RAM piece-table diff and staged hash; disk remains completely untouched until committed.
3. ghost_sandbox: In-RAM MCTS Branching & Isolated Shadow Tests
Operations (
cmd):begin·fork·test·switch_branch·list_branches·merge_best·commit·discardExample Call:
{"name": "ghost_sandbox", "arguments": {"cmd": "begin"}}Verified Output: Active session ID (
session_id) and branch table for branch isolation.
4. causal_flight: 4-Stage Trajectory & Drift Guard
Stages (
stage):pre_flight·ghost_burn·verify·commit·reflect·bisectExample Call:
{"name": "causal_flight", "arguments": {"stage": "pre_flight", "blast_radius": ["src/onyxsi/contracts.py"], "hypothesis": "Inspect contracts"}}Verified Output: Stage authorization, drift index check (<15%), and error budget counter verification.
5. hypothesis_branch: Orthogonal Debugging Exploration
Modes (
mode):register·falsify·selectExample Call:
{ "name": "hypothesis_branch", "arguments": { "mode": "register", "branches": [ {"branch_id": "H1", "statement": "Verify causal tracking", "target_nodes": ["contracts.py"], "probe": "probe_test"} ] } }Verified Output: Hypothesis registered with Jaccard divergence check (≤ 0.70) against competing hypotheses.
6. wiki_task_sync: Project-Namespaced Task & Replay Engine
Operations (
op):init·update·handoff·replayExample Call:
{"name": "wiki_task_sync", "arguments": {"op": "init", "task_id": "TASK-ANTIGRAVITY", "spec": "Verify Antigravity MCP"}}Verified Output: Isolated state persistence initialized under
.onyxsi/wiki/projects/<project>/tasks/.
7. graph_compute: Deterministic Local Compute ALU & Graph Engine
Engines (
engine):alu(type=eval|matrix_matmul|matrix_inv|ieee754) ·bm25(query) ·blast_radius(changed_files)Example Call:
{"name": "graph_compute", "arguments": {"engine": "alu", "type": "eval", "query": "2 + 2"}}Verified Output: Deterministic evaluation result (
4) computed in-process with 0 LLM latency.
8. mcp_orchestrate: Zero-Round-Trip Meta-Tool DAG Pipeline
Parameters:
steps[]withid,tool,arguments, and optionaldepends_onExample Call:
{ "name": "mcp_orchestrate", "arguments": { "steps": [ {"id": "s1", "tool": "graph_compute", "arguments": {"engine": "alu", "type": "eval", "query": "40 + 2"}} ] } }Verified Output: Multi-step pipeline output resolved and merged in a single transport cycle.
📦 Live MCP Resources
OnyxSi exposes direct state and compliance resources over the MCP protocol:
onyxsi://schema: JSON-RPC 2.0 schema for all eight meta-tools with exact token counts (1,593 tokens).onyxsi://audit: AST auditor report verifying zero third-party dependencies and zero UI packages.
1. In-RAM MCTS speculative forking
┌───────────────┐
│ main │ ← the baseline every branch forks from
└───────┬───────┘
┌────────────────┼────────────────┐
▼ ▼ ▼
┌────────────┐ ┌──────────────┐ ┌────────────┐
│ branch_fast│ │ branch_robust│ │ branch_alt │
│ score 41.0 │ │ score 99.99 │ │ score 62.5 │
└────────────┘ └──────────────┘ └────────────┘
│ │
└──── fork ──────┘
▼
┌──────────────┐
│ merge_best │ → winner stays active in RAM, losers are released
└──────────────┘
▼
ghost_commit() → one atomic write to diskEach branch owns its own piece-table documents and tombstones. Forking clones the source branch in RAM so mutations cannot corrupt parent branches. Switching branches requires only a pointer rebind with no copying, write-back, or state loss.
2. Autonomous AST antibody auto-vaccine
commit ──► diff(baseline, fixed)
│
├─ removed line ──► forbidden_pattern (blocks the reintroduction)
└─ added line ──► prescribed_alternative (the cure)
│
└─► AB-<sha256(file, pattern)[:10] ──► .onyxsi/wiki/projects/<p>/ANTIBODIES.jsonThe antibody generates only after a successful commit. A rolled-back write leaves no rules behind for unmerged code. The generated antibody_id uses a deterministic SHA-256 hash, so committing an identical fix never creates duplicate entries.
3. Time-Travel Chronicle
wiki_task_sync op=replay renders two sections: an ASCII decision tree of all explored branches and a table logging the 64-event ring buffer (Frame, Relative Time, Branch, Action, Target, Outcome). Writes are atomic.
🏛️ Architecture & System Topology
┌───────────────────────────────────────────────────────────────────────────┐
│ Layer 7 — MCP Daemon (server.py) │
│ JSON-RPC 2.0 over stdio · 8 fixed meta-tools │
└──────────────────────────────────────┬────────────────────────────────────┘
│
┌──────────────────────────────────────┴────────────────────────────────────┐
│ Layer 4 — Headless Gateway & Shields │
│ Fixed 8 Meta-Tools · Grammar Shield · Stream Folder · Policy Gate │
└───────────────┬───────────────────────┬───────────────────────┬────────────┘
│ │ │
┌───────────────┴──────────────┐ ┌──────┴──────────────┐ ┌──────┴──────────────┐
│ Layer 2 — ContextFS │ │ Layer 3 — DeltaFS │ │ Layer 5 — Causal │
│ Bitplane AST · Piece Table │ │ Ghost-CoW Overlay │ │ 4-Stage Flight │
│ Token Governor · ref:// │ │ MCTS Branching │ │ Error Budget · WAL │
│ Virtual Handles │ │ AST Lease & Merger │ │ Antibody Vaccine │
└───────────────┬──────────────┘ └──────┬──────────────┘ └──────┬──────────────┘
│ │ │
┌───────────────┴───────────────────────┴───────────────────────┴────────────┐
│ Layer 6 — Knowledge, Graph & Deterministic ALU │
│ Project-Namespaced Task Wiki · CSR Graph + BM25 · Blast-Radius Runner │
└──────────────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────────────────────────────┴────────────────────────────────────┐
│ Layer 1 — HAL: SHM Superblock · SPSC Ring · Radix Trie · Proc │
└──────────────────────────────────────┬─────────────────────────────────────┘
│
┌──────────────────────────────────────┴────────────────────────────────────┐
│ Layer 0 — Contracts & Error Codes (E0001 – E9004) │
└───────────────────────────────────────────────────────────────────────────┘The architecture consists of seven layers, verified at startup by the AST compliance auditor:
Layer | Module | Responsibility |
0 |
|
|
1 |
| 64MB shared-memory superblock (POSIX |
2 |
| SWAR/DBP bitplane AST scanner and skeleton pruner, memoryview piece table with nano-checkpoints, token ceiling governor, |
3 |
| Tier-0 Ghost-CoW overlay (now with MCTS branches), 4KB sparse page delta map with reflink + disk spillover to |
4 |
| Fixed 8 meta-tool router, deterministic JSON auto-repair shield, GBNF grammar exporter, macro pipeline fusion, stream folder, policy gate with secret masking. |
5 |
| 4-stage trajectory enforcer, 3-strike error budget, micro-WAL flight recorder, orthogonal hypothesis engine, in-RAM causal bisect, antibody memory with the auto-vaccine. |
6 |
| Project-namespaced task wiki, vectorless CSR graph + tuned BM25, blast-radius differential test runner, safe compute ALU. |
7 |
| The headless JSON-RPC 2.0 daemon and the MCP bridge. |
OnyxSi/
├── onyxsi-mcp.py # Zero-install UTF-8 MCP bridge
├── onyxsi-mcp.sh # Linux/macOS launcher wrapper
├── onyxsi-mcp.cmd # Windows batch launcher wrapper
├── opencode.jsonc # OpenCode MCP server definition
├── pyproject.toml # Build config (zero dependencies, MIT)
├── src/onyxsi/
│ ├── __init__.py # Root facade exposing Layers 0-6
│ ├── __main__.py # python -m onyxsi entry point
│ ├── server.py # JSON-RPC 2.0 stdio daemon
│ ├── contracts.py # OnyxError, OnyxErrorCode, path-segment sanitizer
│ ├── auditor.py # AST zero-dependency & zero-UI auditor
│ ├── hal/ # Layer 1
│ ├── contextfs/ # Layer 2
│ ├── deltafs/ # Layer 3
│ ├── gateway/ # Layer 4
│ ├── causal/ # Layer 5
│ └── knowledge/ # Layer 6
├── tests/
│ ├── run_tests.py # Zero-dependency stdlib test runner
│ ├── test_killer_features.py # Namespacing / MCTS / vaccine / replay / dispatch
│ ├── normal/ # 45 spec-verification modules
│ ├── street/ # 11 chaos, fuzz and concurrency modules
│ └── character/ # 10 end-to-end scenario modules
├── benchmarks/
│ ├── bench_onyxsi.py # Automated benchmark harness
│ ├── recall_eval.py # Labelled-corpus retrieval evaluator
│ ├── BENCHMARKS.md # Measured performance report
│ └── results_v1.0.json # Telemetry snapshot
└── md/ # Architectural blueprints & phase specsOn-disk state
<workspace>/.onyxsi/
├── leases/ # Cross-process AST leases
├── spill/ # CoW workspace disk spillover
├── FLIGHT_LOG.md # Stage 4 commit trail
├── CRASH_REPRO.md # Written on a daemon crash
└── wiki/
├── ANTIBODIES.json # Legacy store (still read)
└── projects/
└── <project>/
├── ANTIBODIES.json # Project-scoped vaccine
└── tasks/
└── TASK-<ID>/
├── TASK_SPEC.md
├── PROGRESS.json
├── PROGRESS.md
├── EXECUTION_LOG.md
├── AGENT_HANDOFF.md
└── TIME_TRAVEL_REPLAY.md📊 Verification & Empirical Metrics
Benchmark sources: Every metric below is drawn directly from benchmarks/results_v1.0.json, generated by running python benchmarks/bench_onyxsi.py on the test environment described below.
Telemetry Metric | Measured | Ceiling | Status |
Meta-tool schema footprint | 1,593 tokens | ≤ 1,800 | PASS |
Output token ceiling | 1,250 tokens | ≤ 1,250 | PASS |
Virtual handle resolvability ( | resolvable | true | PASS |
Bitplane AST scanner throughput | 35.98 MB/s | ≥ 20.0 MB/s | PASS |
Piece-table rollback latency (p95) | 0.0039 ms | ≤ 1.0 ms | PASS |
Ghost overlay discard latency (p95, 25 files) | 3.26 ms | ≤ 5.0 ms | PASS |
Blast-radius test selection (p95, 500 tests) | 0.625 ms | ≤ 5.0 ms | PASS |
Causal bisect search latency (p95, 64 steps) | 0.0105 ms | ≤ 1,000 ms | PASS |
Antibody check latency (p95) | 0.0051 ms | ≤ 5.0 ms | PASS |
CSR + BM25 hybrid search (p95, 5,000 nodes) | 5.70 ms | ≤ 50.0 ms | PASS |
JSON-RPC stdio round-trip (p95) | 0.52 ms | ≤ 50.0 ms | PASS |
Held-out retrieval Hit@5 (150 queries) | 54.67% | ≥ 50.0% | PASS |
Held-out retrieval Recall@5 (150 queries) | 39.11% | ≥ 30.0% | PASS |
Measurement environment: Windows 11 · AMD64 · 8 logical CPUs · Python 3.15.0rc2 · benchmarks/results_v1.0.json (Updated 2026-10-21).
⚡ Multi-Runtime & Dual-OS Benchmark Comparison
Comparison across deployment environments tested on the same physical hardware:
Invariant / Telemetry Metric | Windows 11 (Py 3.12.10) | Windows 11 (Py 3.15.0rc2) | WSL2 Ubuntu (Py 3.14.4) | Target Ceiling | Status |
Bitplane AST Scanner Throughput | 26.54 MB/s | 35.98 MB/s | 43.29 MB/s | $\ge$ 20.0 MB/s | PASS |
Piece-Table Rollback (p95) | 0.0054 ms | 0.0039 ms | 0.0031 ms | $\le$ 1.0 ms | PASS |
Ghost Overlay Discard (p95) | 3.27 ms | 3.26 ms | 0.33 ms | $\le$ 5.0 ms | PASS |
Blast-Radius Test Selection (p95) | 0.631 ms | 0.625 ms | 0.472 ms | $\le$ 5.0 ms | PASS |
Causal Bisect Latency (p95) | 0.0122 ms | 0.0105 ms | 0.0089 ms | $\le$ 1,000 ms | PASS |
Antibody Vaccine Check (p95) | 0.0049 ms | 0.0051 ms | 0.0045 ms | $\le$ 5.0 ms | PASS |
CSR Graph + BM25 Search (p95) | 6.47 ms | 5.70 ms | 5.94 ms | $\le$ 50.0 ms | PASS |
JSON-RPC stdio Round-Trip (p95) | 0.56 ms | 0.52 ms | 0.12 ms | $\le$ 50.0 ms | PASS |
Full Benchmark Suite Wall Clock | 1.76 s | 1.47 s | 1.74 s | — | ALL PASS |
Measurement details: The AST skeleton pruner reports the measured ratio (skeleton ÷ source = 0.683, roughly 32% smaller than original source files across the benchmark corpus) rather than theoretical estimates. Retrieval evaluations use held-out test data without docstring leakage. While indexing docstrings directly yields an artificial 100% Hit@5, held-out retrieval reflects actual search performance.
Test suite
# Full suite under pytest
python -m pytest -v
# Same suite, zero third-party dependencies
python tests/run_tests.py
# Reproduce the benchmark table
python benchmarks/bench_onyxsi.pySuite | Scope |
| 1:1 specification verification across every layer: superblock, SPSC ring, bitplane AST, piece table, ghost overlay, leases, merger, router, grammar shield, trajectory, error budget, hypothesis engine, bisect, antibody, task wiki, CSR+BM25, blast runner, ALU, daemon, MCP protocol. |
| Fuzzing: unclosed JSON brackets, circular DAG pipelines, lease races, concurrent writers, simulated power cuts during atomic writes, boundary conditions. |
| End-to-end personas: amnesiac handoffs, rapid single-byte patching, deep recursion bombs, hostile string manipulation, multi-agent swarms. |
| The v1.0.0-PROD features: project namespacing, Time-Travel Chronicle, MCTS forking and merge, the auto-vaccine, and JSON-RPC dispatch. |
Result: 669 tests passing, 0 failures. Verified on Windows (Python 3.12.10, Python 3.15.0rc2) and Ubuntu WSL2 (Python 3.14.4 / pytest 9.0.2).
🚀 Installation & Quick Start
Prerequisites: Python 3.11 or newer. Nothing else.
# Option 1 (zero install): run straight from the checkout
python onyxsi-mcp.py --workspace /path/to/your/project
# Option 2 (install as an editable package):
pip install -e .
onyxsi --workspace /path/to/your/project# Linux / macOS
./onyxsi-mcp.sh --workspace /path/to/your/project
# Windows
onyxsi-mcp.cmd --workspace C:\path\to\your\project☕ Support & Sponsor
If OnyxSi is useful in your agent workflows or saves context tokens, consider supporting continued development:
📜 License
MIT license. See LICENSE. Copyright © 2026 xTanTHaix.
Deterministic, headless, and dependency-free by construction.
Available Tools
8 toolscausal_flightA
4-stage flight recorder. pre_flight declares blast radius; ghost_burn checks drift (<15%); verify re-parses staged files; commit logs; reflect resets the 3-strike budget; bisect finds the culprit checkpoint. USE WHEN: before/after any non-trivial edit. DO NOT USE: instead of running the affected tests.
Inputs: stage (required), target, strategy, hypothesis, +2 more.
ghost_sandboxB
Ghost overlay lifecycle: begin, mutate (path+content), test (blast-radius selection, or an explicit command run in a shadow copy of the workspace), commit (atomic, fsync+replace), discard, plus fork / switch_branch / list_branches / merge_best for in-RAM MCTS branches. USE WHEN: you need speculative edits, a rollback point, competing fixes, or to run the project's own tests against staged content. DO NOT USE: before knowing the blast radius.
Inputs: cmd (required), path, scores, command, +5 more.
graph_computeA
Deterministic local compute. engine=bm25 (CSR+BM25 search) | blast_radius (select+run impacted tests) | alu (type=eval | matrix_matmul | matrix_inv | ieee754). USE WHEN: locating code, checking test impact, or arithmetic without an LLM. DO NOT USE: for free-form reasoning or file edits.
Inputs: engine (required), bits, type, query, +3 more.
hypothesis_branchB
Orthogonal hypotheses (Jaccard <= 0.70) with falsification probes. mode=register|falsify (pass the observed probe_succeeded)|select. USE WHEN: several plausible root causes to prune. DO NOT USE: to run the probe.
Inputs: mode (required), lesson, branches, hypothesis_id, +1 more.
mcp_orchestrateA
Run meta-tools as one dependency-ordered DAG; later steps read earlier output via '$prev.output' or '$.output'. USE WHEN: a fix needs inspect->mutate->test in one round-trip. DO NOT USE: for one call, parallel work, or nesting.
Inputs: steps (required).
vfs_inspectA
Read-only view: action=tree (dir map), skeleton (AST outline), read (line range), symbols (exact/prefix symbol lookup), grammar (GBNF export), resolve (canonical path or ref:// handle). USE WHEN: orienting, reading code, fetching folded content, finding a symbol, or checking the tool grammar. DO NOT USE: to write or run tests.
Inputs: action (required), mode, query, target, +3 more.
vfs_mutateA
Stage a write in the in-RAM Ghost overlay (disk untouched until commit). op=replace_file (default) | replace_node | insert_after | slice_patch | merge_patches (non-overlapping agent patches, unified imports). USE WHEN: applying a speculative code edit. DO NOT USE: for reads, or before causal_flight pre_flight.
Inputs: path (required), op, code, node_id, +4 more.
wiki_task_syncA
Persist task state in .onyxsi/wiki/projects//tasks/TASK-/ (spec, progress, log), render AGENT_HANDOFF.md, and write TIME_TRAVEL_REPLAY.md. op=init|update|handoff|replay. USE WHEN: starting work, checkpointing, handing off. NOT a scratchpad; it writes real files.
Inputs: op (required), task_id (required), spec, frames, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools occupy distinct phases (read, mutate, compute, orchestrate), and descriptions include explicit USE/DO NOT USE boundaries. However, vfs_mutate and ghost_sandbox both stage mutations in the Ghost overlay, and graph_compute overlaps slightly with vfs_inspect for code location, so an agent could confuse those boundaries.
All names use lowercase snake_case without camelCase or inconsistent casing. The structure is not a strict verb_noun pattern; some are domain-prefixed actions (vfs_inspect), others are noun compounds (ghost_sandbox, causal_flight), but it remains readable and predictable.
Eight tools are well-scoped for a speculative coding agent workflow, and each covers a distinct capability area (inspect, mutate, compute, sandbox, flight recorder, hypotheses, task sync, orchestration). No obvious redundancy that bloats the surface.
The set covers the core lifecycle: inspect, search/compute, speculative mutation, sandbox testing/commit/discard, causal tracking, hypothesis falsification, task persistence, and orchestration. Minor gaps exist around direct task query/list/delete or explicit file creation/deletion, but agents can likely work around them via overlay and wiki operations.
Maintenance
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to checkpoint workspace state, branch parallel attempts, inspect diffs, and roll back to known-good states mid-task through MCP tools, with automatic safety checkpoints to prevent data loss.6 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to perform software engineering tasks inside an isolated, deterministic sandbox—exploring repositories, reproducing failures, applying patches, running tests, and verifying solutions against hidden suites through MCP tools.8MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to inspect files, search text, compare directories, read symbols, and apply structured edits against large codebases through bounded, local-first MCP tools.4Apache 2.0
- AlicenseBqualityBmaintenanceEnables AI coding agents and local LLMs to store and recall project memory, compact verbose logs, look up code symbols, create and rewind workspace snapshots, detect risky commands and loops, pack context optimally, and draft tokens through MCP tools.102Apache 2.0