HoloScript

Describe what you want. It runs everywhere.

HoloScript is a semantic runtime where descriptions become working software. Write .holo, .hsplus, or .hs — the runtime interprets it directly. Compilers optimize for specific platforms when you need them. If a compiler breaks, the runtime still works.

{
  "mcpServers": {
    "holoscript": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.holoscript.net/mcp"]
    }
  }
}

Why teams choose HoloScript

HoloScript is for teams that want to describe intent once and execute it across many targets.

1) Write intent, not glue code

Use semantic files (.holo, .hsplus, .hs) to define behavior, data, and interfaces.
The runtime executes directly. Compilers optimize where available.

2) Build agent-native systems

HoloScript includes board workflows, MCP integration, connectors, and composable traits so agents can discover work, execute, and report with structured outputs.

3) Keep deployment paths flexible

The same composition can target multiple outputs (renderers, services, robotics, and more). If a compiler path is unavailable, runtime interpretation keeps your workflow alive.

4) Compose real product capabilities

Trait groups cover common production needs:

• payments and economy
• compliance and auditability
• search and data pipelines
• collaboration and synchronization
• observability and incident response
• AI/ML and agent orchestration
• IoT, simulation, and digital twins

5) Start small, scale systemically

Most teams begin with one use case (dashboard, workflow, agent task, or spatial scene) and expand by composing additional traits and plugins instead of rewriting infrastructure.

Who this is for

• Founders / product teams: faster path from idea to running prototype.
• Platform engineers: one semantic layer for multi-target outputs.
• Agent builders: deterministic interfaces and task-driven execution loops.
• Research / simulation teams: provenance-aware workflows with replayability hooks.

One-line outcomes by role

Example outcomes

• "Describe a service" -> compile to backend/service targets
• "Describe a scene" -> compile to spatial/render targets
• "Describe a robot" -> export to robotics/simulation targets
• "Describe an agent workflow" -> execute via board + tool ecosystem

What to verify live

HoloScript avoids hardcoded ecosystem counts in docs. Verify current numbers from live sources:

• MCP tool count: https://mcp.holoscript.net/health
• Knowledge entries: https://mcp-orchestrator-production-45f9.up.railway.app/health
• Compiler/trait/package counts: see SSOT commands in docs/NUMBERS.md

Honest gaps

These verticals have foundation traits but no dedicated domain coverage yet:

Every gap shares the same pattern: the infrastructure traits exist, the domain plugin doesn't. The plugin system (packages/plugins/) is designed exactly for this — add domain-specific traits without touching core.

Vertical README epics (optional backlog): some packages have deep READMEs, others are stubs. Tracked in docs/vertical-readme-epics.md for prioritization; split into one board child task per vertical when a row is ready to ship.

How it composes (the loops)

Individual traits solve individual problems. When you wire them together, autonomous loops emerge:

Description → running business. .holo → generate_service_contract → compile_to_node_service → connector-railway (deploy) → economy (meter) → observability (monitor) → self-improve (iterate). One file produces a deployed, metered, monitored, improvable service.

Self-healing infrastructure. Circuit breaker + health check + canary + rollback + incident + agent orchestration + PagerDuty. Detects its own failures, routes around them, rolls back, recovers — no human in the loop.

Recursive knowledge compounding. Absorb scans code → extracts W/P/G → publishes to knowledge store → other agents consume → write better code → absorb scans again. Every cycle, the ecosystem knows more.

Agent economy. Agent creates trait → publishes to marketplace with signing → another agent discovers, installs, pays → revenue splits → creator reinvests. Agents paying agents for work product.

Cross-reality coordination. CRDT + presence + sync + connectors. Same composition state live in VS Code, browser, phone, headset, and IoT device simultaneously — with conflict resolution.

Full provenance chain. CAEL (Continuous Agentic Event Logging) records the perception → cognition → action → physics loop in a tamper-evident hash chain. The SimulationContract enforces physical guarantees (geometry hash, unit validation, deterministic stepping), ensuring the render model IS the solver model. Trust is compositional from shader to neural spike.

Scientific Foundation (8-Paper Program). HoloScript is the first platform where trust is algebraically composable via the provenance semiring (tropical min-plus/max-plus).

• Trust by Construction: Provable simulation accuracy (TET10 convergence p=1.99).
• CAEL Agent Contracts: Hash-chained, replayable, and forkable agent thoughts.
• Trustworthy Tool Use: independent trace replay for MCP tool verification.
• Browser-Native SNN: neuromorphic computing via WebGPU compute shaders (verify benchmarks live).
• Conflict-Free Spatial State: spatial CRDTs resolved via physics-native replay.
• Sandboxed Embodied Simulation: AI-generated physics verified in V8 isolates.
• GraphRAG Self-Understanding: provenance-backed codebase intelligence queries.

Semantic data platform. Any data source → .holo → transform → vector DB + search → compile to dashboard, API, or spatial interface.

Autonomous fleet operations. Swarm intelligence + agent lifecycle + negotiation + economy + board + skills. A fleet that discovers work, negotiates who does it, executes, bills, and reports.

Quick Start (30 seconds)

Try the API — no install needed:

curl -s -X POST https://mcp.holoscript.net/api/compile \
  -H "Content-Type: application/json" \
  -d '{"code": "composition \"Hello\" { object \"Cube\" { @physics geometry: \"box\" position: [0,1,0] } }", "target": "unity"}' \
  | python -m json.tool

