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

> Learn how to configure Litho using the litho.toml file with this comprehensive guide. Set up project metadata, LLM providers, caching, and more for efficient project management.

- Repository: [Sopaco/deepwiki-rs](https://github.com/sopaco/deepwiki-rs)
- Tags: how-to-guide
- Published: 2026-02-16

---

**To configure Litho, create a [`litho.toml`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/./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:

```bash
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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/Cargo.toml) or [`package.json`](https://github.com/sopaco/deepwiki-rs/blob/main/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.

```toml
[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).

```toml
[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`.

```toml
[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:

```toml
[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:

```toml
[[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`](https://github.com/sopaco/deepwiki-rs/blob/main/litho.toml) at your repository root:

```toml

# 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`](https://github.com/sopaco/deepwiki-rs/blob/main/./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`](https://github.com/sopaco/deepwiki-rs/blob/main/./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:

```toml
[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.