Design

Principles

• The event log is the only state. Every run is an append-only, hash-chained log; workers hold nothing they cannot rebuild from it. Dashboards, status lines and recovery are reads of the same log. A feature that needs state expresses it as events.
• Write before acting. Model responses and tool intents are recorded before their effects, so a crash at any point leaves a log that says what did and didn’t happen. Side effects are never retried blindly.
• Harnesses first. Claude Code and Codex, run headless on their subscriptions, are the employees. Shiioo’s own agent loop exists for local models, not as a replacement for the harnesses.
• The owner is on a phone. Every decision an agent cannot make alone becomes a message with two buttons. The rules decide the rest, and every decision is on the record.
• One binary, one machine, no services to run. An embedded store, a loopback API, Tailscale for reach. Remote nodes dial out to the server; they never require the server to reach them.
• A personal workforce, not a managed cloud. One owner, one office. No tenants, organisations or billing.

Topology

Today the office is one process: the server and the only node are the same binary on the same machine, with redb underneath.

What exists

The office runs end to end today: the kernel with leases, fencing and recovery; the redb store with a conformance suite shared with an in-memory backend and a Postgres backend; the worker loop with the Claude Code and Codex drivers and the native loop for Anthropic and OpenAI-compatible providers; the rules with the hook that gates every harness command; the HTTP API with a resumable event stream, approvals, capacity and employees; the mobile dashboard; the Telegram bot; the GitHub issue intake; the launchd service with keep-awake; the simulator. Every section of the design documents is marked (built), (planned) or (deferred, ADR-n).

Planned, and not yet started:

Documents

Everything lives in the repository under docs/. Where a document and the code disagree, the code wins and the document is wrong.

Design documents

Decisions

Each architecture decision record holds one decision: the context, what was chosen, what was given up, and when to revisit. Records are never edited after acceptance except for their status; a changed decision gets a new record that supersedes the old one. The index has the template.

Where to look in the code

A Cargo workspace of ten crates, one binary. Each crate has a README (purpose, API, how to test) and a docs/ directory for maintainers.

Working on it

cargo build --workspace
cargo test                                             # unit, integration and simulation tests; no services needed
cargo clippy --workspace --all-targets --all-features  # must be clean
python3 scripts/check-docs.py                          # every relative link in the docs must resolve

The workspace forbids unsafe and denies unwrap(). Tests never run the real claude or codex; they drive fakes that replay recorded output, and the recordings are real, sanitised output from the real tools. Docs carry status markers, and decisions worth not re-litigating get a record. There is no release process yet: cargo install --path crates/shiioo on the office machine, then shiioo uninstall && shiioo install to pick up a new binary. The rest is in Contributing.

Shiioo is Apache-2.0, at github.com/raskell-io/shiioo. The previous codebase is shiioo-legacy.