Omniscio

ContextDock Integration (link bundles and lists to project knowledge) (part 3)

Part 3 of the ContextDock integration page: where a linked snapshot is written on disk, the sentinel header that marks it as Omniscio-managed, how the picker cache is kept warm, how a snapshot reaches a session's first message, and the full agent-facing IPC surface.

On this page

What it is

This is part 3 of the ContextDock Integration (link bundles and lists to project knowledge) page. It covers the machinery underneath the integration: where a linked bundle, list or doc is written, what the sentinel header at the top of that file carries, how the picker cache stays warm without a visible delay, how a snapshot reaches a session, and the full set of IPC channels an agent can drive.

Where to find it

Nothing in this part has a screen of its own. Everything here happens behind the surfaces described on the parent page: the picker in the Add Project Doc dialog is what the cache warms, and a project's docs section is where the written files show up as rows. The one place you can see part of it is the footer of the ContextDock card in Settings, which names the bundled CLI version.

How it behaves

Cache and startup preload

The picker reads from a SQLite cache so opening the Add Project Doc → ContextDock tab renders instantly, no waiting on a CLI subprocess. The cache is populated by a startup preload that fires once, 5 seconds after the main window opens (past first paint and most critical-path hydration), and kept lightly topped-up by an hourly background refresh task (top-level rosters only) — a low-frequency backstop, since the renderer's on-open stale-while-revalidate is what actually keeps the picker fresh. Both write into three v162 SQLite tables (contextdock_bundles_cache, contextdock_lists_cache, contextdock_list_detail_cache). The docs (library roster) leg was designed to use a delta-sync watermark via the CLI's --since flag once warm, so steady-state refresh would cost a tiny round-trip rather than a full re-fetch. In practice the deployed ContextDock server currently ignores ?since= and returns the full docs roster (the delta-envelope endpoint was never shipped server-side), so the docs leg applies that full roster every tick — Omniscio detects the shape and handles it cleanly, and will automatically switch back to true incremental sync if/when the server starts returning a { changed, deleted, serverTime } delta. Either way the docs cache stays current; the preload leg also re-fetches the docs roster every tick.

User-visible behaviour:

  • Picker open with warm cache → instant render from cache, no network call. The Updated Xm ago caption tells you how stale the snapshot is.
  • Picker open with cold cache → instant render from whatever's in cache (possibly empty), then a silent background refresh kicks in. If the cache was empty the picker briefly shows a loading state until the foreground refresh completes.
  • Steady state → with Settings → ContextDock → Background refresh on (the default), Omniscio quietly tops the cache up hourly in the background. You should rarely see "stale cache" because the renderer revalidates on every picker open (stale-while-revalidate) — that on-open refresh, not the hourly backstop, is what keeps the picker fresh.
  • Manual refresh → the 🔄 button next to the caption forces a foreground refresh at any time. Success toast on done; "Refresh failed — check connection and try again" toast on failure. The button disables and shows a spinning icon while in flight.
  • No API key configured → both the startup preload and the periodic refresh are no-ops (skipped silently). Connecting a key later seeds the cache on the next picker open (foreground refresh) or the next hourly tick.

