Purpose of the Internal Working Directory in Litho: A Deep Dive into deepwiki-rs

The internal working directory (.litho) serves as Litho's isolated workspace for caching LLM responses, storing knowledge-sync metadata, and housing temporary artefacts during the documentation generation process.

The sopaco/deepwiki-rs repository implements Litho, a Rust-based documentation engine that relies on a hidden .litho directory to manage state and optimize performance. Understanding the purpose of this internal working directory is essential for debugging cache issues, configuring custom project paths, and ensuring efficient incremental builds.

What Is the Litho Internal Working Directory?

The internal working directory is a hidden folder named .litho that Litho creates at the root of each project. According to the source code in src/config.rs, the Config struct explicitly documents this field as the "Internal working directory path (.litho)" and initializes it via the CLI in src/cli.rs at lines 146-147:

config.internal_path = self.project_path.join(".litho");

This directory acts as a private workspace where the engine stores all generated artefacts, ensuring that temporary files never pollute the user's source tree.

Core Functions of the .litho Directory

LLM Response Caching

One primary purpose of the internal working directory is to cache LLM API calls. The CacheConfig::default() implementation in src/config.rs (lines 61-63) sets the default cache location:

cache_dir: PathBuf::from(".litho/cache"),

This cache stores request-response blobs and token-usage statistics, preventing redundant API calls and significantly speeding up repeated documentation generation runs.

Knowledge Base Synchronization

The .litho directory maintains metadata for incremental knowledge syncing. When processing local documentation, the sync_local_docs function in src/integrations/knowledge_sync.rs (lines 60-68) constructs a dedicated subdirectory:

let knowledge_dir = self.config.internal_path.join("knowledge").join("local_docs");

This location stores JSON indexes of documentation files and their chunked segments, enabling fast incremental updates when source files change.

Temporary Artefact Storage

During the documentation pipeline, Litho generates intermediate files such as extracted project structures, component graphs, and preliminary markdown. These temporary artefacts reside within .litho to keep the working tree clean. The various generator modules in src/generator/ read from and write to this internal directory before finalizing output to the litho.docs folder.

Self-Exclusion from Source Scans

To prevent infinite recursion or analysing its own generated files, Litho automatically excludes the .litho directory from source scans. The excluded_dirs configuration in src/config.rs (lines 80-84) explicitly includes:

".litho".to_string()

This ensures that the engine never processes cached LLM responses or temporary artefacts as if they were source code.

Configuring the Internal Working Directory

While .litho is the default, the location is configurable. The CLI accepts a --project-path argument that influences where the internal directory is initialized. As shown in src/cli.rs (lines 146-147), the path is constructed by joining the project path with the .litho suffix:

config.internal_path = self.project_path.join(".litho");

Users can relocate this directory by specifying a different project root, which is particularly useful in CI environments or when following specific organizational directory conventions.

Summary

• The .litho directory is Litho's isolated workspace created at the project root, defined in src/config.rs as Config.internal_path.
• It caches LLM responses under .litho/cache to avoid redundant API calls and reduce costs.
• It stores knowledge-sync metadata in .litho/knowledge/local_docs for fast incremental documentation updates.
• It houses temporary artefacts during the generation pipeline, keeping the source tree clean.
• It is automatically excluded from source scans to prevent the engine from analysing its own files.
• The location is configurable via the CLI --project-path option, initialized in src/cli.rs.

Frequently Asked Questions

Can I safely delete the .litho directory?

Yes. The .litho directory contains only generated caches and temporary files. Deleting it will not affect your source code, though the next run will require regenerating cached LLM responses and rebuilding the knowledge index, which may take longer and incur additional API costs.

How does Litho prevent the .litho folder from being processed as source code?

Litho explicitly adds .litho to the excluded_dirs list in src/config.rs (lines 80-84). This exclusion ensures that the source scanner ignores all files within the internal working directory, preventing infinite recursion and contamination of the analysis with cached data.

Can I change the name of the internal working directory from .litho to something else?

While the default name is hardcoded as .litho in the CacheConfig::default() implementation and CLI initialization, you can effectively relocate the directory by using the --project-path CLI argument to specify a different root directory. The internal folder will still be named .litho, but it will reside under your specified path.

What happens if the .litho directory runs out of disk space?

If the disk fills up, LLM caching will fail when attempting to write new request-response blobs to .litho/cache, and knowledge-sync operations will error when writing metadata to .litho/knowledge. Litho will surface these I/O errors through the standard error handling mechanisms in src/cache/mod.rs and src/integrations/knowledge_sync.rs, typically requiring the user to clear the cache or expand available storage.

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