How to Configure Litho Using the litho.toml File: A Complete Guide

To configure Litho, create a litho.toml file in your project root and define sections for project metadata, LLM providers, caching, and optional knowledge sources; the CLI automatically loads this file via Args::to_config in src/cli.rs and merges it with command-line flags.

The sopaco/deepwiki-rs repository (also referred to as Litho) is a Rust-based documentation engine that generates architecture reports from codebases. When you configure Litho using the litho.toml file, you control every aspect of the analysis pipeline—from which directories get scanned to which LLM models generate the documentation.

Where Litho Looks for Configuration

Litho resolves configuration in two stages. First, the CLI checks for ./litho.toml in the current working directory. Second, it calls Args::to_config in src/cli.rs (lines 24-34) to merge TOML values with any command-line overrides passed via --config or other flags.

If you place the file elsewhere, invoke Litho with the explicit path:

litho --config /path/to/custom-litho.toml

The file is parsed into the Config struct defined in src/config.rs (lines 71-136), which serves as the single source of truth for the engine.

Core Configuration Sections

The litho.toml file is divided into three logical domains: project analysis, LLM integration, and cache/knowledge management.

Project and Analysis Settings

Top-level keys in the TOML map directly to fields on the Config struct. These control what code gets analyzed and how the output is structured.

Key	Purpose	Default
project_name	Human-readable name; inferred from Cargo.toml or package.json if omitted	Auto-detected
project_path	Root directory to scan	"."
output_path	Destination for generated markdown	"./litho.docs"
target_language	Documentation locale (en, zh, ja, ko, de, fr, ru, vi)	"en"
max_depth	Directory recursion limit	10
max_file_size	Skip files larger than N bytes	65536
excluded_dirs	Array of directory names to ignore (e.g., ["node_modules", "target"])	Varies
excluded_files	Array of specific filenames to skip	[]
excluded_extensions	Array of extensions to ignore (e.g., [".lock", ".log"])	Varies

Analysis behavior is further tuned with boolean flags:

• analyze_dependencies – Enables the dependency-graph phase.
• identify_components – Activates component detection using core_component_percentage.
• include_tests – Whether test files are ingested.
• include_hidden – Whether hidden files (dotfiles) are processed.

LLM Configuration

The [llm] table maps to the LLMConfig struct in src/config.rs (lines 165-210). This section is required unless you are running in offline mode.

[llm]
provider = "openai"               # openai, moonshot, deepseek, mistral, openrouter, anthropic, gemini, ollama

api_key = "${LITHO_LLM_API_KEY}"  # Environment variable substitution supported

api_base_url = "https://api.openai.com/v1"
model_efficient = "gpt-4o-mini"   # Used for quick tasks

model_powerful = "gpt-4o"         # Used for deep analysis

max_tokens = 4096
temperature = 0.1                 # Lower = more deterministic

retry_attempts = 5
retry_delay_ms = 5000
timeout_seconds = 300
disable_preset_tools = false
max_parallels = 3                 # Concurrent LLM requests

Environment variables: You can inject secrets using the ${VAR_NAME} syntax, which the parser resolves at runtime.

Local Ollama: Set provider = "ollama" and api_base_url = "http://localhost:11434/v1". When provider is ollama, Litho automatically defaults to the local endpoint if the URL is omitted.

Cache and Knowledge Settings

Disk Cache

The [cache] table controls LLM response caching via CacheConfig (src/config.rs, lines 558-595).

[cache]
enabled = true
cache_dir = ".litho/cache"
expire_hours = 8760  # 1 year

Caching prevents redundant API calls when re-analyzing similar codebases.

Knowledge Integration

The [knowledge] table enables ingestion of external documentation (Markdown, PDF, SQL) through KnowledgeConfig.

[knowledge.local_docs]
enabled = true
cache_dir = ".litho/cache/knowledge/local_docs"
watch_for_changes = true

Chunking Strategy

Define how documents are split before embedding:

