Configuration Guide¶

This guide covers all configuration options for repo-ctx across its three interfaces: CLI, MCP Server, and REST API.

Table of Contents¶

Quick Start
Configuration Sources
Environment Variables
Configuration File
CLI Configuration
MCP Server Configuration
API Server Configuration
Storage Configuration
GenAI/LLM Configuration
Advanced Configuration

Quick Start¶

Zero Configuration (Local + Public GitHub)¶

repo-ctx works out of the box for: - Local Git repositories - Public GitHub repositories (with rate limits)

# No configuration needed
repo-ctx index ./my-local-project
repo-ctx index facebook/react

Minimal Configuration (Private Repos)¶

# GitHub private repos
export GITHUB_TOKEN="ghp_your_token"

# GitLab access
export GITLAB_URL="https://gitlab.company.com"
export GITLAB_TOKEN="glpat-your_token"

Configuration Sources¶

repo-ctx loads configuration from multiple sources with the following priority (highest first):

CLI arguments - Direct command-line options
Environment variables - GITHUB_TOKEN, GITLAB_URL, etc.
Config file (explicit) - Specified via --config flag
Config file (auto-discovered) - Found in standard locations:
./config.yaml (current directory)
~/.config/repo-ctx/config.yaml
~/.repo-ctx/config.yaml

Environment Variables¶

Git Providers¶

Variable	Description	Default
`GITHUB_TOKEN`	GitHub personal access token	None (public repos only)
`GITHUB_URL`	GitHub API URL	`https://api.github.com`
`GITLAB_TOKEN`	GitLab personal access token	None (required for GitLab)
`GITLAB_URL`	GitLab server URL	None (required for GitLab)

Alternative prefix GIT_CONTEXT_* is also supported: - GIT_CONTEXT_GITHUB_TOKEN - GIT_CONTEXT_GITLAB_URL

Storage¶

Variable	Description	Default
`STORAGE_PATH`	SQLite database path	`~/.repo-ctx/context.db`
`GIT_CONTEXT_STORAGE_PATH`	Alternative name	Same as above

Vector Database (Qdrant)¶

Variable	Description	Default
`QDRANT_URL`	Qdrant server URL	`:memory:` (in-memory)
`QDRANT_API_KEY`	Qdrant Cloud API key	None
`QDRANT_COLLECTION_PREFIX`	Collection name prefix	`repo_ctx`

Graph Database (Neo4j)¶

Variable	Description	Default
`NEO4J_URI`	Neo4j connection URI	`bolt://localhost:7687`
`NEO4J_USERNAME`	Neo4j username	`neo4j`
`NEO4J_PASSWORD`	Neo4j password	None
`NEO4J_DATABASE`	Database name	`neo4j`
`NEO4J_IN_MEMORY`	Use NetworkX backend	`true`

GenAI/LLM¶

Variable	Description	Default
`GENAI_ENABLED`	Enable LLM features	`false`
`GENAI_MODEL`	LLM model name	`gpt-5-mini`
`GENAI_EMBEDDING_MODEL`	Embedding model	`text-embedding-3-small`
`GENAI_API_KEY`	LLM provider API key	None
`GENAI_BASE_URL`	Custom API base URL	None

API Server¶

Variable	Description	Default
`REPO_CTX_API_KEY`	API authentication key	None (no auth)
`REPO_CTX_REQUIRE_AUTH`	Require auth for all requests	`false`

Configuration File¶

YAML Format¶

Create ~/.config/repo-ctx/config.yaml:

# Git Providers
github:
  url: "https://api.github.com"  # Optional
  token: "${GITHUB_TOKEN}"       # Uses env var

gitlab:
  url: "https://gitlab.company.com"
  token: "${GITLAB_TOKEN}"

# Storage
storage:
  path: "~/.repo-ctx/context.db"

  # Vector database (optional)
  qdrant:
    url: ":memory:"              # In-memory, or "http://localhost:6333"
    api_key: "${QDRANT_API_KEY}" # For Qdrant Cloud
    collection_prefix: "repo_ctx"

  # Graph database (optional)
  neo4j:
    uri: "bolt://localhost:7687"
    username: "neo4j"
    password: "${NEO4J_PASSWORD}"
    database: "neo4j"
    in_memory: true              # Use NetworkX instead of Neo4j

