Configuration Reference

Configuration Hierarchy

Bobbin uses a layered configuration system. Each layer overrides the one above:

How merging works

When both global and per-repo configs exist, they are deep-merged:

• Tables merge recursively — a per-repo [search] section only needs to set the fields it wants to override. Unset fields inherit from global config.
• Arrays replace wholesale — a per-repo index.include replaces the entire global include list.
• Scalars replace — a per-repo search.semantic_weight = 0.5 overrides the global value.

Example

Global config (~/.config/bobbin/config.toml):

[server]
url = "http://search.svc"

[hooks]
gate_threshold = 0.50
budget = 300
skip_prefixes = ["git ", "bd ", "gt "]

Per-repo config (.bobbin/config.toml):

[search]
semantic_weight = 0.8

[hooks]
budget = 500  # Override just this field; gate_threshold inherits 0.50

Result: server.url = http://search.svc, hooks.gate_threshold = 0.50, hooks.budget = 500, search.semantic_weight = 0.8.

Calibration overlay

bobbin calibrate --apply writes optimal search parameters to .bobbin/calibration.json. These override config.toml values for: semantic_weight, doc_demotion, rrf_k, and optionally recency_half_life_days, recency_weight, coupling_depth, budget_lines, search_limit, bridge_mode, bridge_boost_factor.

The search, context, and hook commands all load calibration.json and prefer its values over config.toml. CLI flags still override everything.

Tags and reactions

Two additional config files have their own global/local merge behavior:

• tags.toml — tag pattern rules. Loaded from .bobbin/tags.toml or ~/.config/bobbin/tags.toml (server loads at startup; requires restart to pick up changes).
• reactions.toml — hook reaction rules. Merged: global ~/.config/bobbin/reactions.toml + local .bobbin/reactions.toml. Local rules override global rules by name.

Full Default Configuration

[index]
# Glob patterns for files to include
include = [
    "**/*.rs",
    "**/*.ts",
    "**/*.tsx",
    "**/*.js",
    "**/*.jsx",
    "**/*.py",
    "**/*.go",
    "**/*.md",
]

# Glob patterns for files to exclude (in addition to .gitignore)
exclude = [
    "**/node_modules/**",
    "**/target/**",
    "**/dist/**",
    "**/.git/**",
    "**/build/**",
    "**/__pycache__/**",
]

# Whether to respect .gitignore files
use_gitignore = true

[embedding]
# Embedding model (downloaded automatically on first run)
model = "all-MiniLM-L6-v2"

# Batch size for embedding generation
batch_size = 32

[embedding.context]
# Number of context lines to include before and after a chunk
# when generating its embedding. More context improves retrieval
# quality at the cost of slightly longer indexing time.
context_lines = 5

# Languages where contextual embedding is enabled.
# Contextual embedding enriches each chunk with surrounding
# lines before computing its vector, improving search relevance.
enabled_languages = ["markdown"]

[search]
# Default number of search results
default_limit = 10

# Weight for semantic vs keyword search in hybrid mode.
# 0.0 = keyword only, 1.0 = semantic only, default 0.7.
semantic_weight = 0.7

[git]
# Enable temporal coupling analysis (tracks which files
# frequently change together in git history)
coupling_enabled = true

# Number of commits to analyze for coupling relationships
coupling_depth = 5000

# Minimum number of co-changes required to establish a coupling link
coupling_threshold = 3

# Enable semantic commit indexing (embed commit messages for search)
commits_enabled = true

# How many commits back to index for semantic search (0 = all)
commits_depth = 0

Documentation-Heavy Projects

For projects that are primarily markdown documentation (doc sites, wikis, knowledge bases), consider these tuned settings:

[index]
include = [
    "**/*.md",
]

exclude = [
    "**/node_modules/**",
    "**/build/**",
    "**/dist/**",
    "**/.git/**",
    "**/site/**",            # MkDocs build output
    "**/book/**",            # mdBook build output
    "**/_build/**",          # Sphinx build output
]

[embedding.context]
context_lines = 5
enabled_languages = ["markdown"]

[search]
semantic_weight = 0.8        # Favor semantic search for natural-language queries

Key differences from the defaults:

• Include restricted to **/*.md to skip non-documentation files
• Exclude adds common doc-tool build output directories
• Semantic weight raised to 0.8 since documentation queries tend to be natural language

For projects that mix code and documentation, keep the default include patterns and add the documentation-specific exclude patterns.

See Indexing Documentation for a full walkthrough.

Sections

[git] Settings