Codebase Context Snapshots

Codebase context snapshots give BMO a metadata-only view of the workspace: relative paths, file modes, sizes, mtimes, content hashes, and aggregate hashes. BMO does not store raw file contents in these snapshots.

The feature is on by default when [options.codebase_context] or enabled is omitted. Each user turn runs one snapshot walk that is shared across prompt enhancement and system-prompt assembly. The result drives stale-aware prompt gating, a bounded system appendage, Activity-row annotations, and the describe_context tool.

Maturity: Daily-use prompt and observability surface. Use this page to configure behavior; use Prompt Enhancer and TUI runtime signals for adjacent context surfaces.

What problem this solves

Long sessions mix git summaries, repo maps, MCP snippets, and read-file bodies. If the workspace changes underneath that context, the model can act on stale paths or outdated file bodies. Codebase context snapshots detect drift and let BMO warn, suppress risky injections, or fail strict spawn paths without re-reading every file into the prompt.

Configuration

[options.codebase_context]
enabled = true
inject_in_prompt = true
stale_policy = "suppress_risky"
min_refresh_interval_seconds = 30
strict_on_child_spawn = false
rehash_mode = "incremental"

Option	Default	Description
`enabled`	`true`	Run snapshot build/diff during prompt preparation; explicit `false` disables walks
`inject_in_prompt`	`true`	Include the bounded `codebase_context` system appendage when a capture exists; requires `enabled = true`
`stale_policy`	`suppress_risky`	`warn_only` keeps risky injections; `suppress_risky` drops overlapping high-risk bodies on content drift
`min_refresh_interval_seconds`	`30`	Minimum interval between auxiliary walks (`describe_context` refresh, burst contract preview). Prompt prep still walks every user turn
`strict_on_child_spawn`	`false`	When `true`, fail `spawn_agent` if the workspace diff has content drift
`rehash_mode`	`incremental`	`full` rehashes every file; `incremental` reuses prior hashes when metadata is unchanged

Set enabled = false to skip snapshot walks entirely. Set inject_in_prompt = false to keep capture, trace segments, and describe_context parity without the system appendage.

See Configuration for merge precedence and the generated field inventory in docs/config.reference.toml.

How snapshots reach the model

On each user message, BMO:

Walks the workspace root and builds a metadata snapshot (bounded by file count, depth, and max file size).
Diffs against the last persisted snapshot under the data directory.
Records prompt trace segments and Activity annotations with status built, reused, stale, probe_degraded, or failed.
When inject_in_prompt is on, appends a bounded codebase_context system block with counts and stale taxonomy only (no paths).
Applies stale_policy during user-message enhancement: under suppress_risky, content drift suppresses retrieved repo/MCP snippets, read-snapshot bodies, and overlapping repo-map lines. When only some paths drift, remaining repo-map lines are re-read for fresh symbols via repomap.RefreshStalePaths (no cross-file dedup on those lines). Refreshed lines skip the global stale advisory; failed refreshes keep prior text and per-line markers. Probe degradation warns without blanket suppression. Multi-writer signals—foreign workspace claims, recent foreign-session file mutations, stigmergy marker globs, and trail payload paths—can invalidate overlapping injections before enhancement runs.

Mid-run system appendage rebuilds reuse the last in-session capture instead of starting another walk.

Operator surfaces

Context hub (`/context`)

The TUI Context hub and the describe_context tool return the same panoramic JSON: token budget, pruning, memory, compaction reactions, and a codebase_context object (counts and status only). When multi-writer invalidation fired, the object also includes external_writer and external_writer_sources (for example foreign_claim, coord_file_mutated).

By default describe_context reads the latest in-memory capture from prompt preparation. Set refresh_codebase_context: true to run an auxiliary walk subject to min_refresh_interval_seconds.

MCP bmo_get_codebase_context returns the same codebase_context JSON when listed in options.mcp_server.exposed_tools.

See Tools.

Activity row

During prompt preparation, the Activity strip can show compact snapshot messages:

Status	Activity text
`built`	Codebase context snapshot built
`reused`	Codebase context snapshot reused
`stale`	Codebase context snapshot is stale
`probe_degraded`	Codebase context snapshot probe degraded
`failed`	Codebase context snapshot failed

These are coordination signals, not a file listing. See TUI runtime signals.

Child spawn strictness

When strict_on_child_spawn = true, spawning a child agent fails if the workspace snapshot is stale. Default sessions keep spawn advisory-only.

Cost and scope notes

Per-turn cost: Interactive prompt prep performs a full metadata walk on each user turn (one shared capture per turn). This is intentional for freshness.
Auxiliary throttling: On-demand refresh paths honor min_refresh_interval_seconds so tools like describe_context do not hammer the filesystem.
Data-dir exclusion: Snapshots ignore the active data directory when it lives under the workspace root so BMO runtime files do not falsely mark the codebase stale.