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) if you want the CLI. Any file-aware AI for the substrate itself.

Naming update

Earlier versions of these docs described three product tiers (Scholar, Wizard, LLMAGE). That naming is retired. loci is one plain-text substrate with three run modes: plain markdown, a desktop app, and a CLI. All three shipped together as the 0.6 open beta (v0.6.0-beta). This page covers the terminal-native path.

---

What loci is now

loci is plain-text firmware for a persistent, private cognitive system: the templates and processes that decide how memory, context, and trust work, regardless of which AI runs them. The desktop app and the CLI are two expressions built on top of that substrate. They are not the substrate, and you do not need either to start.

Everything is local-first. No cloud, no accounts, no telemetry, no lock-in.

Three run modes, same substrate underneath:

Run mode	What it is
Plain markdown	The door. Copy the templates/ kit, point any file-aware AI at your palace CLAUDE.md. No build.
Desktop app	The cockpit (Tauri, v0.6.0-beta). A native dashboard plus a tab per instrument your palace generates for itself.
CLI	loci-cli (Rust, v0.6.0-beta). A small read-only binary that prints your palace from the terminal.

---

Start in plain markdown (no build)

The substrate needs no installation at all:

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

1. Copy the templates/ kit into a folder of your own.
2. Open FIRST-SESSION.md in the repo and point any file-aware AI at your palace CLAUDE.md.
3. That is the setup.

The full walkthrough lives in SETUP-GUIDE.md. If an agent is doing the setup for you, hand it AGENT-SETUP.md instead: a short interview that ends with a working palace.

---

Install the CLI

The CLI builds from the same repo:

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 runs an interactive wizard and writes ~/.config/loci/config.toml if you want one.

---

What the CLI does

loci is the read-shaped door into your palace: it walks the palace structure (PALACE.md / CLAUDE.md / rooms / crystals) and prints what it finds. Read-only. No network, no inference, no daemons. Your AI does the thinking; the CLI shows the firmware.

Five commands:

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 wizard; 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

Two palace shapes work, matched by both the CLI and the desktop app:

• rooms inside _palace/: the original loci layout
• rooms at root: palaces ported from older organic structures, where rooms grew at the top level and never moved into _palace/

Either resolves. You do not need to restructure an existing palace to use the tools.

Palace files are plain Markdown: no database, diffable, version-controllable. Your AI reads them directly.

---

What is not shipped yet

Deliberately deferred

The CLI is the safest read-only slice. The following are 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

There is no daemon, no port, and no server process in the shipped CLI. loci init does write a local backend configuration (Ollama endpoint and model) to ~/.config/loci/config.toml: that config exists so a later release can read it, but the CLI itself never calls out to it. What is deferred is backend choice: Ollama is the only backend the wizard writes today, and non-local backends (Anthropic, OpenAI) are not wired up. If a document tells you to run loci serve, it is describing a future release.

---

The desktop cockpit

If you prefer a window over a terminal, the desktop app (v0.6.0-beta) is the second expression on the substrate:

• An Operations tab: the native dashboard.
• One tab per instrument your palace generates for itself: any self-contained HTML page the app discovers in the palace, rendered in place.
• A Tool shelf (gate ledger): palaces that keep a tools ledger in palace-map.json get one card per external tool carrying its quarantine verdict (admitted, admitted-escorted, deferred, held-conditional, rejected). The shelf lists; it never loads.

See desktop/QUICKSTART.md in the repo.

---

Keeping a palace current

loci ships a read-only update protocol (PALACE-UPDATE.md in the repo). Say "update my palace" or "what's new in loci" to your AI: it reads your palace, reads the published methodology version, builds the delta, and offers changes one at a time. Nothing is auto-applied; you cherry-pick.

---

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