OpenLoci

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Installation

Requires Python 3.10+. uv recommended.

pip install openloci

Or with uv:

uv add openloci

Generate a Palace

# Base template — no skin
openloci new my-project

# With a skin
openloci new my-investigation --skin xfiles
openloci new my-startup --skin sv

This creates a directory at my-project/ containing The Vestibule/ and The Palace/ with all nine rooms.

Explore Your Palace

# List available skins
openloci skins

# Show room map for a skin
openloci rooms xfiles

# Inspect an existing palace
openloci info ./my-investigation

Development Install

git clone https://github.com/mrenoch/OpenLoci
cd OpenLoci
uv venv && uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# CLI
openloci --help

Render the Journal

Each palace includes a Hugo journal for rendering session notes as a browsable site. To run it locally:

Palace Structure

Mon, 01 Jan 0001 00:00:00 +0000

Every generated palace has two top-level directories:

my-palace/
├── The Vestibule/ ← global config — the threshold before the palace
│ ├── README.md ← entry point; read this first
│ ├── Characters/ ← one file per character/agent
│ ├── Rooms/ ← room descriptions and atmosphere
│ ├── Rules/
│ │ └── master_prompt.md ← DM instructions for LLM sessions
│ └── Journal/ ← Hugo site for rendering session notes
└── The Palace/ ← nine rooms, prefixed by function
 ├── intake_*/
 ├── build_*/
 ├── ops_*/
 ├── collab_*/
 ├── meet_*/
 ├── think_*/
 ├── priv_*/
 ├── pitch_*/
 └── retro_*/

The Nine Rooms

Two parallel prefix systems make the palace self-documenting across any skin:

Skin Authoring Guide

Mon, 01 Jan 0001 00:00:00 +0000

A skin is a directory in templates/skins/ that provides a cultural frame for the Clue chassis. The nine rooms stay fixed; the skin supplies names, characters, atmosphere, and defaults.

Directory Structure

templates/skins/
└── my-skin/
 ├── skin.json ← skin metadata and room map
 ├── cookiecutter.json ← template variables
 └── {{cookiecutter.palace_name}}/
 ├── The Vestibule/
 │ ├── README.md
 │ ├── Characters/
 │ │ ├── ceo_{name}.md
 │ │ ├── cro_{name}.md
 │ │ ├── cto_{name}.md
 │ │ └── ...
 │ └── Rules/
 │ └── master_prompt.md
 └── The Palace/
 ├── intake_{room-name}/
 │ └── README.md
 ├── build_{room-name}/
 │ └── README.md
 └── ... (all nine rooms)

`skin.json`

Defines the skin’s identity, room names, and character roster.

Philosophy

Mon, 01 Jan 0001 00:00:00 +0000

The Shell Game Constraint

A session that leaves no files did not happen.

The Shell Game is a podcast about AI and labor — its first episode landed on Radiolab — built around the premise that you cannot trust an agent that leaves no receipts. An AI that works invisibly and leaves nothing behind is indistinguishable from an AI that did nothing.

OpenLoci is built on this constraint. Every significant session must leave material evidence: a handoff note, a summary, a decision record, a revised document. The palace grows through use, not intention. Traces are not optional — they are the work.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

OpenLoci is GPL-3.0. The spec is open. Contributions are welcome.

What We Need Most

Skins are the primary contribution surface. A skin is a directory in templates/skins/ containing a room map, character files, and a master prompt. If you have a cultural frame you want to run a project through, build it and open a PR.

See the Skin Authoring Guide for the full spec.

Bug reports and feature requests go in GitHub Issues.