Natalie c1e6f7dbe5 feat: initial Clare scaffold — project manager for the Claude agent fleet

Push A (single-machine):
- HLC + event-sourced SQLite (events table is source of truth, projections rebuildable)
- Pydantic v2 domain models (Project, Task, Assignment, Session, Group, Update)
- rclaude subprocess wrapper (local_sessions via _claude-projects --sessions)
- Typer CLI: init, project, task, assign, pull, status, broadcast, serve, sync
- FastAPI + Jinja2 + HTMX dashboard
- 26 unit tests passing

Push B (HTTP API + sync substrate):
- /api/v1/* JSON routes (projects, tasks, assignments, sessions, status, broadcast, sync)
- CLI refactored as thin httpx client over the API — single business-logic codepath
- web/service.py: every business op defined once; HTML routes + API routes both call into it
- sync.py: peer-to-peer sync via /api/v1/sync/events with HLC + uuid-based dedup
- 32 tests passing including two-Clare convergence test

Push C (cross-host deployment):
- apricot install via uv (Python 3.12.12)
- systemd --user unit for clare-serve on apricot
- Cross-host sync demoed plum (10.9.0.3) ↔ apricot (10.9.0.2) over wg
- .local → .lan rename for forge URLs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-18 02:20:23 -07:00

1.7 KiB

Raw Blame History

Clare — infrastructure

Storage

Each developer machine has its own SQLite DB:

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

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

Hosts (Push A)

Clare 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)

clare.toml.peers becomes active — each Clare 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 clare web default (the sync endpoints are routes on the same FastAPI app).

rclaude dependency

Clare 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

Clare 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 CLARE_LOG_LEVEL (default INFO). No log file in Push A — journalctl --user or stdout redirect is the answer if a user wants persistence.

1.7 KiB Raw Blame History