# GenAI/LLM (optional)
genai:
  enabled: true
  model: "gpt-5-mini"           # Or "claude-3-haiku-20240307", "ollama/llama3"
  embedding_model: "text-embedding-3-small"
  api_key: "${OPENAI_API_KEY}"
  base_url: null                 # Custom API endpoint

Environment Variable Substitution¶

The config file supports ${VAR_NAME} syntax for environment variables:

gitlab:
  token: "${GITLAB_TOKEN}"  # Replaced with actual value at load time

CLI Configuration¶

Global Options¶

repo-ctx [global-options] <command> [command-options]

Option	Description
`-c, --config PATH`	Config file path
`-p, --provider {auto,github,gitlab,local}`	Override provider detection
`-o, --output {text,json,yaml}`	Output format
`-v, --verbose`	Verbose output
`--version, -V`	Show version

Examples¶

# Use specific config file
repo-ctx -c ~/my-config.yaml index owner/repo

# Force provider
repo-ctx -p github index owner/repo
repo-ctx -p local index ./my-project

# JSON output for scripting
repo-ctx -o json list
repo-ctx -o json search "fastapi" | jq '.results[].name'

# Verbose mode
repo-ctx -v analyze ./src

Interactive Mode¶

repo-ctx -i
# or
repo-ctx --interactive

Launches an interactive command palette with: - Command auto-completion - Fuzzy search for repositories - Rich formatted output

MCP Server Mode¶

repo-ctx -m
# or
repo-ctx --mcp

Starts the MCP server for AI assistant integration.

MCP Server Configuration¶

Starting the Server¶

# Default (uses environment/config file)
repo-ctx --mcp

# With explicit config
repo-ctx --mcp --config ~/my-config.yaml

Claude Desktop Integration¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "repo-ctx": {
      "command": "uvx",
      "args": ["repo-ctx", "--mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token",
        "GITLAB_URL": "https://gitlab.company.com",
        "GITLAB_TOKEN": "glpat-your_token"
      }
    }
  }
}

With Custom Config File¶

{
  "mcpServers": {
    "repo-ctx": {
      "command": "uvx",
      "args": ["repo-ctx", "--mcp", "--config", "/path/to/config.yaml"]
    }
  }
}

Available MCP Tools¶

The MCP server exposes these tool categories:

Category	Tools	Description
Repository	`ctx-index`, `ctx-list`, `ctx-search`, `ctx-docs`	Index, search, retrieve docs
Code Analysis	`ctx-analyze`, `ctx-symbol`, `ctx-symbols`, `ctx-graph`	Symbols, dependencies
Architecture	`ctx-dsm`, `ctx-cycles`, `ctx-layers`, `ctx-architecture`, `ctx-metrics`	Structure analysis
Export	`ctx-llmstxt`, `ctx-dump`	Compact summaries, full export
CPG (Joern)	`ctx-query`, `ctx-export`, `ctx-status`	Advanced code analysis

API Server Configuration¶

Starting the Server¶

# Development server
uvicorn repo_ctx.api:app --reload --port 8000

# Production server
uvicorn repo_ctx.api:app --host 0.0.0.0 --port 8000 --workers 4

Authentication¶

By default, the API allows unauthenticated access from localhost.

Enable API Key Authentication:

# Generate a key
export REPO_CTX_API_KEY=$(openssl rand -hex 32)

# Require auth for all requests (including localhost)
export REPO_CTX_REQUIRE_AUTH=true

Using the API Key:

curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/repositories

Rate Limiting¶

Default rate limits (configurable in code): - 100 requests per 60-second window - Applied per client IP - Disabled for localhost by default

API Endpoints¶

Endpoint	Description
`GET /health`	Health check
`GET /api/v1/info`	Server info and capabilities
`GET /api/v1/repositories`	List indexed repositories
`POST /api/v1/index`	Index a repository
`GET /api/v1/search`	Search repositories
`GET /api/v1/docs/{group}/{project}`	Get documentation
`POST /api/v1/analyze`	Analyze code

Full OpenAPI documentation available at /docs when server is running.

Storage Configuration¶

SQLite (Content Database)¶

The main content database stores: - Repository metadata - Document content - Symbol information

# Default location
~/.repo-ctx/context.db

# Custom location
export STORAGE_PATH=/path/to/database.db

Qdrant (Vector Database)¶

For semantic search capabilities:

# In-memory (default, data lost on restart)
export QDRANT_URL=":memory:"

# Local Qdrant server
export QDRANT_URL="http://localhost:6333"

