Getting started

Quickstart

Microcosm runs locally against a folder. The shortest path is a clone, a clean check, and the first screen.

A coding agent (Claude Code, Codex, Cursor) can run this whole page for you; working with a coding agent is that path.

1. Clone the repository

git clone https://github.com/wcook04/microcosm-substrate
cd microcosm-substrate

2. Run the one-command check

A single command confirms the local slice is runnable on your machine before you install anything:

./bootstrap.sh

It runs against a small built-in example and writes its output into an ignored .microcosm/ folder beside the project. Nothing leaves your machine.

3. Open the first screen

From a source checkout, run the behavior-first card first, then inspect status, boundaries, and the optional map:

PYTHONPATH=src python3 -m microcosm_core tour --card .
PYTHONPATH=src python3 -m microcosm_core status --card .
PYTHONPATH=src python3 -m microcosm_core authority --card
PYTHONPATH=src python3 -m microcosm_core workingness --card
PYTHONPATH=src python3 -m microcosm_core hello .
PYTHONPATH=src python3 -m microcosm_core first-screen --card .
PYTHONPATH=src python3 -m microcosm_core legibility-scorecard

Or, after installing the local command:

microcosm tour --card .
microcosm status --card .
microcosm authority --card
microcosm workingness --card
microcosm hello .
microcosm first-screen --card .
microcosm legibility-scorecard

tour --card writes the local witness; hello prints the non-writing map; status and the boundary cards show what the run recorded and where it stops.