How almanaccode/codealmanac works
1. Product boundary
- This is a local-only Python CLI application (codealmanac) for maintaining a markdown wiki inside a repository, with derived runtime state kept under ~/.codealmanac/.
- The committed wiki lives only under almanac/; the rest is generated/searchable state, run history, and local automation metadata.
2. Top-level architecture
- The code is organized into a fairly strict layered split: CLI entrypoints, service layer, workflows, and integrations.
- The CLI parses commands, the service layer owns business rules, workflows orchestrate multi-step operations, and integrations isolate external systems like Git, filesystem, transcript stores, Codex, Claude, and the local scheduler.
3. CLI layer
- src/codealmanac/cli contains parser/dispatch/render modules for command groups such as wiki, topics, search, show, health, validate, ingest, garden, sync, jobs, serve, setup, automation, update, doctor, and config.
- Rendering is separated from dispatch, so terminal output and command logic are not mixed. That matters for architecture diagrams because the CLI is an adapter over services rather than the place where domain rules live.
4. Core domain and shared primitives
- src/codealmanac/core holds cross-cutting primitives like paths, slugs, text handling, error types, and small model definitions.
- This is the “shared kernel” used by multiple services for repository identity, wiki page naming, and filesystem conventions.
5. Wiki subsystem
- src/codealmanac/services/wiki handles page formats, frontmatter, links, topic files, templates, and path normalization.
- It is responsible for turning markdown files plus topics.yaml into a coherent local wiki model, including page identity and backlink/link resolution.
- The wiki is the core read/write artifact that the rest of the system manipulates.
6. Indexing and read models
- src/codealmanac/services/index builds the searchable/readable projection over wiki content, with views for pages, topics, summaries, search, and health.
- The README’s search, show, topics, health, and validate commands are driven from this indexed read model rather than directly from raw files.
- This subsystem also bridges to the per-repository runtime database under ~/.codealmanac/repos/<repo-id>/index.db.
7. Repository and workspace selection
- src/codealmanac/services/repositories manages repository identity, root selection, and local state for registered repos.
- The architecture supports operating on “the current repo” and, for the viewer, browsing among registered repos, but the committed wiki root remains fixed to almanac/.
8. Lifecycle workflows
- src/codealmanac/workflows contains the higher-level orchestration for build, garden, ingest, operations, run queue, and sync.
- These workflows coordinate read/write tasks, validation, mutation safety, commits, and queueing.
- The important boundary is that workflows do the multi-step orchestration while services provide the domain operations they call.
9. Run queue and job execution
- Lifecycle operations like ingest and garden are not executed inline; they create queued runs managed by workflows/run_queue and tracked by services/runs.
- Runs have persistent records, locks, state transitions, event streams, snapshots, and worker execution support.
- jobs is the user-facing view of this subsystem: it exposes run status, logs, attach/cancel behavior, and historical events.
10. Harness/provider integration
- src/codealmanac/services/harnesses and src/codealmanac/integrations/harnesses encapsulate the local AI execution backends.
- The project supports at least Codex app-server and Claude Agent SDK harnesses, each with its own adapter, event model, streaming/result handling, and failure mapping.
- These harnesses are only used for write-capable lifecycle commands, not for read-only wiki queries.
11. Source ingestion and sync
- src/codealmanac/services/sources plus integrations/sources resolve source addresses and fetch material from files, directories, Git, GitHub, web pages, and local transcripts.
- sync scans local Claude/Codex transcript stores, discovers active conversations, and turns them into ordinary ingest runs.
- This is the main inbound data flow into the wiki: external material is normalized into source requests, then folded into markdown pages.
12. Automation and updates
- src/codealmanac/services/automation and integrations/automation manage scheduled local jobs such as sync, garden, and update.
- The scheduler integration shown in the tree is launchd, so the automation model is local OS scheduling rather than a cloud service.
- update has its own service and integration boundary for package/version checks and install actions.
13. Setup, prompts, and local environment
- src/codealmanac/services/setup and integrations/setup generate local agent instructions, install guides, and unmanaged text blocks for supported runners.
- src/codealmanac/prompts and src/codealmanac/manual provide runtime content used to guide AI behavior and document product expectations.
- These are not just docs; they are part of the operational contract for how lifecycle runs should behave.
14. Local viewer and static server
- src/codealmanac/server plus services/viewer provide the read-only local web viewer exposed by codealmanac serve.
- The viewer renders pages, search, topics, backlinks, file references, and job views from local data and static assets.
- It is intentionally separate from the mutation workflows: it reads the index and run data but does not own them.
15. Persistence and boundaries
- Persistent state is split between committed wiki content in almanac/ and runtime databases under ~/.codealmanac/ using SQLite.
- The README and architecture docs emphasize that the tool does not stage, split, or commit changes itself; Git operations are delegated to the selected agent when auto-commit is allowed.
- That separation is a key diagram boundary: repo-owned content, local runtime state, and external agent execution are distinct zones.
16. Quality and evolution
- The repository includes a large tests/ suite and extensive docs/ architecture audits, refactor plans, and design notes.
- Those docs are part of the system’s architecture discipline: they encode the intended boundaries around CLI, services, lifecycle, sources, harnesses, and storage.
Main entry points: dispatch Dispatchers · sources Sources · wiki Wiki · runs Runs
Components 34
CLI
Command parsing, dispatch, and terminal rendering adapters
- App · CLI application bootstrap and wiring
src/codealmanac/app.py - Main CLI · Root command entry and top-level dispatch
src/codealmanac/cli/main.py - Command parsers · Command-group parsing for wiki, topics, search, jobs, serve, setup, sync, and admin commands
src/codealmanac/cli/parser - Dispatchers · Command handlers that call services and workflows
src/codealmanac/cli/dispatch - Renderers · Terminal and JSON output formatting separated from dispatch
src/codealmanac/cli/render
Services
Domain services and shared application logic
- Core kernel · Paths, slugs, text handling, error types, and common models
src/codealmanac/core - Repos · Repository identity, root selection, and local repo state
src/codealmanac/services/repositories - Wiki · Markdown pages, frontmatter, links, topics, templates, and path normalization
src/codealmanac/services/wiki - Index · Searchable read model over wiki pages, topics, summaries, health, and views
src/codealmanac/services/index - Pages · Page-level requests and mutations over wiki content
src/codealmanac/services/pages - Topics · Topic graph, read model, and mutation logic
src/codealmanac/services/topics - Health · Validation and health reporting for wiki and sources
src/codealmanac/services/health - Sources · Source address resolution and source request normalization
src/codealmanac/services/sources - Harnesses · AI execution ports, events, results, and provider selection
src/codealmanac/services/harnesses - Runs · Persistent run ledger, locks, records, transitions, and streaming state
src/codealmanac/services/runs - Viewer · Read-only viewer projections and repository scoping
src/codealmanac/services/viewer
Workflows
Multi-step orchestration for lifecycle operations and run execution
- Build · Refreshes derived wiki index and projections
src/codealmanac/workflows/build - Ingest · Normalizes source material into wiki mutations
src/codealmanac/workflows/ingest - Garden · Maintenance workflow for wiki upkeep and curation
src/codealmanac/workflows/garden - Operations · Mutation orchestration, harness execution, and commit policy
src/codealmanac/workflows/operations - Run queue · Queued run creation, worker execution, and lifecycle coordination
src/codealmanac/workflows/run_queue - Sync · Discovers transcript activity and enqueues ingest runs
src/codealmanac/workflows/sync
Integrations
Adapters for filesystems, AI harnesses, scheduling, git, and external sources
- Git probe · Repository probing and git status integration
src/codealmanac/integrations/repositories/git - Filesystem source · Local file and directory source ingestion
src/codealmanac/integrations/sources/filesystem - Git source · Git-based source ingestion
src/codealmanac/integrations/sources/git - GitHub source · GitHub-based source ingestion
src/codealmanac/integrations/sources/github - Web source · Web page fetching and normalization
src/codealmanac/integrations/sources/web - Transcript source · Claude and Codex transcript discovery and reading
src/codealmanac/integrations/sources/transcripts - Claude SDK · Claude Agent SDK execution backend
src/codealmanac/integrations/harnesses/claude - Codex app server · Codex app-server execution backend
src/codealmanac/integrations/harnesses/codex - Launchd · Local OS scheduler integration for automation jobs
src/codealmanac/integrations/automation/scheduler/launchd.py - Setup adapters · Installer instructions, managed blocks, and uninstall helpers
src/codealmanac/integrations/setup
Runtime
Local databases and server/viewer runtime surfaces
- SQLite state · Per-repository runtime databases under ~/.codealmanac/repos/...
src/codealmanac/database - Server · Local viewer server and API routes for read-only browsing
src/codealmanac/server
Connections 40
- App → Main CLI: starts · Bootstraps the CLI application
- Main CLI → Command parsers: parses · Builds the command surface
- Command parsers → Dispatchers: routes to · Maps parsed commands to handlers
- Dispatchers → Renderers: renders via · Separates output formatting from command logic
- Dispatchers → Repos: selects repo · Resolves repository context for commands
- Dispatchers → Wiki: wiki ops · Invokes wiki read/write operations
- Dispatchers → Index: read model · Drives search, show, topics, health, and validate views
- Dispatchers → Topics: topic ops · Handles topic mutation and inspection commands
- Dispatchers → Health: health checks · Runs repository and wiki diagnostics
- Dispatchers → Sources: source requests · Normalizes inbound source selection and addresses
- Dispatchers → Harnesses: harness config · Chooses execution backend for lifecycle runs
- Dispatchers → Runs: jobs view · Exposes run status, logs, and events
- Dispatchers → Viewer: viewer data · Feeds read-only viewer routes and projections
- Wiki → Core kernel: uses · Shares path, slug, text, and error primitives
- Index → SQLite state: persists index · Stores searchable projections in SQLite runtime state
- Repos → SQLite state: persists repos · Tracks registered repositories and local state
- Runs → SQLite state: persists runs · Stores ledgers, locks, snapshots, and transitions
- Build → Index: refreshes · Build workflow updates read models
- Ingest → Sources: reads sources · Resolves and fetches external material
- Ingest → Wiki: writes wiki · Folds source material into markdown pages
- Garden → Wiki: maintains · Curation and upkeep over wiki content
- Operations → Harnesses: executes · Delegates write-capable work to AI harnesses
- Operations → Wiki: mutates · Applies safe wiki mutations
- Operations → Runs: records run · Creates and updates lifecycle run state
- Run queue → Runs: queues runs · Manages queued execution and worker progression
- Sync → Transcript source: discovers transcripts · Scans local Claude and Codex transcript stores
- Sync → Run queue: enqueues ingest · Turns transcript discoveries into queued runs
- Viewer → Index: reads index · Uses projections for pages, search, topics, and health
- Viewer → Runs: reads runs · Displays job history and logs
- Server → Viewer: serves · HTTP surface over viewer projections
- Git probe → Repos: probes · Determines repository identity and git state
- Filesystem source → Sources: adapts · Filesystem source runtime
- Git source → Sources: adapts · Git source runtime
- GitHub source → Sources: adapts · GitHub source runtime
- Web source → Sources: adapts · Web source runtime
- Transcript source → Sources: adapts · Transcript source runtime
- Claude SDK → Harnesses: implements · Claude SDK backend adapter
- Codex app server → Harnesses: implements · Codex app-server backend adapter
- Launchd → Setup adapters: schedules · Installs and runs local automation jobs
- Setup adapters → Dispatchers: setup flow · Supports onboarding, install guides, and uninstall actions