Repository Structure

Directory layout — what lives where, with subsystem README pointers

Details

work_buddy/ = Python package. Key top-level modules: agent_session.py (identity), artifacts.py (centralized store), paths.py (path resolution), tools.py (feature toggles), config.py (config.yaml + config.local.yaml overlay), consent.py (SQLite-backed), workflow.py (DAG engine), journal_day.py (timezone-aware logical Journal-day policy).

Key packages: knowledge/ (agent docs: query, index, store, editor, vault adapter), dashboard/ (Flask host + root frontend), settings/ (registry, broker, persistence, migrations), health/ (diagnostics engine, checks, components), collectors/ (16 sources), mcp_server/ (gateway + activity_ledger.py), sessions/ (conversation inspector), notifications/ (surfaces: obsidian, telegram, dashboard), messaging/ (inter-agent), memory/ (Hindsight), telegram/ (bot), threads/ (chat system and the WorkItem base with Thread/Task sibling subtypes), work_item/ (WorkItem-family home: the Task write port, which routes Task mutations to obsidian/tasks/mutations.py), projects/ (registry + Hindsight observations), entities/ (entity registry: SQLite store + migrations -- authored names, tags, aliases, append-only reference index), truth/ (scoped provenance-aware claim ledger and invariant engine -- see architecture/truth), cowork/ (the Co-work folder and document lifecycle: inspection/setup/migration, catalog, create/register/scratch, structured persistence and recovery, materialization/drift/reimport/retirement, sittings, feedback, conversations, and cowork_doc_* capabilities -- see cowork), triage/ (Chrome tab pipeline), llm/ (API wrappers), chrome_native_host/ (extension host), obsidian/ (bridge, vault_writer, tasks, tags, datacore, ktr, day_planner, vault_events, commands), calendar/, journal_backlog/, web/ (shared HTTP/Flask helpers), backups/ (vital-DB hot-backup, manifest, gh-CLI remote push, restore pipeline -- see architecture/backups), storage/ (cross-package storage infrastructure: MigrationRunner schema-version ladder -- see architecture/migrations), control/ (control-graph aggregator), vault_index/ (native chunk-level semantic index over configured Markdown roots: chunker, SQLite chunk+vector store, FTS5, hybrid search -- see architecture/vault-index), index/ (consolidated hybrid-search substrate: one SQLite DB across all partitions, FTS5+dense RRF, writer-gated incremental builds -- see architecture/consolidated-index), indexing/ (index-agnostic status seam over the IR/vault/knowledge/consolidated indexes), cli/ (the wbuddy shell CLI for bootstrap and sidecar lifecycle, plus wbuddy truth with exactly capture, propose, query, confirm, and migrate, see operations/wb-cli).

dashboard-react/ = React dashboard source, UI foundations, widget library, Settings surface, development harnesses, and browser tests. Its production build is served by the Flask dashboard at /app.

knowledge/store/ = agent docs, one Markdown file per unit (directions, system, capability declarations, workflows). contracts/ = live data. sidecar_jobs/ = system scheduled jobs (git-tracked, ship with work-buddy).

/ = all generated data. The default is .data/, which is gitignored and configured via paths.data_root in config.yaml. Major directories are agents/ (per-session consent.db, manifests, logs, ledgers), context/ (bundles), runtime/ (PID, state, tool status, per-service rotated logs), cache/ (LLM, chrome tabs, Claude Code usage DB), chrome/ (ledger), logs/ (debug logs), commit/ (90d TTL), export/, report/, scratch/ (artifact types with TTL lifecycle), user_jobs/ (user-authored scheduled jobs that are not shared across installs), and backups/ (local snapshot tarballs + last_run.json health-check sentinel).

/db/ contains the vital SQLite databases for messages, tasks, projects, threads, entities, settings, and the Truth machine registry at truth_registry.db. Architecture/backups covers these vital databases. The directory also contains the non-vital work_item_events.db WorkItem audit log and the derived, rebuildable vault-index.db semantic chunk and vector store.

Truth state is intentionally scoped differently: each participating folder, project, or purpose root owns a sidecar containing its profile, permanent identity, SQLite ledger, optional blobs, and deterministic recovery export. Co-work folders use .wbuddy/cowork/ with a work-buddy namespace manifest at .wbuddy/manifest.yaml; truth_store_create initializes the same canonical shape. Canonical stores live beside the material they describe rather than under the shared <data_root>. Only the machine inventory lives centrally at <data_root>/db/truth_registry.db. The registry tracks path, identity, profile, title, last-seen time, and reachability for discovery and portable backup coverage. It is not a claim store. See architecture/truth.

.claude/commands/ = slash commands (thin launchers loading from knowledge store).