claude-system

01The two layers

The system is a framework plus the instances it scaffolds. Only the framework lives in this repo. ~/.claude/ is not a separate checkout — install.sh symlinks the load-bearing directories straight back into ~/claude-system/claude/, so editing either path edits the same file and all of it is versioned here.

This map is scoped to Layer 1. Layer 2 appears only as what the framework scaffolds and governs — the instances are documented in their own repos.

02Repo layout

Runtime state — state.db, sessions/, .env, ~/projects/* — is deliberately not tracked. .gitignore is strict on *.db and .env.

03The claude/ tree — the ~/.claude payload

Everything the Claude Code harness loads at ~/.claude/ is one of these six things. They are the framework's primary surface; the coordinator and dashboard exist to serve them.

04Skills — 17 SKILL.md contracts

Skills are the user-facing verbs. Each is a markdown contract loaded into context on invocation. Three groups: the experiment loop, the literature pipeline, and hygiene/ops. subagent spawns a fresh subagent · HCE respects evaluation.md · auto-commit writes & commits without a confirmation gate.

Experiment loop — ideation → execution → iteration

Literature pipeline — discover → fetch → ingest → graph

Hygiene & ops

05Hooks — 6 scripts wired to lifecycle events

Hooks are the framework's enforcement layer — discipline that doesn't rely on the agent remembering. Wired in settings.json.

06Rules & CLAUDE.md — the discipline spec

Two prose layers govern agent behaviour without code.

07Templates — the instance scaffold

The framework's output is a project. templates/project/ is the canonical shape /new-project copies, after which a thin instance CLAUDE.md and .claude/rules/ refine the durable principles.

templates/project/
├── CLAUDE.md          # thin orientation; refines ~/.claude/CLAUDE.md
├── README.md          # public-facing layout guide
├── budget.yaml        # wall-time / token / disk ceilings + model roles + git.auto_push
├── dvc.yaml · params.yaml · Makefile · NOTES.md
├── _meta/             # index.md, log.md, templates/{concept,experiment,paper,post,repo}.md
├── literature/  concepts/  mocs/      # the knowledge graph
├── experiments/                       # YYYY-MM-DD-<slug>/ runs (+ _proposals/)
├── raw/                               # immutable sources — read-only after ingest
├── docs/decisions/                    # lightweight ADRs
└── journal/                           # hook-written daily session files

Two archetypes emerge from the same scaffold: literature-curation projects (large knowledge graph, no splits.yaml; e.g. the agentic-research hub) and ML-experiments projects (HCE on, budget.yaml + DVC + sealed test split; e.g. dotaml-turbo).

08Coordinator — one sqlite DB as source of truth

A single ~/.claude/state.db tracks resources so skills can make admit/defer decisions instead of guessing. The Python package wraps it with writers, readers, a hardware poller, an admission policy, and five CLIs.

CLIs (console scripts in the coordinator venv)

ccusage shells out to the community ccusage CLI to read per-message usage. The weekly window is reset-anchored (Mon 17:00 local) and well-calibrated; the 5h block boundary drifts, so trust the projection/burn-rate over the headline 5h %.

09Dashboard — LAN-only window into state.db

FastAPI + HTMX + server-sent events at http://<host>:8080. Reads state.db and project files; auto-refreshes via SSE. Runs as a systemd user unit. A TTL cache fronts hot filesystem scans.

10Session lifecycle — how the parts talk

A single session weaves skills, hooks, and the coordinator together:

1. SessionStart hook primes context.
2. Before a heavy job, a skill calls /plan → policy.can_start reads hardware + quota from state.db → admit / defer.
3. On admit, the skill optionally declares a job (visible in /headroom and the dashboard queue). /implement spawns the subagent that runs it.
4. Each turn, the Stop hook logs token_events; the PreToolUse cap halts a runaway loop past its ceiling. A systemd timer polls hardware every 30s.
5. The dashboard reflects all of this live over SSE.
6. /wrap (backstopped by the SessionEnd hook) writes Did/Findings/Next to NOTES.md, the journal, and — if the project opts in — commits and pushes.

Division of labour: skills = the agent's verbs · hooks = non-negotiable discipline · coordinator = the shared resource truth · dashboard = the human's read-only window.

11Install & operate

git clone git@github.com:eschmitt88/claude-system.git ~/claude-system
cd ~/claude-system && ./install.sh        # idempotent: symlinks + systemd units + backups

install.sh symlinks claude/{rules,skills,hooks,templates} and claude/{CLAUDE.md,settings.json} into ~/.claude/ (backing up anything it replaces), then installs the systemd user units. Required env vars live in ~/.claude/.env (copied from .env.example; never overwritten).

Because claude/ is symlinked into ~/.claude/, editing either path edits the same file — but always commit from ~/claude-system/ so history stays coherent.

12Conventions that hold everywhere