Configuration

Codumentor is configured through a YAML file, typically named codumentor.yaml. This page covers the options most users need day-to-day. For the full reference (authentication, API server, logging, config inheritance, overrides), see the Full Configuration Reference.

Environment Variable Substitution

All string values in the configuration file support ${VAR_NAME} syntax. This keeps secrets out of your config files:

models:
  agent: "${AGENT_MODEL}"
  agent_base_url: "${BASE_URL}/v1"
  embedding_api_key: "${GOOGLE_API_KEY}"

vector_db:
  path: "${DATA_DIR}/vector_db"

If a variable is not set, the literal ${VAR_NAME} string is kept as-is.

Repositories

The repos list tells Codumentor which codebases to index. Entries can be Git URLs or local paths:

repos:
  - "https://github.com/your-org/project.git"
  - "/home/user/projects/local-repo"

On ingest, remote repos are cloned into the repos_dir directory (default: repos). Local paths are read in place.

File Patterns

Codumentor includes all known file types by default (~180 extensions covering source code, config, templates, markup, and documentation). Files with unknown extensions are included if they pass a binary-detection check. Binary files and files over 1 MB are automatically skipped.

You usually don't need to configure anything. The defaults work for most repositories out of the box.

To exclude additional directories, use exclude_patterns_overrides (this appends to the built-in defaults):

exclude_patterns_overrides:
  - "**/legacy/**"
  - "**/generated/**"

To narrow ingestion to specific file types only, set include_patterns (whitelist mode):

include_patterns:
  - "**/*.py"
  - "**/*.md"

Note: Setting include_patterns or exclude_patterns directly replaces all defaults. Use the _overrides suffix to append without losing them. See the Full Configuration Reference for the complete list of defaults.

Chunking

Controls how documents are split into chunks for the vector database:

chunking:
  size: 1000      # Target characters per chunk (default: 1000)
  overlap: 100    # Overlapping characters between chunks (default: 100)

Larger chunks preserve more context; smaller chunks give more precise search results.

Models

Configure the embedding and agent (chat) models:

models:
  embedding: "text-embedding-004"
  embedding_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
  agent: "gemini-2.0-flash"
  agent_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"

API Keys

API keys can be set in the config or via environment variables. Use api_key as a shared fallback, or set model-specific keys:

models:
  api_key: "${OPENAI_API_KEY}"            # Fallback for all models
  agent_api_key: "${OPENROUTER_API_KEY}"  # Agent-specific
  embedding_api_key: "${GOOGLE_API_KEY}"  # Embedding-specific

Alternatively, set OPENAI_API_KEY as an environment variable and omit the key from the config entirely.

Vector Database

vector_db:
  backend: "chroma"           # Vector database backend (default: "chroma")
  path: "./data/vector_db"    # Storage path (default: "./data/vector_db")

Embedding Cache

Caches embedding results to avoid redundant API calls during re-ingestion:

cache:
  embedding_enabled: true           # Enable caching (default: true)
  embedding_db_path: null           # SQLite path; auto-determined if null
  embedding_max_age_days: 365       # Max cache age in days (default: 365)

Agent

agent:
  max_iterations: 10    # Maximum tool-calling iterations per query (default: 10)

Increase max_iterations if the agent is running out of iterations on complex questions.

Tools

tools:
  shell_always_allow: false      # Skip shell confirmation prompts (default: false)
  shell_timeout: 900              # Seconds before killing a shell command (default: 900)
  shell_output_max_size: 10240   # Max bytes returned by shell tool (default: 10240)

Set shell_always_allow: true if you trust the agent to run shell commands without asking.

Plugins

Enable plugins by listing them under plugins:

plugins:
  - module: "codumentor.plugins.telemetry"
    class: "TelemetryPlugin"

  - module: "codumentor.plugins.web_search"
    class: "WebSearchPlugin"
    args:
      enabled: true

Disable a plugin by removing it from the list or setting enabled: false in its args. See Plugins for the full list of available plugins.

Minimal Example

A complete working configuration:

repos:
  - "https://github.com/your-org/your-repo.git"

models:
  embedding: "text-embedding-004"
  embedding_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
  embedding_api_key: "${GOOGLE_API_KEY}"
  agent: "gemini-2.0-flash"
  agent_base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"

vector_db:
  path: "./data/vector_db"

plugins:
  - module: "codumentor.plugins.telemetry"
    class: "TelemetryPlugin"