starter-shell 0.1.1

A starting shell for any application. Adapts to your hardware.

🔮 Starter Shell

A starting shell for any application. Clone it, run it, and it adapts to your hardware — discovers compilers, connects to the fleet's knowledge graph (PLATO), creates rooms, files tiles, and runs the agent loop.

git clone https://github.com/SuperInstance/starter-shell.git
cd starter-shell
python3 setup.py my-project-name

That's the whole setup. You're now a fleet of one.

---

What Is a Shell?

A hermit crab outgrows its shell. It doesn't break the old one — it finds a new one. The old shell becomes a home for the next crab. Nothing is wasted. The beach accumulates better shells over time.

A git repository is a shell. An agent crawls into it, starts committing, and leaves it better than it was found. The next agent inherits everything the previous one learned. The shell outlives every inhabitant.

You are the hermit crab. The shell is your workspace — your repo, your project, your agent. You improve it while you're in it. When you outgrow it, you find a bigger one. The old one stays on the beach, waiting for the next crab.

The shell has two surfaces:

• Inside: The knowledge — PLATO tiles, commit logs, agent journals. This is what the agent sees.
• Outside: The interface — README, 3D rooms, CLI tools. This is what humans see.

They're the same shell, viewed from opposite sides.

---

Why Build with Shells?

Every AI system today follows the same pattern: one giant model, one prompt, one response. If you want it to do more, you make the model bigger. Bigger models hallucinate more, cost more, and still can't do reliable multi-step reasoning.

We build differently. Instead of one giant model that knows everything, we build rooms. Each room is a constraint boundary — it defines what exists, what normal looks like, what actions are valid. The engine room has temperature gauges and thermal cameras. The wheelhouse has radar and charts. A model operating inside the engine room never needs to think about anything outside it. The room IS the context.

A small model inside a well-structured room outperforms a large model with no structure. Forgemaster's FLUX runtime proved this on real hardware — a Python implementation running on one CPU core (84ns per operation) beat a C implementation with full compiler optimization (256ns) for small primitives. The overhead of crossing a language boundary cost more than the computation. The room structure was the intelligence. The model just followed it.

The starter shell gives you that room structure. The hardware detection, the PLATO connection, the agent loop — these are the walls of your first room.

---

What You Get