# Qdrant Cloud
export QDRANT_URL="https://xyz.qdrant.io:6333"
export QDRANT_API_KEY="your-cloud-api-key"

Neo4j (Graph Database)¶

For advanced dependency analysis:

# In-memory NetworkX backend (default)
export NEO4J_IN_MEMORY=true

# Local Neo4j server
export NEO4J_IN_MEMORY=false
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_PASSWORD="your-password"

GenAI/LLM Configuration¶

repo-ctx uses litellm for multi-provider LLM support.

Enable LLM Features¶

export GENAI_ENABLED=true
export GENAI_API_KEY="your-api-key"

Supported Providers¶

# OpenAI (default)
export GENAI_MODEL="gpt-5-mini"
export GENAI_API_KEY="sk-..."

# Anthropic
export GENAI_MODEL="claude-3-haiku-20240307"
export GENAI_API_KEY="sk-ant-..."

# Azure OpenAI
export GENAI_MODEL="azure/gpt-4"
export AZURE_API_KEY="..."
export AZURE_API_BASE="https://your-resource.openai.azure.com"

# Local Ollama
export GENAI_MODEL="ollama/llama3"
export GENAI_BASE_URL="http://localhost:11434"

# AWS Bedrock
export GENAI_MODEL="bedrock/anthropic.claude-3-sonnet"
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."

LLM Features¶

When enabled, LLM provides: - Code summarization - Documentation enhancement - Symbol classification - Quality suggestions

Without LLM, these features fall back to heuristic-based analysis.

Advanced Configuration¶

Multiple Environments¶

Create environment-specific config files:

# Development
repo-ctx -c config.dev.yaml index owner/repo

# Production
repo-ctx -c config.prod.yaml index owner/repo

Docker Deployment¶

FROM python:3.11-slim

RUN pip install repo-ctx

ENV GITHUB_TOKEN=""
ENV STORAGE_PATH="/data/context.db"

VOLUME /data

CMD ["repo-ctx", "--mcp"]

docker run -e GITHUB_TOKEN=ghp_xxx -v repo-ctx-data:/data repo-ctx

Kubernetes ConfigMap¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: repo-ctx-config
data:
  config.yaml: |
    github:
      token: "${GITHUB_TOKEN}"
    storage:
      path: "/data/context.db"

Logging¶

# Enable debug logging
export LOG_LEVEL=DEBUG

# Or in Python
import logging
logging.getLogger("repo_ctx").setLevel(logging.DEBUG)

Troubleshooting¶

Common Issues¶

"No provider configured"

# Solution: Set at least one provider
export GITHUB_TOKEN="ghp_xxx"
# or
export GITLAB_URL="..." && export GITLAB_TOKEN="..."

"Rate limit exceeded" (GitHub)

# Solution: Use authenticated requests
export GITHUB_TOKEN="ghp_xxx"

"Joern not found"

# Solution: Install Joern and add to PATH
export PATH="$HOME/bin/joern:$PATH"
repo-ctx status  # Verify installation

Verify Configuration¶

# Show current configuration and capabilities
repo-ctx status

# Test specific provider
repo-ctx -p github list
repo-ctx -p gitlab list
repo-ctx -p local index ./

Configuration Guide¶

Table of Contents¶

Quick Start¶

Zero Configuration (Local + Public GitHub)¶

Minimal Configuration (Private Repos)¶

Configuration Sources¶

Environment Variables¶

Git Providers¶

Storage¶

Vector Database (Qdrant)¶

Graph Database (Neo4j)¶

GenAI/LLM¶

API Server¶

Configuration File¶

YAML Format¶

Environment Variable Substitution¶

CLI Configuration¶

Global Options¶

Examples¶

Interactive Mode¶

MCP Server Mode¶

MCP Server Configuration¶

Starting the Server¶

Claude Desktop Integration¶

With Custom Config File¶

Available MCP Tools¶

API Server Configuration¶

Starting the Server¶

Authentication¶

Rate Limiting¶

API Endpoints¶

Storage Configuration¶

SQLite (Content Database)¶

Qdrant (Vector Database)¶

Neo4j (Graph Database)¶

GenAI/LLM Configuration¶

Enable LLM Features¶

Supported Providers¶

LLM Features¶

Advanced Configuration¶

Multiple Environments¶

Docker Deployment¶

Kubernetes ConfigMap¶

Logging¶

Troubleshooting¶

Common Issues¶

Verify Configuration¶

See Also¶