Background refresh task (the hourly backstop):

  • Cadence. First tick fires 60 seconds after app start (after the one-shot preload has had a chance to land), then every hour thereafter.
  • Two legs per tick. First docs (the library roster — a ?since= "delta" call that the current server answers with the full roster, so Omniscio applies it as a full-roster refresh; a real { changed, deleted, serverTime } envelope would be applied incrementally instead). Then bundles, lists, and tags rosters via runContextDockTopLevelPreload(). Per-list-detail is not refreshed on the tick — that pass (the expensive one-CLI-spawn-per-list leg) runs only on the manual 🔄 button and the picker's on-open refresh, which use the full runContextDockPreload(). Each leg is independent — a failure in docs doesn't skip the preload, and vice versa.
  • User-controlled. Toggle off at Settings → Tools & Plugins → ContextDock → Background refresh. The setting is checked on every tick, so flipping it mid-session takes effect immediately (no restart, no waiting for the next interval boundary).
  • Push events. Omniscio emits a CONTEXTDOCK_LIBRARY_CHANGED push so any open Library / Picker view re-reads and re-renders. The docs leg emits a scoped { resource: 'docs' } push only when it applies a genuine incremental delta (so a full-roster refresh every tick doesn't trigger a needless Library refetch); the preload leg emits a generic push (no resource) after its full bundles/lists/tags refresh. Both shapes are valid — the push payload's resource field is optional.
  • Telemetry. Each tick records one feature_events row — bg_refresh_ok on success (with durationMs, docsChanged, bundleCount, etc.) or bg_refresh_failed on a runtime error. Programmer errors (ReferenceError, TypeError) surface loud rather than being swallowed.
  • Env-var kill switch. Set AMC_DISABLE_CONTEXTDOCK_BG_REFRESH=1 before launching Omniscio to disable the task entirely for that process. Cached on first read — restart Omniscio to flip it.

Behaviour guarantees:

  • Best-effort. Any CLI / network failure during preload is logged but never thrown — a cold cache is fine, the picker falls back to a foreground refresh on open. The same applies to per-list-detail fetches: one stale list id doesn't poison the whole pass. The hourly background timer follows the same contract — one failed tick is logged + telemetry-recorded but does not cancel the next tick.
  • Atomic. Bundles and lists are each wiped + re-inserted inside a single SQLite transaction, so a partial fetch can never half-update the cache (a bundle deleted upstream really disappears; a re-ordered list really re-orders).
  • Per-list-detail is independent. List-detail rows are upserted one-at-a-time keyed by list_id. A pruneContextDockListDetailCache() pass after the lists upsert drops any list-detail rows whose list_id is no longer in the lists cache, so the detail cache doesn't grow unbounded across refresh cycles.
  • Concurrency bounded. Per-list-detail fetches inside a preload run run at most 4 in flight. A user with 50 lists doesn't spawn 50 simultaneous CLI subprocesses (each is a fresh Node process, expensive to start).
  • Top-level warm is time-boxed. The four top-level fetches (bundles + lists + tags + docs) race a 30-second wall-clock ceiling (TOP_LEVEL_PRELOAD_DEADLINE_MS). Normally they finish in ~1–2s, but if they overrun — e.g. the CLI subprocesses are CPU-starved by a startup squeeze (a 20-session crash-recovery storm sharing Omniscio's capped Job Object once stretched this to ~186s) — the preload aborts the in-flight children (freeing CPU for the storm) and returns { timedOut: true } with the cache left as-is; the hourly background refresh retries once the machine is idle. The per-process spawn timeout (30s) is deliberately NOT relied on for this — its kill timer is itself starved under CPU contention — so the ceiling is enforced by the preload's own deadline plus an AbortController threaded through the client onto spawn({ signal }).
  • List drill-in is cache-first too. Opening Browse on a list reads contextdock_list_detail_cache first and renders instantly when warm; misses fall back to a live contextdock:list-detail fetch.

First-message injection

ContextDock files are picked up by Omniscio's first-message injection. When you spawn a new session, Omniscio scans <project>/.claude/docs/, classifies text files (no per-file cap; 500 KB total / ~125K tokens across all files), and inlines the contents into the first user message via buildProjectDocsContext(). ContextDock files are regular .md files in this directory, so they go through this same flow with no special-casing.

Injection is first-message-only and Omniscio-native — there is no shell hook, no <system-reminder>, and nothing written to CLAUDE.md. The global sync-claude-docs.sh hook was removed 2026-05-28; injection now happens once, in Omniscio's TypeScript, with no per-turn overhead. See project-docs-auto-injection.md for the full injection flow.

The parent page covers turning the integration on and using it day to day, and part 2 covers its limits and its error codes. The shared injection flow this page refers to is described on the project docs auto-injection page, and the in-development local-first ContextDock library is on the ContextDock (Local) page.

Last verified 2026-09-23