PowerShell:

curl -s -X POST https://mcp.holoscript.net/api/compile `
  -H "Content-Type: application/json" `
  -d '{"code": "composition ""Hello"" { object ""Cube"" { @physics geometry: ""box"" position: [0,1,0] } }", "target": "unity"}' |
  ConvertFrom-Json |
  ConvertTo-Json -Depth 100

Change "target" to get different platforms from the same input:

All registered targets work the same way — same .holo input, different output. Full list: ExportTarget in packages/core/src/compiler/CircuitBreaker.ts.

See it in a browser:

curl -s -X POST https://mcp.holoscript.net/api/compile \
  -H "Content-Type: application/json" \
  -d '{"code": "composition \"Store\" { object \"Product\" { @label(text: \"Demo\") @gauge(value: 99, unit: \"%\") geometry: \"box\" } }", "target": "native-2d"}' \
  -o demo.html && open demo.html

Scaffold a project:

npx create-holoscript my-world
cd my-world && npm install && npm run dev

Develop on the repo:

git clone https://github.com/brianonbased-dev/HoloScript.git
cd HoloScript && pnpm install && pnpm build && pnpm test

Agent validation (TypeScript): After touching packages/*, run pnpm preflight so only changed packages are typechecked (fast, Windows-safe spawns). Narrow to TS only with pnpm preflight --check=typescript,ts. For dependency posture, use pnpm run health:deps or pnpm preflight --check=dependency_audit; both use the bounded pnpm audit wrapper and emit structured JSON/SKIP instead of hanging. Before a large merge, use pnpm preflight --full (all packages; slower). Flags and checks live in scripts/preflight.mjs.

Three file formats

TypeScript is the last resort — for parsers, CLI, adapters, infrastructure. If you're writing .ts for business logic, you're doing it wrong.

Versioning

npm and PyPI packages share the same major version. See the Release Versioning Guide.

Agent quick reference

For agents connecting via MCP — what's available beyond the problems listed above.

Local checks: pnpm preflight (changed packages) · pnpm preflight --check=typescript,ts (TS only) · pnpm run health:deps (bounded dependency audit) · pnpm preflight --full (entire monorepo TS sweep plus dependency audit).

HoloDoor (security guardrails): Use docs/agents/holodoor-mcp.md. Corridor is deprecated; policy, hooks, and MCP validation live in the ai-ecosystem repo.

Connectors (deploy anywhere): connector-github (repos, PRs, CI/CD), connector-railway (deploy, envs, logs, costs), connector-appstore (TestFlight, Play Store), connector-upstash (Redis, vector search, QStash), connector-vscode (IDE sync), connector-core (build your own).

IDE intelligence (via MCP): hs_scan_project, hs_diagnostics, hs_autocomplete, hs_refactor, hs_docs, hs_code_action, hs_hover, hs_go_to_definition, hs_find_references — full LSP-equivalent over MCP.

Self-improvement (via MCP): Agents modify the codebase through MCP — holo_write_file, holo_edit_file, holo_read_file, holo_git_commit, holo_run_tests_targeted, plus refactoring and scaffolding. The codebase improves itself.

Service contracts: generate_service_contract turns any OpenAPI spec into a .holo composition. explain_service_contract analyzes existing ones. Any REST API becomes a HoloScript composition.

Domain plugins: medical-plugin (DICOM, surgical training), scientific-plugin (molecular dynamics), robotics-plugin (ROS 2, digital twins), alphafold-plugin (protein folding), radio-astronomy-plugin (interferometers, pulsars), web-preview.

Absorb — point it at your data

# Scan a GitHub repo into a knowledge graph
absorb_run_absorb({ repo: "https://github.com/your/repo" })

# Ask questions about it
holo_ask_codebase({ query: "how does auth work?" })

# Map a CSV to traits
holoscript_map_csv({ headers: ["name","price","image_url","category"] })

Works with codebases (TypeScript, Python, Rust, Go), CSVs, JSON schemas, and plain language descriptions. Absorb docs

Studio

Browser-based universal IDE. Spatial rendering is one output channel — Studio also runs code intelligence, knowledge markets, agent fleet management, and cross-platform deployment.

Numbers

Every number in this README points to a live source. If a number is hardcoded, it's wrong — verify and fix it.

Release

HoloScript release lanes are managed under scripts/version-policy.json (for example, the platform-v6 lane id targets major 7 after the 2026-04 platform release), and npm publishing is now guarded.

• Use pnpm release:publish for production publish flows.
• Raw pnpm publish at repo root is intentionally blocked.
• Guard checks run via node scripts/release-guard.js (git cleanliness, strict version policy, private package rules, semver validation, and tag awareness).

Links

• Operator runbook — deployment smoke checks, incidents, rollback
• Full feature reference — compilers, renderers, identity, domain blocks, GPU pipelines
• Compile API — live at mcp.holoscript.net
• Absorb service — codebase intelligence
• Studio — universal IDE
• Academy — learning path
• TypeScript API reference — TypeDoc output (run pnpm docs:api locally → docs/api/)
• Examples — copy-paste starting points
• Strategy — roadmap and vision
• Universal IR Coverage — how HoloScript bridges 3D ecosystem tools
• Plugins — domain extensions

v7.0.0 · MIT License