codemixture 0.1.0
A literate programming system for the AI coding era
Requires Python: >=3.11
Keywords: literate-programming, markdown, tangling, ai

# 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:

````markdown
# 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:

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

Later, we can include that section:

```python
# @include(imports)

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

## Quick Start

```bash
# 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:

```bash
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:

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

**Watching** re-tangles on file changes:

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

**Initializing** scaffolds a new project:

```bash
cm init myproject --language python
```

## Self-Hosting

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

| Document | Produces | Description |
|----------|----------|-------------|
| `tangler.md` | `tangle.py` | The tangler — code extraction and macro resolution |
| `cli.md` | `cli.py`, `__init__.py` | The `cm` command-line tool |
| `checker.md` | `check.py` | Document validator |
| `watcher.md` | `watch.py` | File watcher with debouncing |

`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