ctxr

ctxr is a CLI tool that bundles a markdown file and its linked dependencies into a single, tagged output suitable for feeding as context to an LLM.

Usage

ctxr [--circular] <file>

Reads <file>, resolves any ctxr link comments, and prints the result to stdout.

ctxr index.md
ctxr docs/context.md | pbcopy
ctxr README.md > context.txt

Link syntax

Inside any markdown file, use an HTML comment to declare a link to another file:

<!-- ctxr: ./path/to/file.md -->

• The path is relative to the file containing the comment
• The comment is replaced in the output by the linked file's content, wrapped in XML-style tags
• Links are resolved recursively (linked files may themselves contain <!-- ctxr: ... --> comments)

Output format

Every file's content is wrapped in XML-style tags using the file's basename:

<filename.md>
...content...
</filename.md>

The entry file wraps the entire output. Linked files are inlined at the position of their <!-- ctxr: ... --> comment, each wrapped in their own tags.

Duplicate basenames: if two linked files share the same basename (e.g. a/index.md and b/index.md), the tag uses the link path as written in the comment with the leading ./ stripped:

<!-- ctxr: ./a/index.md -->  →  <a/index.md>...</a/index.md>
<!-- ctxr: ./b/index.md -->  →  <b/index.md>...</b/index.md>

Tag names are determined after all links are resolved, so a basename is only promoted to its full path if it appears more than once across the entire output.

Examples

No links

Input (input.md):

## A markdown file

Just a basic markdown file nothing fancy

Output:

<input.md>
## A markdown file

Just a basic markdown file nothing fancy
</input.md>

One link

Input (input.md):

## A markdown file with a link

This markdown file contains a link to another markdown file

<!-- ctxr: ./link.md -->

There is also some content below the link

link.md:

## Linked markdown file

This file is linked to by the input for this test

> It has a blockquote!

Output:

<input.md>
## A markdown file with a link

This markdown file contains a link to another markdown file

<link.md>
## Linked markdown file

This file is linked to by the input for this test

> It has a blockquote!
</link.md>

There is also some content below the link
</input.md>

Flags

--circular

By default, circular links are an error. With --circular, a file that has already been visited in the current resolution chain is not expanded again. Instead, the link is replaced with a placeholder tag:

<a.md>circular link to b.md</a.md>

Where a.md is the file that contains the circular <!-- ctxr: ... --> comment, and b.md is the file that was already visited. A warning is also printed to stderr:

⚠️ Circular link from a.md to b.md

Error cases

• File not found: if the entry file does not exist, exit with a non-zero code and print an error to stderr
• Unresolvable link: if a <!-- ctxr: ... --> path cannot be resolved, exit with a non-zero code and print the offending path to stderr
• Circular links: if a file transitively links back to itself, exit with a non-zero code indicating a cycle (unless --circular is passed)