Context Hub Configuration File Format: Complete YAML Schema and Examples

Context Hub stores user-level settings in a YAML file located at ~/.chub/config.yaml, merging custom values with built-in defaults defined in cli/src/lib/config.js.

Context Hub, an open-source CLI tool maintained by Andrew Ng's team, relies on a structured configuration file to manage registry sources, output preferences, and telemetry settings. Understanding the Context Hub configuration file format is essential for customizing cache behavior, adding private documentation sources, and controlling data collection features.

Configuration File Location and Loading

The configuration loader resides in cli/src/lib/config.js, which attempts to read ~/.chub/config.yaml at startup. When the file is absent, the system automatically creates it during the first-run welcome command, populated with the DEFAULTS constant defined in the same module.

The loader performs a shallow merge between the user-defined YAML map and the built-in defaults, meaning any omitted fields inherit their values from the DEFAULTS object.

YAML Schema Specification

The configuration file consists of a top-level YAML map with the following optional fields:

Core Settings

• output_dir (string): Directory where generated context files are written. Default: .context
• refresh_interval (integer): Cache TTL in seconds for fetched registries. Default: 21600 (6 hours)
• output_format (string): Selects between human (readable) or json (machine-readable) output. Default: human
• source (string): Comma-separated list of source names agents may access (e.g., official,maintainer,community). Default: official,maintainer,community

Telemetry and Feedback Controls

• telemetry (boolean): Enables anonymous usage reporting to the telemetry endpoint. Default: true
• feedback (boolean): Enables the post-search thumbs-up/down prompt. Default: true
• telemetry_url (string): Remote endpoint receiving telemetry data. Default: https://chub.telemetry.run/

Custom Registry Sources

The sources field accepts a list of objects defining external registries. Each entry requires:

• name (string): Unique identifier for the source
• Either url (string): Remote YAML registry URL, OR path (string): Local filesystem directory containing documentation

This structure supports both remote registry fetching and local "bring-your-own-data" (BYOD) workflows documented in docs/byod-guide.md.

Practical Configuration Examples

Minimal Configuration

An empty file or complete absence of config.yaml causes the CLI to rely entirely on internal defaults:

# No configuration file required for basic usage

chub search "python decorators"

Customizing Cache TTL and Output Format

To extend the cache lifetime to 12 hours and force JSON output:

# ~/.chub/config.yaml

refresh_interval: 43200
output_format: json

chub search "docker compose" --json

Adding Local Documentation Sources (BYOD)

Reference local build output by specifying a path instead of a url:

# ~/.chub/config.yaml

sources:
  - name: my-project
    path: /Users/alice/projects/my-docs/build

After updating the configuration, force a cache refresh to index the new source:

chub update
chub search "my-project authentication"

Disabling Telemetry and Feedback

To opt out of anonymous reporting and post-search prompts:

# ~/.chub/config.yaml

telemetry: false
feedback: false

Validation and Schema Authority

The configuration schema is validated by the test suite in cli/tests/lib/config.test.js, which ensures that default values are correctly applied when fields are omitted. Authoritative documentation regarding the YAML structure appears in docs/design.md, while the runtime implementation—including the DEFAULTS constant and merge logic—resides in cli/src/lib/config.js.

Summary

• Context Hub uses YAML format for configuration stored at ~/.chub/config.yaml
• The loader in cli/src/lib/config.js merges user settings with the DEFAULTS constant, applying built-in values for any omitted fields
• Key configurable areas include output directories, cache TTL (refresh_interval), output formatting, and registry sources
• The sources array supports both remote URLs and local filesystem paths for BYOD workflows
• Configuration changes take effect immediately, though registry updates may require chub update to refresh the cache

Frequently Asked Questions

What is the default location for the Context Hub configuration file?

The CLI expects the configuration file at ~/.chub/config.yaml on Unix-like systems. If this file does not exist, the application creates it automatically during the first-run welcome sequence, initialized with default values from the DEFAULTS object in cli/src/lib/config.js.

Can I use Context Hub without creating a configuration file?

Yes. The tool functions without a configuration file by using the built-in DEFAULTS defined in cli/src/lib/config.js. All fields are optional, and the CLI will use fallback values for output_dir, refresh_interval, telemetry, and other settings when no user configuration is present.

How do I add my own documentation to Context Hub searches?

Add a local source entry to the sources list in your configuration file, specifying a name and a local path pointing to your documentation directory. Unlike remote sources that use a url field, local sources reference filesystem locations directly, enabling private documentation indexing as described in docs/byod-guide.md.

What happens if I disable telemetry in the Context Hub configuration?

Setting telemetry: false in ~/.chub/config.yaml prevents the CLI from sending anonymous usage data to the default endpoint at https://chub.telemetry.run/. This change takes effect immediately on the next command execution without requiring a restart or cache refresh.

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