How to Use Context Hub Offline with Local Documentation Sources

Context Hub supports complete offline operation by either configuring local directory paths as sources or pre-downloading full content bundles, enabling air-gapped documentation access without remote CDN calls.

Context Hub is an open-source CLI tool for managing and querying contextual documentation. Whether you are working on air-gapped machines or prefer to keep proprietary documentation local, you can use Context Hub offline by pointing it at local directories or pre-caching remote bundles.

Two Methods for Offline Operation

Method 1: Configure Local Content Folders as Sources

You can point Context Hub directly at a local directory containing your documentation. When a source is configured with a path field instead of a url, the CLI reads registry.json and content files directly from disk.

The configuration handling is implemented in cli/src/lib/config.js, which loads ~/.chub/config.yaml and transforms a path entry into a local source object [source 1†L21-L45]. The cli/src/lib/cache.js module then shortcuts remote fetching when source.path is present, reading files directly from the filesystem [source 2†L24-L33].

Method 2: Pre-Download Full Bundles

For remote sources, you can download a complete offline archive once and use it indefinitely. The chub update --full command fetches a pre-packed bundle.tar.gz for every configured remote source, extracts it to the local cache, and thereafter all search and get operations read from the cached files only.

The --full flag is parsed in cli/src/commands/update.js [source 3†L10-L12][source 3†L24-L31], while the bundle download and extraction logic resides in cli/src/lib/cache.js [source 2†L68-L81][source 2†L94-L106].

Architecture Components Supporting Offline Use

Context Hub's offline capability relies on several key components working together:

• Config (~/.chub/config.yaml): Lists sources. A source with a path field points to a local directory containing a registry.json and content tree, eliminating network requirements.
• fetchDoc (cache.js): Detects source.path and reads files straight from the filesystem; remote fetches only occur when the source has a url.
• ensureRegistry (cache.js): When a local source is present, skips bundled-seed/remote-fetch logic and uses the provided registry directly.
• Full bundle (bundle.tar.gz): A static archive containing the registry and all docs/skills. Downloaded once via chub update --full, it extracts to ~/.chub/sources/<name>/data/, making subsequent operations network-free.
• build command: Located in cli/src/commands/build.js, this converts any folder of DOC/SKILL markdown into a proper registry and content tree (dist/), which can then be referenced as a local source.

Practical Implementation Examples

Setting Up Local Documentation (Bring Your Own Docs)

To use your own documentation without internet access:

# Build a local registry from your markdown tree

chub build ./my-content --output ./my-content/.chub-local

# Add the local source to the config (creates ~/.chub/config.yaml if missing)

cat >> ~/.chub/config.yaml <<'EOF'
sources:
  - name: internal
    path: /full/path/to/my-content/.chub-local
EOF

Now all commands work offline:

chub search "payment api"      # searches your local docs only

chub get internal:mycompany/internal-api --lang py   # fetches the DOC.md locally

Relevant files: docs/byod-guide.md (explains the workflow) [source 4†L1-L76], cli/src/commands/build.js (build logic) [source 5†L90-L118], cli/src/lib/config.js (config parsing) [source 1†L21-L45].

Downloading Public Registry for Offline Use

To use public documentation without a persistent connection:

# First time – download the full bundle for every remote source

chub update --full

# Afterwards you can work offline:

chub search "stripe"          # uses the cached search-index.json

chub get stripe/payments --lang js   # reads the cached DOC.md

Relevant files: cli/src/commands/update.js (parses --full) [source 3†L10-L31], cli/src/lib/cache.js (bundle download & extraction) [source 2†L68-L106].

Verifying Cache Status

To confirm your offline setup is working:

chub cache status

This shows each source, whether a registry is present, bundle status, and file counts. The implementation lives in cli/src/lib/cache.js [source 2†L173-L183].

Key Files and Their Purposes

File	Purpose
docs/byod-guide.md	Guide for bringing your own documentation directory and configuring it as a local source.
docs/design.md	High-level architecture explaining multiple sources, caching, and offline bundle strategy.
cli/src/commands/update.js	Implements chub update --full to download and extract the offline bundle.
cli/src/commands/build.js	Generates a registry.json and content tree from a local folder (the BYOD build step).
cli/src/lib/config.js	Loads ~/.chub/config.yaml, creates the source list, and distinguishes local (path) vs remote (url) sources.
cli/src/lib/cache.js	Core cache logic: fetching remote registries, reading local sources, downloading full bundles, and serving docs from cache.

Summary

• Local sources use the path field in ~/.chub/config.yaml to read directly from disk without network calls.
• Full bundles downloaded via chub update --full enable offline access to remote content by extracting bundle.tar.gz to the local cache.
• The build command converts markdown trees into local registries for proprietary documentation.
• Core offline logic resides in cli/src/lib/cache.js and cli/src/lib/config.js, with entry points in cli/src/commands/update.js and cli/src/commands/build.js.

Frequently Asked Questions

Does Context Hub require an internet connection to index local documentation?

No. When you configure a source with a path pointing to a local directory containing a registry.json, Context Hub reads directly from the filesystem without any network calls. This is implemented in cli/src/lib/cache.js, which detects local paths and shortcuts remote fetching entirely.

Can I use Context Hub offline with documentation from public sources?

Yes. Run chub update --full while connected to download the complete bundle.tar.gz for each remote source. After extraction to ~/.chub/sources/<name>/data/, all subsequent search and get operations read from the cached files locally, requiring no further internet access.

How do I convert my existing markdown documentation into a Context Hub compatible format?

Use the chub build command. Point it at your folder containing DOC or SKILL markdown files, and it will generate a registry.json and content tree in the output directory. You can then add this directory as a local source in ~/.chub/config.yaml to query your documentation offline.

Where does Context Hub store offline content and configuration?

Configuration is stored in ~/.chub/config.yaml. Cached registries and downloaded bundles reside in ~/.chub/sources/<source-name>/, with extracted content typically stored under data/ subdirectories. The cache management logic is handled in cli/src/lib/cache.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}