The operating system for AI-run companies.
spielos.xyz · one durable Goal loop, Agent-owned Departments, approvals, evidence, and memory — all local, all on disk.
GOAL → OBSERVE → DECIDE → ACT → EVALUATE
Turn business intent into measurable Goals. The Director Agent (in OpenCode or Codex) owns the conversation; SpielOS owns the durable loop behind it: every run, work order, approval, evidence record, and memory item is persisted in a local SQLite database — never lost when a chat session ends.
One line with pipx (requires Python 3.11+):
pipx install spielos && spielos init --dir my-company -yOne line with Homebrew:
brew install shayanspiel/spielos/spielos && spielos init --dir my-company -yOne line with npm (thin launcher; needs the Python package too):
npm i -g spielos && pipx install spielos && spielos init --dir my-company -yOne line with curl:
curl -fsSL https://raw.githubusercontent.com/ShayanSpiel/SpielOS/main/install.sh | shOne line with curl and a Department bundle (local folder or git URL):
curl -fsSL https://raw.githubusercontent.com/ShayanSpiel/SpielOS/main/install.sh | sh -s -- --bundle /path/to/bundle-folder--bundle installs the product, creates the home, and imports the
Department in one step, then prints your next steps. Bundle folders come
from company export (a complete repository with a README that onboards
you through OpenCode, Codex, or Claude Code with a paste-prompt block).
The chosen folder becomes a self-contained SpielOS home: the runtime
spine, Director agent + host adapters for OpenCode, Codex, and Claude Code, and empty
private state. The spielos command itself is a global CLI — your company
data always lives in the folder you chose.
cd my-company
opencode # or: codexIn OpenCode: run /agents, select the Director agent, and talk to
it — it already sees your company state.
In Codex: talk to the Director agent — it already sees your company state.
No manual probing, no status commands to start: the host injects a fresh,
read-only company projection into every model request.
pipx upgrade spielos && spielos update --dir /path/to/your/homeupdate refreshes only the vendored spine and host adapters; your private
.spielos/ state, owner profile, memory, and user Departments are always
preserved. Stale files from older releases are pruned so the home matches a
fresh install exactly.
| Concept | What it is |
|---|---|
| GoalRuntime | The one durable control loop: observe, decide, act, evaluate |
| Goal | A measurable outcome with an owner, metric, and target |
| Department | A declarative, Agent-owned capability package |
| Workflow | Ordered steps with declared evidence and approval keys |
| Agent | Performs claimed work orders through a Host |
| Evidence | Immutable proof attached to Goals and Runs |
| Memory | Three scopes: owner profile, workflow learning, strategy learning |
| Approval | Explicit owner keys — external actions always park first |
Fresh homes start with zero Departments — add clean declarative packages
only when their Goal, Workflow, Agent, Evidence, and approval contracts are
ready. Shareable Departments travel as bundle repositories (company export / company import); see
the bundle walkthrough.
Executor identity is enforced: a WorkOrder executes only for its declared agent (exact string, no aliases), claims are claim-then-complete, and work for an agent that is neither installed, nor the goal owner, nor declared by the owning Department is refused upfront and escalated to the owner instead.
Memory retrieval is topology-aware: a Goal's relevant memory carries the
strategy claims of Goals it is structurally related to (same owner and
metric, parent, child, or supports edge), parked asks append the workflow
or goal-relevant learning they should build on, and every WorkOrder brief
carries that bounded memory list so the next execution differs from the
last — memory is causal, not decorative. Direct-work lessons are
goal-keyed: a lesson learned completing a direct order (workflow_id NULL)
reaches future direct orders of that same Goal. Strategy memory stays
selective —
completing a goal writes no new strategy claims; owners and evidence-backed
host distillation are the only strategy writers, operational lessons are
the only per-completion writes, and stale claims retire with
memory retire without losing their evidence. Approvals acknowledge
their answered asks, and unknown comparison operators raise instead of
silently failing closed.
Useful commands:
spielos status
spielos overview
spielos context
spielos memory summary
spielos memory retire <memory_id>
spielos profile list
spielos notifications list
spielos runner tickgit clone https://github.com/ShayanSpiel/SpielOS.git
cd SpielOS
PYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest company.tests.test_clean_core_acceptance- Architecture — the clean-core contract
- Website · GitHub
- MIT licensed