Getting Started: The Terminal Path

For: engineers and terminal-native users who want to work with a loci palace from the shell. Setup time: 5 minutes. Requirements: Git. A Rust toolchain (cargo) for the CLI. Any file-aware AI for the substrate itself.

loci is plain-text firmware for a persistent, private cognitive system: the templates and processes that decide how memory, context, and trust work, whichever AI runs them. Local-first: no cloud, no accounts, no telemetry. The CLI (loci-cli, Rust, v0.6.0-beta) is a small read-only door into that substrate: no network, no inference, no daemons. It is not the substrate, and you do not need it to start.

---

Start in plain markdown (no build)

git clone https://github.com/huximaxi/loci

Copy the templates/ kit into a folder of your own, open FIRST-SESSION.md, and point any file-aware AI at your palace CLAUDE.md. That is the setup. If an agent is doing it for you, hand it AGENT-SETUP.md instead: a short interview that ends with a working palace. The beginner path walks through it step by step.

---

Install the CLI

git clone https://github.com/huximaxi/loci
cd loci
cargo install --path loci-cli

A pre-built binary will follow once release tagging stabilises. No config file is required to start; loci init writes ~/.config/loci/config.toml if you want one.

---

What the CLI does

loci walks the palace structure (PALACE.md / CLAUDE.md / rooms / crystals) and prints what it finds. Your AI does the thinking; the CLI shows the firmware.

Command	What it does
loci status	Palace path, layout, room and crystal counts
loci crystals	List every crystal slug across all rooms
loci crystals --room <name>	Restrict the list to one room
loci read <slug>	Print a crystal's contents
loci read <slug> --room <name>	Disambiguate when the same slug lives in two rooms
loci handover	Print the most recent handover by modification time
loci init	Interactive setup; writes ~/.config/loci/config.toml

Example (illustrative room names):

$ loci status
palace : /Users/you/palace
layout : rooms-at-root
rooms  : 2
         dev                      (18 crystals)
         research                 (12 crystals)
total  : 30 crystals

Global flags

Flag	What it does
--palace <path>	Point at a palace explicitly
--json	Machine-readable output for any read command

Palace resolution

Each command resolves the palace in this order:

1. --palace <path> (explicit override)
2. $LOCI_PALACE (environment variable)
3. Walk up from the current directory until a palace marker is found

Exit codes

Code	Meaning
0	Clean
1	I/O or unexpected error
2	Palace or crystal not found
3	Bad input (ambiguous slug, malformed arguments)

---

Supported palace layouts

Both shapes resolve without restructuring: rooms inside _palace/ (the original layout) and rooms at the root (palaces ported from older organic structures). Palace files are plain Markdown: no database, diffable, version-controllable.

---

What is not shipped yet

Deliberately deferred

The CLI is the safest read-only slice. Planned, but not in v0.6.0-beta:

• One-shot inference (loci -z "<prompt>")
• Non-local AI backends (Anthropic, OpenAI)
• Chat TUI (loci chat)
• MCP server (loci serve)
• Sync / reindex (loci sync)
• Full diagnostic feedback flow

loci init writes a local backend configuration (Ollama endpoint and model) for a later release to read; the shipped CLI never calls out to it. If a document tells you to run loci serve, it is describing a future release.

---

Keeping a palace current

PALACE-UPDATE.md in the repo is a read-only update protocol. Say "update my palace" or "what's new in loci" to your AI: it compares your palace with the published methodology version and offers changes one at a time. Nothing is auto-applied.

---

Bundled personas and skills

The 0.6 kit includes filled examples, not just blank templates:

• templates/personas/: four worked personas: Vesper (orchestration, meant to be renamed), Cipher (security) and Praxis (sysadmin) as a paired dyad, and Nyx (design).
• templates/skills/: three skills: quarantine, session-close, and insight-consolidation.

Copy what fits, rename freely, discard the rest.

---

Next steps

• See Architecture for how the pieces fit together
• Explore Rooms for context-scoping patterns and multi-project setups
• The full changelog and methodology version live in PALACE-METHODOLOGY.md and CHANGELOG.md in the repo