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: start a chat in the company home. Its root AGENTS.md makes
that main chat the Director and loads the canonical operating contract.
.codex/agents/director.toml also defines a custom subagent; that file alone
does not select the main chat's identity.
Review the company hooks before relying on automatic context (/hooks in
the Codex CLI). Project trust does not approve hooks, and moved or changed
hook definitions require fresh owner review. Approved hooks inject a fresh,
read-only company projection at startup, resume, compaction, and each user
prompt. Without a projection, the Director reports the missing injection and
uses its read-only status fallback.
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 tickThis checkout is product source, not a company home. Keep owner Departments,
Skills, bundles, host configuration, and private state in a separate home.
Repository role markers prevent current runtime commands from creating company
state inside a source or website checkout. Synthetic test fixtures remain here.
Run source commands with PYTHONDONTWRITEBYTECODE=1 python3 -B -m company COMMAND;
choose a separate destination for init, update, and import.
git 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
This repository ships reusable code and generic home/host templates. It does
not contain an installed company, owner Skills, private Departments, company
data, or production pipelines. Test fixture packages are synthetic, excluded
from installation, and never production-ready. Audit the source boundary with
python3 -B tools/check_source_boundary.py. An explicitly authorized ignored
.env may hold publishing credentials; it must never enter Git.
A home may refresh from a source checkout by running that checkout's runtime
with SPIELOS_TEMPLATE_DIR set to company/init_templates, an explicit
update --dir /path/to/home, and --keep-stale when removal is not authorized.
--keep-stale retains obsolete vendored files and bytecode while refreshing
shipped files. It makes no backup. Owner layers and private data remain local.