thoth

A CLI tool that generates documents from a mix of static text, verbatim file includes, and LLM-generated content. Write a template, run thoth, get a document that stays in sync with your repo.

Install

Requires Node.js ≥ 22.

Global install

npm install -g thoth
thoth template.md

Project-local (as a dev dependency)

Add thoth to a specific project. Use npx thoth or wire it into package.json scripts:

npm install --save-dev thoth
npx thoth template.md

{
  "scripts": {
    "docs": "thoth --config thoth.config.json AGENTS.md"
  }
}

Source (clone and build)

git clone <repo-url> && cd thoth
npm install
npm run build
./dist/cli.js template.md

Development (npm link)

Symlinks the binary for testing against a local checkout:

npm link  # from the thoth repo
thoth template.md

Quick start

Create a template file (template.md):

# My Project

@include README.md

## Architecture Summary

@llm:arch-summary
  context:
    - docs/architecture.md
  prompt: |
    Summarize the architecture in 2-3 paragraphs.
@end

Run it:

thoth template.md

The output inlines the contents of README.md and replaces the @llm block with the model's response. On the next run, the LLM response is served from cache — no API call, no network.

Usage

thoth [options] [<input.md>|-]

If <input.md> is omitted or given as -, the template is read from stdin (unless stdin is a terminal, which is an error).

Options

| Flag | Description | | -------------------- | ----------------------------------------------------------------------- | | --config <path> | Path to a config file | | --check | Drift detection: render to memory and compare against --output | | --output <path> | Write output to <path> instead of stdout (required with --check) | | --cache-dir <path> | Override the cache directory | | --no-cache | Bypass the cache (always call the LLM) | | --help | Print usage summary and exit | | --version | Print version and exit |

Exit codes

| Code | Meaning | | ---- | ------------------------------ | | 0 | Success | | 1 | Unexpected runtime error | | 2 | Usage error (bad arguments) | | 3 | Drift detected (--check only)|

Examples

thoth template.md                     # render to stdout
thoth template.md --output out.md     # render to file
thoth --check --output out.md         # check if out.md is fresh
thoth --no-cache template.md          # force LLM re-generation
thoth --config prod.json template.md  # use a specific config file

Template syntax

A template is a text file containing static text and directives. Directives are resolved at render time; everything else is passed through unchanged.

Static text

Any text not inside a @directive...@end block is static. Write it as you would any markdown file.

@include — inline a file

@include path/to/file.md

The referenced file's contents replace the directive. Paths are relative to the template file's directory (or the current working directory when reading from stdin).

@llm — LLM-generated content

One-liner:

@llm Summarize the architecture in two paragraphs.

Multi-line with an optional label (used for cache identification):

@llm:architecture-summary
  context:
    - docs/architecture.md
    - docs/concept.md
  prompt: |
    Summarize the architecture in 2-3 paragraphs.
    Mention the core design values.
  model: gpt-4o
@end

| Parameter | Required | Description | | ------------ | -------- | --------------------------------------------- | | prompt | Yes | The prompt sent to the model | | context | No | List of files whose contents are prepended | | model | No | Override the default model for this block | | Label | No | Short identifier (used in cache keys, errors) |

The label follows the directive name, separated by a colon: @llm:my-label.

@static — explicit verbatim block

@static
  Any text here is passed through verbatim.
  Useful for disambiguating text that looks
  like a directive header line.
@end

@static is rarely needed — text outside directives is already static. Use it only when a line of text matches the @directive pattern and you want it treated as literal text.

Configuration

thoth looks for a config file at thoth.config.json in the current directory. You can specify a different path with --config.

{
  "cacheDir": "./.doc-cache",
  "cache": { "enabled": true },
  "llm": {
    "provider": "openai",
    "apiKey": "${OPENAI_API_KEY}",
    "baseUrl": "${OPENAI_BASE_URL}",
    "defaultModel": "${OPENAI_MODEL}"
  }
}

Values of the form ${ENV_VAR} are resolved from the environment at load time — commit the config file without leaking secrets.

Precedence (highest to lowest)

1. CLI flags (e.g. --cache-dir, --no-cache)
2. Environment variables: THOTH_CONFIG, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
3. Config file values (with ${...} interpolation)
4. Built-in defaults: cacheDir = "./.doc-cache", provider = "openai", baseUrl = "https://api.openai.com/v1"

Caching

Every @llm block is cached by a content-addressed key derived from the provider, model, prompt, and context file hashes. Cache entries live in ./.doc-cache/ (configurable with --cache-dir).

• Deterministic: the same inputs always produce the same cache key.
• Committing the cache: regenerate without LLM credentials or network access.
• Bypassing the cache: use --no-cache to force fresh LLM calls.

Real-world examples

Maintaining an agent instructions file

A template that pulls in architecture and coding-style docs, then has the LLM write a one-paragraph summary:

# Project Instructions

@include docs/coding-style.md

## Architecture

@include docs/architecture.md

## Summary

@llm:project-summary
  context:
    - docs/architecture.md
    - docs/concept.md
    - docs/coding-style.md
  prompt: |
    Write a one-paragraph summary of this project
    for a new contributor.
@end

Generating a docs index

A template that lists project documents with LLM-generated summaries:

# Documentation Index

@llm:summarize-architecture
  context:
    - docs/architecture.md
  prompt: |
    Write a two-sentence summary of this architecture
    document and a one-line note on when to read it.
@end

@llm:summarize-concept
  context:
    - docs/concept.md
  prompt: |
    Write a two-sentence summary of this concept document
    and a one-line note on when to read it.
@end

Building a README from parts

# My Library

@include docs/badges.md

@include docs/install.md

@llm:readme-overview
  context:
    - README.md
    - docs/architecture.md
  prompt: |
    Write a 3-sentence project overview based on these docs.
@end

More information

• Concept — project mission, core values, non-goals
• Architecture — module design, directive grammar, cache key spec