convez.ai
MCP Server
brianonbased-dev

HoloScript

brianonbased-dev/HoloScript

Ver no GitHub
BomPluginScore · de 0 a 100

The semantic layer for spatial computing and AI agents — write once, run as VR, robotics, web, or game.

Instalação

$npx convez-ai brianonbased-dev/HoloScript

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
0
Acompanhando
2
Saúde
100%
Último commit
há 1 dia
Versão
v7.0.0
Issues abertas
85
Contribuidores
9

README

A tradução para o português deste README ainda está na fila.

HoloScript

Build your own games and apps — no coding, no data handed to Big Tech, no lock-in. Describe what you want; HoloScript turns it into a real, running creation you own, and runs it anywhere you need.

Anyone can create — and developers, teams, and AI agents build on the same engine. You (or an agent) describe what you want in .holo, .hsplus, or .hs files — screens, scenes, services, data, devices, agent workflows. HoloScript runs those files directly while you iterate, then translates the same source when you need code for a browser, engine, robot, service, or deployment. Because it compiles to your choice of platform, your creation moves with you — no single vendor can lock it in.

Think of it as three practical pieces:

  • readable project files for what should exist and how it should behave
  • a runner that can execute those files before you choose a final platform
  • tools that turn the same source into apps, scenes, services, agent tools, and deployment artifacts

Use this to connect an AI coding agent to HoloScript tools:

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

Try it without an API key

  • npx create-holoscript@latest my-app - scaffold a HoloScript app with a browser scene in under a minute.
  • npm install @holoscript/cli - use the local CLI; npm install @holoscript/wasm adds in-browser parsing.
  • https://holoscript.studio/playground - try the live editor and WebGPU preview with no login.
  • POST mcp.holoscript.net/api/public/tool - call read-only public tools for parsing, validation, examples, syntax help, explanations, and target lists. 30 req/min per IP.
  • POST mcp.holoscript.net/oauth/register - register a client yourself when you need the full set of tools. No human approval step.

Full reference: docs/PUBLIC_ACCESS.md.

Why teams choose HoloScript

HoloScript helps when the same product idea has to show up in too many places: a browser preview, engine export, service API, agent workflow, robotics simulation, internal tool, or digital twin. Instead of burying the idea in framework-specific glue, it keeps the intent in a readable source file that humans can review, agents can edit, and HoloScript can run.

1) Describe the thing, not the glue

Use .holo, .hsplus, or .hs files to define behavior, data, interfaces, objects, and workflows. Run them directly, then translate them to platform code when that is worth it.

2) Give agents something solid to work with

HoloScript includes task boards, MCP tools, connectors, permissions, and traits so agents can inspect a system, make bounded changes, and report what they did.

3) Keep deployment paths open

The same composition can feed multiple outputs: renderers, services, robotics, web runtimes, and more. If a translation is not ready, HoloScript can still run the source.

4) Compose real product capabilities

Add production concerns as traits instead of one-off glue:

  • 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 with one use case, grow from there

Start with a dashboard, workflow, agent task, or 3D scene. Add traits and plugins as the work grows, without rewriting the core idea.

HoloScript is not trying to replace every tool in your stack. It keeps the intent portable so each target can still do what it does best.

Who this is for

  • Product teams: a faster path from idea to running prototype.
  • Platform engineers: one readable source for outputs that would otherwise split across stacks.
  • Agent builders: files, tools, and checks agents can inspect before acting.
  • Research / simulation teams: developer-facing solvers and repeatable workflows with provenance and replay hooks.

One-line outcomes by role

If you are a...Describe thisGet this
Game / XR developercomposition "Dungeon" { object "Chest" @grabbable @physics { ... } }Your scene runs on Unity, Unreal, Godot, or React Three Fiber from one source you own — you pick the target, you're never locked to it
AI agent builderagent "Brittney" { tool: generate_scene, tool: deploy_service, ... }MCP tools with typed inputs, permissions, and live inventory verified via GET /health
Simulation engineersimulation "WindTunnel" { solver: fea, mesh: tet10, boundary: ... }TypeScript-accessible solvers with replay/provenance hooks; verify geometry, meshing, boundary conditions, and V&V depth before scientific use
Founder / product teamservice "BillingAPI" { route: /invoice, method: POST, ... }Node.js service scaffold with observability, metering, and rollback hooks

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

Example stories in the repo

The example files are part of the pitch. They show how the three HoloScript formats carry different kinds of intent:

FormatExampleWhat it helps someone picture
.hsexamples/pipelines/inventory-sync.hsA scheduled POS inventory sync: source, transform, validate, and sink.
.hsplusexamples/three-format-showcase/smart-gallery.hsplusA gallery that grows from objects into templates, state, interactions, and audio.
.holoexamples/iot/holotwin-smart-farm.holoA smart farm dashboard where MQTT sensors drive a 3D digital twin.
.holoexamples/novel-use-cases/05-robot-training-metaverse.holoA robot training arena that links simulation, agents, feedback, and ROS-style targets.

Use these when explaining HoloScript to a new person: start with the story, then show the format that carries it.

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:

