Local State Layout
Local state layout is the split between committed wiki source and machine-local runtime files. The repository-owned wiki is the almanac/ tree. The local database, user config, per-repository derived indexes, update lock, and scheduler logs live under ~/.codealmanac/ by default [@readme] [@core-paths].
This layout follows the local-only Python product decision: authored Markdown stays reviewable in Git, while runtime state is kept outside the repository and can be rebuilt or removed without editing wiki source [@live-agreement]. The architecture page for this area is Repository local state, and the persistence boundary is SQLite store boundaries.
Default Paths#
| Path | Owner | Purpose |
|---|---|---|
<repo>/almanac/ |
Repository source | Committed wiki pages and topics.yaml. |
<repo>/almanac/topics.yaml |
Repository source | Authored topic definitions. |
~/.codealmanac/ |
Local runtime | Default global state directory. |
~/.codealmanac/codealmanac.db |
Local runtime | Local database for repositories, runs, run events, worker locks, and sync state. |
~/.codealmanac/config.toml |
Local runtime | User config. |
~/.codealmanac/repos/<repo-id>/index.db |
Derived runtime | Per-repository search and graph index. |
~/.codealmanac/update.lock |
Local runtime | Global update lock. |
~/.codealmanac/logs/ |
Local runtime | Scheduler stdout and stderr logs. |
~/.codealmanac/harnesses/ |
Local runtime | Product-owned cache root Yoke uses to compile Claude and Codex provider resources, so provider config is never written into a repository. |
core.paths defines the default state directory as Path.home() / ".codealmanac", the default database as ~/.codealmanac/codealmanac.db, the default config as ~/.codealmanac/config.toml, and scheduler logs as ~/.codealmanac/logs [@core-paths].
App Config Paths#
AppConfig defaults database_path and config_path to the default local-state paths and normalizes both paths through expanduser().resolve(strict=False) [@settings] [@core-paths]. Environment variables use the CODEALMANAC_ prefix because AppConfig is a Pydantic settings model [@settings]. Repository-level config is not supported.
LocalStatePaths.from_config derives state_dir from the database parent. If the database path is customized and config_path was not explicitly set, config moves beside that database as <database-parent>/config.toml [@settings]. Tests cover both the implicit config path and an explicit custom config path [@settings-tests].
The database path must live directly inside the state directory. LocalStatePaths rejects a shape where the database is nested more deeply than state_dir / "codealmanac.db" would imply [@settings].
LocalStatePaths.harness_runtime_dir is state_dir / "harnesses" [@settings]. The composition root passes it to both provider adapters so Yoke's native Claude and Codex compilation caches under CodeAlmanac's own local state instead of the target repository; see Yoke harness boundary for how the adapter uses this path for run caching and readiness checks [@yoke-adapter].
Per-Repository Runtime#
Per-repository runtime files live under state_dir / "repos" / <repo-id> [@settings]. The index schema defines the derived index filename as index.db inside that runtime directory [@index-schema]. The public README documents this as ~/.codealmanac/repos/<repo-id>/index.db [@readme].
The derived index is not authored wiki data. It can be rebuilt from almanac/**/*.md and almanac/topics.yaml, while the committed Markdown remains the durable artifact [@live-agreement].
What Must Not Live In almanac/#
Runtime state does not belong in the committed wiki tree. Health checks flag index.db, index.db-wal, index.db-shm, jobs/, and runs/ inside almanac/ with the message that runtime state belongs under ~/.codealmanac/ [@health-runtime].
This is also the reason Only Almanac Root matters. almanac/ is the only repo wiki root, but it is not an application state directory.