Skip to content

docs: add persistent data storage section to CLAUDE.md #979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acreeger merged 1 commit into from
Apr 3, 2026
Merged

docs: add persistent data storage section to CLAUDE.md #979

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,23 @@ The orchestrator and child workers have strictly separated responsibilities. Get
- **Strategy Pattern**: Branch naming (Simple vs Claude), dev server (Native vs Docker)
- **Configuration Layering**: Defaults → global (`~/.config/iloom-ai/settings.json`) → project (`.iloom/settings.json`) → local (`.iloom/settings.local.json`) → CLI flags

### Persistent Data Storage

All per-user iloom data lives under `~/.config/iloom-ai/`. Key subdirectories:

- **`looms/`** — Loom metadata JSON files, one per active worktree. Filename is the slugified worktree path (triple underscores replace path separators). Contains issue details, branch name, dependency map, child issues, swarm config, and loom state. Finished looms move to `looms/finished/`.
- **`recaps/`** — Recap JSON files, one per loom. Contains the goal, decisions, insights, risks, assumptions, fixes, and artifacts logged by agents during a loom's lifecycle. Archived recaps move to `recaps/archived/`.
- **`mcp-configs/`** — Per-loom MCP server configuration files used by swarm workers to connect to the orchestrator's MCP server.
- **`cache/`** — Cached issue data fetched from issue trackers.
- **`projects/`** — Project marker files tracking which directories have been configured with `il init`.
- **`settings.json`** — Global user settings (applies to all projects).
- **`migration-state.json`** — Tracks which data migrations have been applied.
- **`telemetry-id` / `telemetry.json`** — Anonymous telemetry state.
- **`update-check.json`** — Version update check cache.
- **`*-first-run`** — First-run markers for features (e.g., `spin-first-run`).

Key code: `MetadataManager` (`src/lib/MetadataManager.ts`) manages loom files, `resolveRecapFilePath()` in `src/utils/mcp.ts` resolves recap paths, `SettingsManager` (`src/lib/SettingsManager.ts`) handles settings.

### Component Documentation

Each major directory has its own CLAUDE.md with detailed component documentation. These load automatically when you access files in that directory:
Expand Down
Loading