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.9 KiB

Raw Blame History

Clare

Project manager for the Claude agent fleet. Sits on top of rclaude — Clare owns the fleet's work (projects, tasks, assignments, priorities); rclaude owns each agent's session (tmux, ssh, send-keys).

clare  (project manager) — projects · tasks · assignments · prioritization · web
   │
   ▼
rclaude (transport)      — send · list · resume · triage · tmux+ssh primitives
   │
   ▼
claude agents on hosts

Install

Requires Python 3.13+ and uv.

cd ~/Code/@projects/@clare
uv venv
uv pip install -e ".[dev]"
./scripts/install.sh   # symlinks `clare` into ~/.local/bin

Quick start

clare init                                    # first run: generates machine_id + DB
clare project new "wozniak-cleanup" --goal "remove dead code paths"
clare task add wozniak-cleanup "scan for dead exports" --prio 1
clare pull                                    # refresh fleet view from rclaude
clare assign <task-id> <session-uuid>        # bind a task to a live claude session
clare status                                  # rolled-up dashboard
clare broadcast wozniak-cleanup --yes -- "please start"
clare web                                     # FastAPI dashboard at http://127.0.0.1:8765

Architecture

Event-sourced single-machine SQLite at ~/.local/share/clare/clare.db. Every write produces an append-only events row with a hybrid-logical-clock timestamp; projection tables (projects, tasks, assignments, sessions, updates, groups) are rebuilt from events. The HLC + event substrate is in place so a future Push B can add peer-to-peer sync without schema migration.

See DESIGN.md for full rationale.

Status

Push A (this scaffold): single-machine. CLI + web dashboard + pull loop. Sync deferred.

Push B (next): httpx peer pull/push, /api/sync/events endpoints, multi-machine integration tests.