Skip to main content
Glama

⚡ 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


Python Version Dependencies Platforms License Tests Boot Audit Schema Rollback Ghost CoW Antigravity OpenCode Claude Desktop Protocol

Why OnyxSi • Connect MCP • Live Transcript • 8 Meta-Tools • Architecture • Benchmarks • Installation


IMPORTANT

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 ref:// handles above 1,250 tokens.

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 .onyxsi/wiki/projects/<project>/, so nothing bleeds across workspaces.

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 TIME_TRAVEL_REPLAY.md, readable anytime without extra tools.

🎬 The Architectural Narrative

Figure 1: The Entropy of Modern Coding Agents
Coding agents commonly struggle with three structural issues:

  1. Context Bloat: Dozens of micro-tools consume thousands of prompt tokens on definitions alone before reading a single line of code.

  2. Destructive Edits: Unbuffered disk writes corrupt working trees during multi-step edits, leaving broken builds behind.

  3. 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• vfs_inspect & vfs_mutate: Zero-copy AST inspection and RAM-buffered edits• hypothesis_branch & ghost_sandbox: Ephemeral shadow execution• causal_flight & wiki_task_sync: Trajectory verification and task state• graph_compute & mcp_orchestrate: Deterministic ALU & DAG pipelines

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 .onyxsi/wiki/• Decision Trees: Records every branch evaluated during an edit• Ring Buffer Log: Tracks relative timestamps, actions, and test results in TIME_TRAVEL_REPLAY.md

📊 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 ref:// handles• 3.9 μs (0.0039 ms): Ghost-CoW rollback latency (p95)• 669 Passed Tests: Zero failures across chaos, fuzzing, and scenario suites

Pure Python stdlib headless orchestration• Zero Installation: Runs directly from checkout with python onyxsi-mcp.py• Standard Stdio MCP: Connects directly to Google Antigravity, OpenCode, and Claude Desktop• Minimal Setup: No Node.js runtime, compilers, or UI processes


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"
      }
    }
  }
}
TIP

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 }
      }
    }
  }
}
TIP

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 + b

Step 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_patches

  • Example 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 · discard

  • Example 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 · bisect

  • Example 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 · select

  • Example 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 · replay

  • Example 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[] with id, tool, arguments, and optional depends_on

  • Example 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 disk

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

The 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

onyxsi.contracts

OnyxError / OnyxErrorCode (E0001–E9004) and the shared data contracts.

1

onyxsi.hal

64MB shared-memory superblock (POSIX /dev/shm + Windows tagged mmap), lock-free SPSC ring buffer, flat array('I') radix trie, process supervisor, syscall guard, sandbox enclave, non-blocking cross-process wakeup, telemetry ring.

2

onyxsi.contextfs

SWAR/DBP bitplane AST scanner and skeleton pruner, memoryview piece table with nano-checkpoints, token ceiling governor, ref:// virtual handle registry, workspace scanner.

3

onyxsi.deltafs

Tier-0 Ghost-CoW overlay (now with MCTS branches), 4KB sparse page delta map with reflink + disk spillover to .onyxsi/spill/, granular AST node leases, conflict-free bottom-up patch merger.

4

onyxsi.gateway

Fixed 8 meta-tool router, deterministic JSON auto-repair shield, GBNF grammar exporter, macro pipeline fusion, stream folder, policy gate with secret masking.

5

onyxsi.causal

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

onyxsi.knowledge

Project-namespaced task wiki, vectorless CSR graph + tuned BM25, blast-radius differential test runner, safe compute ALU.

7

onyxsi.server

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 specs

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

NOTE

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 (ref://)

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

IMPORTANT

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

Suite

Scope

tests/normal/ (45 modules)

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.

tests/street/ (11 modules)

Fuzzing: unclosed JSON brackets, circular DAG pipelines, lease races, concurrent writers, simulated power cuts during atomic writes, boundary conditions.

tests/character/ (10 modules)

End-to-end personas: amnesiac handoffs, rapid single-byte patching, deep recursion bombs, hostile string manipulation, multi-agent swarms.

tests/test_killer_features.py

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 tools
causal_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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to inspect files, search text, compare directories, read symbols, and apply structured edits against large codebases through bounded, local-first MCP tools.
      4
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      10
      2
      Apache 2.0