> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimensionalos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codeblocks

# Executable Code Blocks

We use [md-babel-py](https://github.com/leshy/md-babel-py/) to execute code blocks in markdown and insert results.

## Golden Rule

**All code blocks must be executable.** Never write illustrative/pseudo code blocks. If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures documentation stays correct as the codebase evolves.

## Running

```sh skip theme={null}
md-babel-py run document.md          # edit in-place
md-babel-py run document.md --stdout # preview to stdout
md-babel-py run document.md --dry-run # show what would run
```

## Supported Languages

Python, Shell (sh), Node.js, plus visualization: Matplotlib, Graphviz, Pikchr, Asymptote, OpenSCAD, Diagon.

## Code Block Flags

Add flags after the language identifier:

| Flag              | Effect                                            |
| ----------------- | ------------------------------------------------- |
| `session=NAME`    | Share state between blocks with same session name |
| `output=path.png` | Write output to file instead of inline            |
| `no-result`       | Execute but don't insert result                   |
| `skip`            | Don't execute this block                          |
| `expected-error`  | Block is expected to fail                         |

Use `skip` when a block would pull in **CUDA / GPU-only** stacks (for example perception models, `VoxelGridMapper` defaults, or imports that load torch with GPU expectations), or when it is **flaky in CI** (multi-module coordinators, timing-sensitive workers, pytest-style snippets that are not meant to run as a single script). Prefer `expected-error` only when the block is supposed to fail and you want to assert that failure.

## Examples

# md-babel-py

Execute code blocks in markdown files and insert the results.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/dimensional/coding-agents/docs/assets/screencast.gif" alt="Demo" />

**Use cases:**

* Keep documentation examples up-to-date automatically
* Validate code snippets in docs actually work
* Generate diagrams and charts from code in markdown
* Literate programming with executable documentation

## Languages

### Shell

```sh theme={null}
echo "cwd: $(pwd)"
```

```results theme={null}
cwd: /home/lesh/coding/dimos
```

### Python

```python session=example theme={null}
a = "hello world"
print(a)
```

```results theme={null}
hello world
```

Sessions preserve state between code blocks:

```python session=example theme={null}
print(a, "again")
```

```results theme={null}
hello world again
```

### Node.js

```node theme={null}
console.log("Hello from Node.js");
console.log(`Node version: ${process.version}`);
```

```results theme={null}
Hello from Node.js
Node version: v24.11.1
```

### Matplotlib

```python output=assets/matplotlib-demo.svg theme={null}
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import numpy as np
plt.style.use('dark_background')
x = np.linspace(0, 4 * np.pi, 200)
plt.figure(figsize=(8, 4))
plt.plot(x, np.sin(x), label='sin(x)', linewidth=2)
plt.plot(x, np.cos(x), label='cos(x)', linewidth=2)
plt.xlabel('x')
plt.ylabel('y')
plt.legend()
plt.grid(alpha=0.3)
plt.savefig('{output}', transparent=True)
```

<img src="https://mintlify.s3.us-west-1.amazonaws.com/dimensional/coding-agents/docs/assets/matplotlib-demo.svg" alt="output" />

### Pikchr

SQLite's diagram language:

<details>
  <summary>diagram source</summary>

  ```pikchr fold output=assets/pikchr-demo.svg theme={null}
  color = white
  fill = none
  linewid = 0.4in

  # Input file
  In: file "README.md" fit
  arrow

  # Processing
  Parse: box "Parse" rad 5px fit
  arrow
  Exec: box "Execute" rad 5px fit

  # Fan out to languages
  arrow from Exec.e right 0.3in then up 0.4in then right 0.3in
  Sh: oval "Shell" fit
  arrow from Exec.e right 0.3in then right 0.3in
  Node: oval "Node" fit
  arrow from Exec.e right 0.3in then down 0.4in then right 0.3in
  Py: oval "Python" fit

  # Merge back
  X: dot at (Py.e.x + 0.3in, Node.e.y) invisible
  line from Sh.e right until even with X then down to X
  line from Node.e to X
  line from Py.e right until even with X then up to X
  Out: file "README.md" fit with .w at (X.x + 0.3in, X.y)
  arrow from X to Out.w
  ```
</details>

<img src="https://mintlify.s3.us-west-1.amazonaws.com/dimensional/coding-agents/docs/assets/pikchr-demo.svg" alt="output" />

### Asymptote

Vector graphics:

```asymptote output=assets/histogram.svg theme={null}
import graph;
import stats;

size(400,200,IgnoreAspect);
defaultpen(white);

int n=10000;
real[] a=new real[n];
for(int i=0; i < n; ++i) a[i]=Gaussrand();

draw(graph(Gaussian,min(a),max(a)),orange);

int N=bins(a);

histogram(a,min(a),max(a),N,normalize=true,low=0,rgb(0.4,0.6,0.8),rgb(0.2,0.4,0.6),bars=true);

xaxis("$x$",BottomTop,LeftTicks,p=white);
yaxis("$dP/dx$",LeftRight,RightTicks(trailingzero),p=white);
```

<img src="https://mintlify.s3.us-west-1.amazonaws.com/dimensional/coding-agents/docs/assets/histogram.svg" alt="output" />

### Graphviz

```dot output=assets/graph.svg theme={null}
A -> B -> C
A -> C
```

<img src="https://mintlify.s3.us-west-1.amazonaws.com/dimensional/coding-agents/docs/assets/graph.svg" alt="output" />

### Diagon

ASCII art diagrams:

```diagon mode=Math theme={null}
1 + 1/2 + sum(i,0,10)
```

```results theme={null}
        10
        ___
    1   ╲
1 + ─ + ╱   i
    2   ‾‾‾
         0
```

```diagon mode=GraphDAG theme={null}
A -> B -> C
A -> C
```

```results theme={null}
┌───┐
│A  │
└┬─┬┘
 │┌▽┐
 ││B│
 │└┬┘
┌▽─▽┐
│C  │
└───┘
```

## Install

### Nix (recommended)

```sh skip theme={null}
# Run directly from GitHub
nix run github:leshy/md-babel-py -- run README.md --stdout

# Or clone and run locally
nix run . -- run README.md --stdout
```

### Docker

```sh skip theme={null}
# Pull from Docker Hub
docker run -v $(pwd):/work lesh/md-babel-py:main run /work/README.md --stdout

# Or build locally via Nix
nix build .#docker     # builds tarball to ./result
docker load < result   # loads image from tarball
docker run -v $(pwd):/work md-babel-py:latest run /work/file.md --stdout
```

### pipx

```sh skip theme={null}
pipx install md-babel-py
# or: uv pip install md-babel-py
md-babel-py run README.md --stdout
```

If not using nix or docker, evaluators require system dependencies:

| Language  | System packages             |
| --------- | --------------------------- |
| python    | python3                     |
| node      | nodejs                      |
| dot       | graphviz                    |
| asymptote | asymptote, texlive, dvisvgm |
| pikchr    | pikchr                      |
| openscad  | openscad, xvfb, imagemagick |
| diagon    | diagon                      |

```sh skip theme={null}
# Arch Linux
sudo pacman -S python nodejs graphviz asymptote texlive-basic openscad xorg-server-xvfb imagemagick

# Debian/Ubuntu
sudo apt-get install python3 nodejs graphviz asymptote texlive xvfb imagemagick openscad
```

Note: pikchr and diagon may need to be built from source. Use Docker or Nix for full evaluator support.

## Usage

```sh skip theme={null}
# Edit file in-place
md-babel-py run document.md

# Output to separate file
md-babel-py run document.md --output result.md

# Print to stdout
md-babel-py run document.md --stdout

# Only run specific languages
md-babel-py run document.md --lang python,sh

# Dry run - show what would execute
md-babel-py run document.md --dry-run

# Longer subprocess limit (default 60s); see upstream README for MD_BABEL_EXECUTION_TIMEOUT
md-babel-py run document.md --execution-timeout 120
```