claire/INFRA.md

Claire — infrastructure

Storage

Each developer machine has its own SQLite DB:

~/.local/share/claire/claire.db     · WAL-mode SQLite, single-writer
~/.config/claire/claire.toml        · machine_id, groups, (future) peer list

machine_id is a uuid4 generated on first claire init and persisted in claire.toml. It's stamped onto every event Claire emits and never changes — even if the user's hostname or username changes, the machine identity is stable.

Hosts (Push A)

Claire runs locally on each developer machine. There is no central state host in Push A. The DB is single-writer per machine; the events table is the substrate for the future Push B sync layer.

Hosts (Push B, planned)

claire.toml.peers becomes active — each Claire instance pulls events from the others. The protocol is:

GET  http://<peer>:8765/api/sync/events?since=<hlc>   → batch of events newer than <hlc>
POST http://<peer>:8765/api/sync/events               → push local events (idempotent)

No central coordinator; every peer is a peer. The default port 8765 matches the claire web default (the sync endpoints are routes on the same FastAPI app).

rclaude dependency

Claire requires rclaude to be on $PATH. Install:

git clone http://forge.black.lan/lilith/session-tools.git ~/Code/@scripts/session-tools
~/Code/@scripts/session-tools/install.sh

Claire verifies rclaude --version succeeds at startup and errors with a clear message if not.

Logging

Structured JSON to stderr via stdlib logging. Level controlled by CLAIRE_LOG_LEVEL (default INFO). No log file in Push A — journalctl --user or stdout redirect is the answer if a user wants persistence.