[knowledge.local_docs.default_chunking]
enabled = true
max_chunk_size = 8000
chunk_overlap = 200
strategy = "semantic"
min_size_for_chunking = 10000

Document Categories

You can route specific document types to targeted research agents:

[[knowledge.local_docs.categories]]
name = "architecture"
description = "High-level system architecture and C4 model documentation"
paths = [
    "docs/architecture/**/*.md",
    "docs/c4/**/*.md",
    "docs/design/**/*.md"
]
target_agents = [
    "SystemContextResearcher",
    "ArchitectureResearcher",
    "DomainModulesDetector"
]

Available categories include architecture, database, deployment, api, adr, workflow, and general. Each category can override chunking settings via a nested [knowledge.local_docs.categories.chunking] table.

Minimal litho.toml Example

For a quick start, copy the following into litho.toml at your repository root:

# Project basics

project_name = "My Project"
project_path = "."
output_path = "./litho.docs"
target_language = "en"

# Analysis scope

analyze_dependencies = true
identify_components = true
max_depth = 8
core_component_percentage = 30.0
max_file_size = 65536

# LLM provider

[llm]
provider = "openai"
api_key = "${LITHO_LLM_API_KEY}"
api_base_url = "https://api.openai.com/v1"
model_efficient = "gpt-4o-mini"
model_powerful = "gpt-4o"
max_tokens = 4096
temperature = 0.1

# Response caching

[cache]
enabled = true
cache_dir = ".litho/cache"
expire_hours = 8760

Run litho from the same directory to generate documentation using these settings.

Summary

• Configuration entry point: Litho automatically loads ./litho.toml via Args::to_config in src/cli.rs, or accepts a custom path via --config.
• Core struct: All values parse into the Config struct defined in src/config.rs (lines 71-136), with nested tables mapping to LLMConfig, CacheConfig, and KnowledgeConfig.
• Environment variables: Use ${VAR_NAME} syntax for sensitive values like API keys.
• Key sections: Project paths and analysis filters (top-level), LLM provider settings ([llm]), disk caching ([cache]), and external document ingestion ([knowledge]).
• Local Ollama: Set provider = "ollama" and api_base_url = "http://localhost:11434/v1" for offline operation.

Frequently Asked Questions

Where does Litho look for the litho.toml file by default?

By default, Litho searches for ./litho.toml in the current working directory. This behavior is hardcoded in the CLI argument parser within src/cli.rs (lines 24-34). If the file exists, Args::to_config loads it automatically; otherwise, Litho falls back to default values. You can override this path at any time using the --config flag followed by a custom file path.

Can I use environment variables in the litho.toml file?

Yes, Litho supports environment variable substitution using the ${VAR_NAME} syntax. This is particularly important for the api_key field in the [llm] section to avoid committing secrets to version control. When the Config struct is parsed from the TOML file in src/config.rs, the loader resolves these placeholders against the current environment. If a variable is undefined, the parser typically leaves the value empty or fails gracefully depending on the field requirements.

How do I configure Litho to use a local Ollama instance?

To run Litho against a local Ollama server, set the provider field to "ollama" in the [llm] section and point api_base_url to your local endpoint. According to the LLMConfig implementation in src/config.rs (lines 165-210), the typical configuration looks like this:

[llm]
provider = "ollama"
api_base_url = "http://localhost:11434/v1"
model_efficient = "llama3.2"
model_powerful = "llama3.1:70b"

When provider is set to ollama, Litho automatically defaults to the local endpoint if the URL is omitted, making offline documentation generation possible without exposing API keys.

What is the purpose of the knowledge section in litho.toml?

The [knowledge] section enables external document ingestion, allowing Litho to reference Markdown, PDF, SQL, and other files when generating architecture reports. Defined by the KnowledgeConfig struct in src/config.rs (lines 558-595), this section supports local_docs with configurable chunking strategies and category-based routing. For example, you can map architecture documents to the ArchitectureResearcher agent while routing API specifications to specific editors. This integration ensures generated documentation incorporates existing design decisions, ADRs, and system context rather than relying solely on code analysis.

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