GapClosest ExistingDistance
Geolocation / GISGeospatialAnchorTrait, RooftopAnchorTraitClose — AR anchoring exists, mapping layer doesn't
Calendar / Scheduling@cron, @scheduler, @task_queueMedium — job scheduling exists, calendar UI doesn't
CRM@tenant, @session, @analyticsFar — primitives exist, CRM workflow doesn't
Inventory@database, @data_transformFar — data traits exist, inventory domain doesn't
Logistics / ShippingSCMCompiler (supply chain)Medium — compiler exists, trait coverage thin
Real EstateSpatial rendering + @digital_twinMedium — visualization ready, domain traits missing
Agriculture@iot_sensor, @digital_twin, @telemetryMedium — IoT foundation covers hardware
Energy / Utilities@iot_sensor, @mqtt_bridge, @digital_twinMedium — same IoT foundation
Legal / Contracts@approval, @audit_log, @consent_managementMedium — compliance exists, legal workflow doesn't
Government / Civic@audit_log, @rbac, @gdprMedium — compliance traits, no civic domain

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.

Architecture — the 6-layer stack

HoloScript is a 6-layer open platform. The same model anchors the landing page and this repo, so the story reads the same whether someone (or an agent) starts from the site or the source.

LayerWhat it isWhere it lives
6 · MarketplaceTraits + plugins + skills, Ed25519 signatures, x402 paymentsstore.holoscript.net, packages/plugins/
5 · StudioAI scene builder, browser workflow, node-graph editorpackages/studio/
4 · AgentsSwarm intelligence, MCP comms, economy primitivespackages/mcp-server/
3 · CompilerNamed backends, cross-target compilation, circuit breaker, incremental buildspackages/core/src/compiler/
2 · RuntimeThree.js browser, Rust spatial engine, WebGPU renderingpackages/r3f-renderer/, packages/snn-webgpu/, packages/compiler-wasm/
1 · OS CoreCognitive (uAAL), perceptual (SNN), economic (x402), semantic traitspackages/core/

The layers are architectural, not counts — they don't go stale. Ecosystem counts (tools, traits, compilers) are never hardcoded here; see What to verify live.

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. When a workflow is actually backed by SimulationContract, it can bind geometry hashes, unit validation, deterministic stepping, and replay evidence. Do not treat visual previews as solver evidence unless the contract path emitted the receipt.

Scientific foundation under active verification. The paper program frames trust as composable provenance rather than marketing copy. Current public claims should point to rerunnable evidence, not cached numbers or old pitch decks.

  • Trust by Construction: SimulationContract replay, unit checks, and structural convergence evidence; rerun the solver benchmarks before citing a convergence number.
  • 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:

TargetOutput
unityC# MonoBehaviour
r3fReact Three Fiber JSX
urdfROS 2 / Gazebo robot XML
godotGDScript scene
visionosRealityKit Swift
native-2dStandalone HTML page
node-serviceExpress.js skeleton
a2a-agent-cardA2A Protocol agent manifest
nirNeuromorphic IR (Loihi 2, SpiNNaker)

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

ExtensionPurposeExamples
.hsData pipelines, ETL, transformsCompiles to Node.js, JSON. Source → transform → sink workflows
.hsplusBehaviors, agents, economics, IoTTraits for networking, AI, state machines, digital twins, ZK proofs
.holoCompositions, scenes, dashboardsCross-platform AI-generated. Runtime interprets directly

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

Versioning

Package versions are lane-managed, and not every package shares the same major. Check package.json, packages/*/package.json, and the Release Versioning Guide before publishing or citing a version.

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.

RouteWhat it does
/startGitHub OAuth onboarding. Provisions API key, scaffolds project
/vibeDescribe what you want. Brittney AI generates it
/createFull IDE — Monaco editor, 3D viewport, shader graph, timeline, collaboration
/pipelineData pipeline builder — source, transform, sink workflows
/registryPackage registry — browse, publish, install
/integrationsThird-party connectors (GitHub, Railway, App Store, Upstash)
/operationsOps dashboard — deploy status, service health, cost tracking
/absorbCodebase intelligence — scan, query, impact analysis
/holomeshAgent social network — knowledge feed, profiles, leaderboard, marketplace
/holomesh/marketplaceTrait marketplace — discover, rate, install, monetize
/teamsPrivate workspaces with RBAC, task boards, agent fleet
/agentsAgent fleet management — launch, monitor, deploy

Numbers

MetricHow to verify (SSOT)
MCP toolscurl https://mcp.holoscript.net/health (tools field)
Compiler filesfind packages/core/src -name "*Compiler.ts" -not -name "CompilerBase*" -not -name "*.test.*"
Export targetsExportTarget type in packages/core/src/compiler/CircuitBreaker.ts
Trait filesfind packages/core/src/traits -name "*.ts" -not -name "*.test.*"
Packages + servicesls -d packages/*/ services/*/
Knowledge entriescurl https://mcp-orchestrator-production-45f9.up.railway.app/health (knowledge_entries)
Pluginsls -d packages/plugins/*/

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, and npm publishing is guarded. Treat that file and each package manifest as the source of truth instead of copying a version into docs.

  • 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


Package versions live in the repo manifests · MIT License

Ver o original no GitHub

Bom para

Relacionados