Skip to content

Holophyte

A minimal, Linear-driven software factory. A ticket goes in as a frozen contract; a merged commit on main comes out, or a preserved branch and a ledger entry saying exactly why not. Stdlib Python and SQLite, no frameworks, and every step is a row in a store that the rest of the system is rendered from.

This site is the manual. It is organised by the question you are asking:

  • How does it all link together?

    One page, one diagram, every component and what it talks to.

    Architecture overview

  • What happens to one ticket?

    From a markdown file on the operator's machine to a --no-ff merge, step by step, naming the module, the table and the process at each step.

    Lifecycle of a ticket

  • Something is stuck. What do I do?

    The escalation ladder, the operator commands, and the recovery recipes written the day each incident happened.

    Runbook

  • How do I write a ticket the loop will take?

    The template, the validator, what the reviewer can and cannot witness, and the contract defects that cost runs.

    Tickets as contracts

The thesis in one paragraph

Holophyte turns a Linear ticket into a merged commit without a human in the loop. One process claims the next ready ticket, cuts a git worktree, hands the whole ticket body to an implementer agent, runs the ticket's own verify commands, sends the diff and the ticket to an independent reviewer inside a hardened container, gives the implementer at most two fix rounds, asks a terminal adjudicator for a PASS or FAIL, and merges with --no-ff. A separate supervisor sweeps the store for runs that died and frees their leases. A daemon serves the store's state as JSON; it reads by default and writes only through two opt-ins, [serve] actions and config_edit (The daemon's actions). A menu-bar drawer answers "what should I look at next?" from it. The same daemon serves the console at /: a browser view of the floor, the ledger and each run's detail, built from console/ with Bun. All of it runs on one machine; a second machine is optional. The factory dogfoods itself: it is the project most of its own tickets run against, and it re-executes itself after merging its own code.

Where things are

Surface Lives in Read more
The loop, supervisor, daemon, operator commands holophyte/ package, factory.py entry point Processes
Durable state one SQLite file per project under ~/.holophyte/<slug>/ Store and state
The board a Linear project, one-way mirror of the store Tickets as contracts
The review boundary a read-only Docker container running Codex Reviewing
Machines one, by default; a second for the drawer or the operator is a page of its own Across machines
Evidence the store's runs/reviewRounds, read through the console or --report; a project may opt into a rendered FINDINGS.md Store and state

Install and run

Python 3.11+ and Git on the host, Docker for the reviewer container, LINEAR_API_KEY in the environment or a .env beside linear_provider.py, and ruff as the one developer tool. Per-project settings go in ~/.holophyte/<slug>/config.toml.

python3 factory.py /path/to/repo                  # run the loop
python3 factory.py --supervise /path/to/repo      # keep it honest
python3 factory.py --serve 7710 /path/to/repo         # JSON daemon on loopback; writes only with [serve] actions or config_edit

The full mode list is in the CLI reference; every config.toml table is in Config.