Codemixture

A literate programming system for the AI coding era.

Programs are written as markdown documents with executable code in standard fenced code blocks. The prose — design rationale, specifications, constraints, prompts — is interwoven with the code. The documents are simultaneously human-readable documentation, AI-readable context, and executable programs.

The Problem

Code and documentation live in separate worlds. Comments rot. READMEs drift. Design docs go stale the moment code ships. AI coding agents work from context that's scattered across files, commit messages, and Slack threads.

The Idea

What if the documentation was the program? What if the markdown you write to explain your design also contained the code that implements it?

Codemixture documents are valid CommonMark. Code lives in standard fenced code blocks. Metadata lives in invisible HTML comments. Macros are expressed as comments in the target language. Everything renders correctly on GitHub, in VS Code, in any markdown viewer — with zero preprocessing.

Example

Here's a complete codemixture document:

# Hello World

<!-- codemixture
type: module
file: hello.py
language: python
-->

A simple greeting program.

```python
def main():
    print("Hello from codemixture!")

if __name__ == "__main__":
    main()
```

Run cm tangle hello.md and out comes hello.py.

For more complex programs, named sections let you define code in the order that makes sense for explanation, then assemble it in the order the language requires:

```python
# @begin(imports)
import sys
# @end(imports)
```

Later, we can include that section:

```python
# @include(imports)

def main():
    print("hello")
```

Quick Start

# Clone and bootstrap
git clone <repo-url> && cd codemixture
python3 bootstrap.py tangler.md
python3 bootstrap.py cli.md

# Install with uv
uv sync --all-extras

# Tangle, check, test
uv run cm tangle tangler.md cli.md checker.md watcher.md
uv run cm check tangler.md cli.md checker.md watcher.md
uv run pytest tests/ -v

How It Works

Tangling extracts executable code from .md files:

cm tangle mymodule.md              # Single file
cm tangle *.md                     # Project (enables cross-document refs)
cm tangle mymodule.md --dry-run    # Preview without writing

Checking validates documents without tangling:

cm check *.md           # Report errors and warnings
cm check *.md --strict  # Treat warnings as errors

Watching re-tangles on file changes:

cm watch *.md           # Requires: pip install codemixture[watch]

Initializing scaffolds a new project:

cm init myproject --language python

Self-Hosting

Codemixture is written in codemixture. The .md files in this repository are the source of truth:

bootstrap.py is the only non-.md Python source — a minimal ~90-line tangler that bootstraps the real one.

Format Specification

See codemixture.md for the complete format specification, including:

• Document anatomy (prose, code, metadata)
• The macro system (@begin/@end, @include, @append)
• Cross-document references
• Multiple output files
• Metadata fields

License

MIT