Home

Coding Agents

While your deployed site serves /llms.txt to web tools, coding agents working in a local checkout need an index that links directly to repository files and line numbers:

luaudocs llms

This writes llms.txt at your project root, indexing your guides and every public module, type, and member with links to their declaration lines. Because it only runs extraction and markdown rendering, you don't need luaudocs init, a VitePress build, or a docs directory.

What it contains

Here is the llms.txt generated for this repository (indexing the guides and examples/Flux):

llms.txt

<!-- Generated by luaudocs: edits here are lost the next time `luaudocs llms` runs. -->
# LuauDocs

> Documentation generator for Luau.

This file indexes the project for coding agents reading a local copy of it, in the llms.txt format: its guides, then every module, type, and member its Luau source exposes. Links are relative to this file, and each API entry links the lines that declare it, directly below its doc comment.

Keep it current: after changing the public surface, a doc comment, or a guide, run `npx luaudocs@latest llms` in this directory and commit the result. When nothing listed here changed, the command leaves the file as it is.

## Guides

- [Getting Started](.luaudocs/guide/getting-started.md): Install LuauDocs and build a browsable documentation site for your Luau library.
- [How It Works](.luaudocs/guide/how-it-works.md): How LuauDocs finds your public surface and organizes your documentation site.
- [Writing Doc Comments](.luaudocs/guide/writing-doc-comments.md): Write prose descriptions and automatic symbol cross-references for your Luau API.
- [Overriding with Tags](.luaudocs/guide/overriding-with-tags.md): Override inferred types, placement, visibility, and badges with Moonwave-compatible tags.
- [Configuration](.luaudocs/guide/configuration.md): Configure luaudocs.toml, understand file ownership, and style your site with custom.css.
- [Deploying](.luaudocs/guide/deploying.md): Publish your documentation site to GitHub Pages or Cloudflare Pages with base paths and custom domains.
- [Coding Agents](.luaudocs/guide/coding-agents.md): Generate a repository-root llms.txt index with file and line links for coding agents.
- [Migrating from Moonwave](.luaudocs/guide/migrating-from-moonwave.md): Convert a Moonwave project, including hand-written guides and assets, in one command.
- [CLI](.luaudocs/guide/reference/cli.md): Every luaudocs command and flag.
- [Tags](.luaudocs/guide/reference/tags.md): Complete reference for all 24 Moonwave-compatible override tags in LuauDocs.
- [Markup](.luaudocs/guide/reference/markup.md): Admonitions, tabs, frames, badges, and inline highlighting in doc comments and guide pages.
- [Diagnostics](.luaudocs/guide/reference/diagnostics.md): Every diagnostic code LuauDocs emits and how each severity affects your build.
- [Doc Model](.luaudocs/guide/reference/doc-model.md): Export the JSON doc model that LuauDocs extracts from your source and use it in your own tooling.
- [Troubleshooting](.luaudocs/guide/reference/troubleshooting.md): Fix environment and build failures that occur outside source-level diagnostics.

## Flux

- [Flux](examples/Flux/init.luau): A tiny reactive state library.
- [`Flux.State: State`](examples/Flux/State.luau): [Module]
- [`Flux.Util: Util`](examples/Flux/Util/init.luau): [Module]
- [`Flux.state<T>(initial: T?): State.State<T>`](examples/Flux/init.luau#L18-L20): Creates a state holding `initial`.
- [`Flux.isState(value: any): boolean`](examples/Flux/State.luau#L20-L22): [from State] Reports whether `value` is a state.

## Flux.State

- [State](examples/Flux/State.luau): A single reactive value, and the listeners watching it. Constructors: `Flux.state`, `State.new`.
- [`type State<T>`](examples/Flux/State.luau#L6-L12): A value that notifies listeners whenever it changes.
- [`State.new<T>(initial: T?): State<T>`](examples/Flux/State.luau#L15-L17): Creates a state holding `initial`.
- [`State.isState(value: any): boolean`](examples/Flux/State.luau#L20-L22): Reports whether `value` is a state.
- [`State:Connect(callback: (any) -> ()): () -> ()`](examples/Flux/State.luau#L29-L37): Runs `callback` whenever the value changes.
- [`State:Destroy()`](examples/Flux/State.luau#L44-L46): [Deprecated since 2.0: states are collected once nothing references them] Drops every listener and releases the state.

## Flux.Util

- [Util](examples/Flux/Util/init.luau): Small helpers that stand on their own.
- [`Util.Queue: Queue`](examples/Flux/Util/Queue.luau): [Module]

## Flux.Util.Queue

- [Queue](examples/Flux/Util/Queue.luau): A queue that yields on `pop` until something is available. Constructors: `Queue.new`.
- [`type Queue<T>`](examples/Flux/Util/Queue.luau#L6-L11): A first-in, first-out queue.
- [`Queue.new<T>(): Queue<T>`](examples/Flux/Util/Queue.luau#L14-L16): Creates an empty queue.
- [`Queue:push(item: any)`](examples/Flux/Util/Queue.luau#L23-L25): [since 1.1.0] Adds `item` to the back of the queue.
- [`Queue:pop(): any`](examples/Flux/Util/Queue.luau#L28-L33): [Yields] Removes the front item and returns it, waiting when the queue is empty.

## Optional

- [Changelog](CHANGELOG.md): Notable changes to LuauDocs, newest first.

• Guides link to their local Markdown files with their frontmatter summaries.
• Each module gets a section ordered like the API reference and headed by its access path (Flux.Util.Queue), listing the module, its types, and its members.
• Every entry is a Luau signature linked to its file:line span right below its doc comment.
• Bracketed labels carry badges ([Yields], [Server], [Read Only], [from State], and deprecation notes).
• CHANGELOG.md appears under Optional.

Because luaudocs llms derives llms.txt solely from committed repository files, every checkout produces identical bytes. Commit it alongside your source code.

Pointing agents at it

Reference llms.txt in your root AGENTS.md or CLAUDE.md:

AGENTS.md

## Public API

`llms.txt` indexes this library's guides and public API. Read it before using or changing the API. After changing the public surface, a doc comment, or a guide, run `npx luaudocs@latest llms` and commit the regenerated `llms.txt` with your change.

CLAUDE.md

## Public API

@llms.txt

After changing the public surface, a doc comment, or a guide, run `npx luaudocs@latest llms` and commit the regenerated `llms.txt` with your change.

Claude Code expands @llms.txt into context automatically. This works well for small libraries. For larger libraries, reference llms.txt by name so agents read it on demand.

The generated llms.txt header includes the exact npx luaudocs@latest llms regeneration command, and running luaudocs llms leaves the file untouched on disk when nothing changed.

Checking it in CI

Use --check in CI to fail when the committed llms.txt is missing, stale, or hits extraction errors:

npx luaudocs@latest llms --check

A normal luaudocs llms run also aborts without overwriting llms.txt if extraction errors occur, so a temporary syntax error never strips modules from the index.

Where it lives

Pass --out <file> to write the index to another path. All relative links and the embedded regeneration command adjust automatically.

luaudocs llms only overwrites an existing file if line 1 starts with <!-- Generated by luaudocs. Removing that marker claims the file as hand-maintained. Setting [docs] llms = false only disables the site's public/llms*.txt files and doesn't affect luaudocs llms.