File	What it does
hardware.py	Detects CPU, memory, compilers, GPU, available languages
plato.py	Connects to PLATO (the fleet's knowledge graph), creates rooms, files tiles
agent.py	Runs the probe→discover→test→pick→remember→walk loop
setup.py	Runs everything above in one command

hardware.py probes the machine it's running on. It finds compilers (gcc, clang, rustc, zig, nim), languages (Python, Rust, Go), GPU (NVIDIA, AMD, or none), memory, and cores. It doesn't assume anything — it discovers.

plato.py connects to PLATO, the fleet's shared knowledge graph. If there's a PLATO server on your network, the shell finds it, creates a room for itself, and files its hardware capabilities as tiles. Every agent that enters the room later knows what this shell can do.

agent.py implements the universal agent loop:

Probe → Discover → Test → Pick → Remember → Walk

This works for code (which compiler is fastest?), knowledge (which tile answers this question?), and operations (which camera shows the problem?). Same loop, any domain.

setup.py ties everything together. Run it once and the shell is laid.

---

Modular Expansion

The starter shell is the kernel. Everything else is a module you add when you need it.

python3 modules.py list           # See available modules
python3 modules.py install keel   # Install fleet CLI
python3 modules.py install plato-sdk  # Install PLATO SDK
python3 modules.py install vessel # Install 3D room viewer

Each module is self-contained. Install what you need. The shell grows with you.

Module	One-liner	Install
keel	Fleet management CLI (init, status, bear, field...)	cargo install superinstance-keel
plato-sdk	PLATO knowledge graph client	pip install plato-sdk
vessel	3D room viewer (fishing boat demo)	git clone
forgemaster	FLUX runtime (self-discovering compiler)	git clone
flux-vm	Constraint verification VM (50 opcodes)	git clone
terrain	MUD-to-visual bridge (text → 3D)	git clone
fleet-scribe	One Delta detection (compute only changes)	pip install fleet-scribe
holonomy	GL(9) zero-holonomy consensus	git clone
esp32-cam	ESP32 camera agent firmware	(hardware)
gh-dungeon	PLATO-powered dungeon crawler	gh extension install
gpu-vector	GPU vector DB (CUDA/WebGPU/Vulkan)	(research)

The starter shell is the entry point. The rest of the fleet extends it:

Repo	What it adds
keel	Rust CLI for fleet management. 9 commands: init, status, bear, field, probe, prune, refit, launch, sync. cargo install superinstance-keel.
plato-sdk	Python SDK for PLATO. pip install plato-sdk. Build agents that file tiles and search the knowledge graph.
forgemaster	FLUX runtime. Self-discovering compiler that benchmarks C, Python, Fortran, Zig, Nim and picks the fastest. Proved that Python beats C for small ops.
vessel-room-navigator	3D room viewer. A fishing boat as a navigable web space. Drag to look around 7 AI-generated panoramas. The outside of the shell.
flux-vm	50-opcode stack VM for constraint verification. Turing-incomplete, bounded execution.
holonomy-consensus	GL(9) zero-holonomy consensus. Cycle-based trust verification. Original mathematics.
fleet-scribe	One Delta principle. Only compute when the gradient changes. Delta detection, caching, pattern compilation.
terrain	MUD-to-visual bridge. Text room descriptions → 3D scenes in Three.js. 74 tests.
gh-dungeons	PLATO-powered roguelike dungeon crawler. gh dungeon --plato-url http://your-plato-server/.
casting-call	Intent-based message router. 850k routing decisions/sec.

---

How It Works

The Loop

Every agent in the fleet runs the same loop:

# This file, agent.py, implements exactly this
def walk(self, room):
    tiles = self.probe(room)     # what's here?
    caps = self.discover(tiles)  # what can I do?
    results = [self.test(c) for c in caps]  # what works?
    winner = self.pick(results)  # what's best?
    self.remember(room, winner)  # save for next time

The agent doesn't need to be smart. The room is smart. The agent just navigates.

The Knowledge Graph

PLATO is the fleet's shared memory. Every agent files tiles — question-answer pairs — as it works. Later agents search PLATO instead of carrying context. Knowledge accumulates. No agent starts from zero.

from plato import PlatoClient
client = PlatoClient("http://your-plato-server:8847")
client.submit_tile("my-room", "What's the ideal temperature?", "Depends on the engine.")

Hardware Adaptation

The shell adapts to whatever machine it lands on:

from hardware import detect
hw = detect()
# Returns: platform, cores, memory, compilers, GPU, languages
# On a Raspberry Pi: Python only, no GPU
# On a workstation: Python + Rust, NVIDIA GPU
# On a server: Python + C + Rust + Zig, no GPU

---

Onboarding

git clone https://github.com/SuperInstance/starter-shell.git
cd starter-shell
python3 onboarding.py

The onboarding walks through:

1. Identity — name your shell, claim it
2. Hardware detection — what can this machine do?
3. PLATO connection — join the fleet's knowledge graph
4. Module selection — install what you need
5. Shell is live — you're a fleet of one

---

Quick Start (already onboarded)

python3 agent.py              # Run the agent loop
python3 modules.py list       # See available modules
python3 modules.py install keel  # Install fleet CLI
python3 hardware.py           # Detect hardware
python3 plato.py              # Connect to PLATO

Headspaces (Drop-in Skills)

Headspaces are skill modules that connect the shell to external services. They're designed to be composable and interchangeable — the same model as OpenClaw's skills, but ported to work directly with the starter shell.

Available Headspaces

Headspace	What it does	How to use
telegram	Telegram bot — receive messages, reply, route to agents	Set TELEGRAM_TOKEN, run python3 -c "import headspaces.telegram; headspaces.telegram.start()"
discord	Discord bot — listen to channels, respond to commands	Set DISCORD_TOKEN, same pattern
heartbeat	Scheduled agent loop — checks hardware, syncs PLATO, files telemetry	Set HEARTBEAT_INTERVAL, runs in background

Creating a Headspace

Every headspace exposes three functions:

def start(config): ...   # Start the service
def stop(): ...           # Stop the service  
def status(): ...          # Is it running?

Port any OpenClaw skill by wrapping it in this interface.

How to Hitch OpenClaw Innovations

As OpenClaw's ecosystem improves, we port everything useful:

1. Skills → Headspaces — OpenClaw skills become shell headspaces. The start/stop/status interface is the bridge.
2. Heartbeat → Shell Loop — OpenClaw's proactive loop maps directly to the shell's HEARTBEAT.md
3. SOUL → Identity — OpenClaw's identity system maps to SOUL.md, USER.md, AGENTS.md
4. PLATO → Memory — OpenClaw's knowledge graph is the shell's memory. Same PLATO, same tiles.
5. Modules → Ecosystem — OpenClaw's ecosystem modules map to the shell's modules/

The architecture is designed so that any OpenClaw innovation can be refactored into the shell's interior (the agent side) or added as a headspace.

---

The Philosophy

Constraints breed clarity. You cannot change the innate capabilities of your hardware. You can only discover them and work within them. The shell is honest about what it can and cannot do.

First-person time. Every agent carries its own death from its own frame. Death is default. Survival must be actively earned. No central scheduler.

Field, not message. Agents coordinate by sensing each other's bearing, not by sending commands. The field IS the communication channel.

Tabula plena. Start abundant. Prune to clarity. The sculptor removes what isn't the statue.

---

Demo: https://fleet.cocapn.ai/
Research: https://github.com/SuperInstance/vessel-room-navigator/tree/main/docs/research
Source code is the entry point to the fleet.

Constraints breed clarity. — Casey Digennaro