runxmd — run your Markdown files

The simplest thing: write - @python, - @node, - @go (or any of 10 language plugins) directly in a .md file. Run it. Get a rendered output file with your prose intact and every code block replaced by its result. No new syntax. No @workflow required to get started.

The idea in one sentence

runxmd adds state and execution to .md files. You keep writing Markdown exactly as you do today — it still renders in GitHub, VS Code, and every viewer. The difference is that bare - @plugin steps execute directly, output renders back inline, and @memory persists state across runs. Static doc → stateful doc. Same file.

The bigger goal — save tokens, stop making models recompute. When a document already carries the results of its code (the render output), an LLM reading it doesn't have to mentally execute the snippets, guess at outputs, or burn tokens reasoning through logic it can't actually run. The answer is already in the file. runxmd turns "here's code, imagine what it prints" into "here's code and exactly what it printed" — so the model reads facts instead of computing them. Deterministic output, computed once by the real interpreter, reused by every reader (human or model) forever after.

What's new in v1.0.3 — the trust layer

"The answer is already in the file" only helps if you can tell the answer is still the answer. v1.0.3 makes that checkable, and makes a render safe to diff and safe to gate CI on.

Details: Commands · runxmd verify · Step params · Sharing state · Use in CI · SPEC-v0.0.3.md §6.

The simplest possible file

No @workflow. No @memory. No annotations at all — just prose and code steps.

# Analysis

This document runs three Python snippets and renders the results inline.

- @python
  run: |
    print("=== Arithmetic ===")
    x = 10
    print("x =", x)

This section explains what the next snippet does.
Feel free to write as much prose as you like between steps.

- @python
  run: |
    print("=== String ===")
    msg = "hello world"
    print(msg.upper())

Final note before the last snippet.

- @python
  run: |
    print("=== List ===")
    nums = [1, 2, 3, 4, 5]
    print("sum:", sum(nums))

Closing prose — steps are done.

Run it:

runxmd run analysis.md

You get analysis_render.md — your original document with every code block replaced by its output, prose preserved exactly as written:

# Analysis

This document runs three Python snippets and renders the results inline.

=== Arithmetic ===
x = 10

This section explains what the next snippet does.
Feel free to write as much prose as you like between steps.

=== String ===
HELLO WORLD

Final note before the last snippet.

=== List ===
sum: 15

Closing prose — steps are done.

The source file is never modified. The render file is your shareable, LLM-readable output. Re-run any time to refresh it.

Worked examples in this repo

Two complete, runnable showcases live in examples/showcase/. Each is a real .md you can run, paired with its committed render output so you can see exactly what runxmd produces — the render file is the token-saving artifact: a model reads the precomputed results instead of trying to execute the code in its head.

1. Polyglot capability showcase

examples/showcase/readme_showcase.md → readme_showcase_render.md

Runs Python, Node.js, Perl, and PowerShell — inline snippets and external scripts — at basic / medium / advanced levels, with tables, blockquotes, and headings woven between the steps to prove all Markdown survives untouched.

cd examples/showcase
runxmd run readme_showcase.md

2. File-existence guardrails

examples/showcase/file_checks_test.md → file_checks_test_render.md

The common "does this file/dir exist before I proceed?" guardrail at three levels: a single inline check, a multi-file inline check, and an advanced external script that audits a whole directory and prints a PASS/FAIL summary.

Before (source — code the reader would have to mentally execute):

## Level 1 — Simple: does a specific file exist?

- @python
  run: |
    import pathlib
    target = pathlib.Path("scripts/basic.py")
    if target.exists():
        print(f"  FOUND    : {target}")
        print("  GUARDRAIL PASS: required file is present")
    else:
        print("  GUARDRAIL FAIL: required file is missing")

After (file_checks_test_render.md — the answer is already in the file):

## Level 1 — Simple: does a specific file exist?

=== Simple File Check ===
  FOUND    : scripts\basic.py
  Size     : 648 bytes
  Is file  : True

  GUARDRAIL PASS: required file is present

The prose, heading, and tables are identical between the two — only the - @python block is replaced with its real, computed output.

Output modes

Every run produces an output file automatically. You control the format with an @on_done hook — or leave it out to get the default.

Default (render) is best for sharing and LLM consumption — it reads like a notebook. results is best when you want only the raw output. write is best when you want to re-run the file and see diffs over time.

Example — explicitly choose render:

@on_done
render(reports/analysis_rendered.md)

Example — output only:

@on_done
results

Install

pip install runxmd

Zero third-party dependencies — pure Python standard library (≥ 3.9).

Or from source:

git clone https://github.com/shubham10divakar/xmd.git
cd xmd
pip install -e .

Running the tests

pip install -e ".[test]"
pytest

Platform compatibility

runxmd runs on Windows, Linux, and macOS — the core runtime is pure Python stdlib with no platform-specific code.

PowerShell note: On Windows, @powershell uses powershell -ExecutionPolicy Bypass. On Linux and macOS, it uses pwsh (PowerShell Core) — install from https://aka.ms/install-powershell if needed.

Security & trust model

runxmd executes code embedded in a Markdown file. Treat a runnable .md exactly as you would treat a shell script: only run files you trust.

What this means in practice:

• runxmd run file.md executes the code inside it. @python, @node, @shell, the *_script plugins, etc. all run real commands on your machine with your permissions. There is no sandbox.
• Only run .md files you wrote or have reviewed. A document from an untrusted source can contain - @shell / - @python steps that do anything you could do from a terminal. This is the same trust decision as bash somescript.sh.
• The source file is never modified by default. Output goes to a new _render.md / _results.md / _output.md file. Memory write-back into the source only happens with the explicit --write-back flag.
• @llm and agent --autonomous run model-generated commands. With --autonomous, the LLM both writes and runs the steps — that is arbitrary code execution directed by a model. Use it only on goals and in environments where that is acceptable.
• No network or filesystem access beyond what your steps request. runxmd itself makes no outbound calls (except @http/@llm when you use them) and installs nothing — detect-don't-install means a missing interpreter fails loudly rather than fetching anything.
• Inspect before running. Use runxmd parse file.md to see the structured steps, or runxmd validate file.md to list sections, before executing an unfamiliar document.

In short: the power of runxmd is that the document is the program. The responsibility that comes with it is the same as any executable — run only what you trust.

Check what's available on your machine

Before writing a multi-language doc, run:

runxmd check

It scans every interpreter, shows what's installed, and gives install hints for anything missing:

runxmd check — interpreter availability

  Language     Plugin            Executable   Status      Version
  ---------------------------------------------------------------
  @python      @python_script    python       ✓  found    Python 3.14.5
  @node        @node_script      node         ✓  found    v24.15.0
  @typescript  @typescript_script ts-node     ✗  missing  install: npm install -g ts-node
  @ruby        @ruby_script      ruby         ✗  missing  install: https://...
  @bash        @bash_script      bash         ✓  found    GNU bash 5.3.9
  @go          @go_script        go           ✗  missing  install: https://go.dev/dl/
  @r           @r_script         Rscript      ✗  missing  install: https://cran.r-project.org/
  @php         @php_script       php          ✗  missing  install: https://...
  @perl        @perl_script      perl         ✓  found    v5.42.2
  @powershell  @powershell_script powershell  ✓  found    5.1.26100

  5 of 10 languages available.

Only install the languages you actually use — runxmd never installs anything itself.

.md and .xmd — same Markdown, one is a signal

runxmd runs both .md and .xmd files identically. The only difference is the name:

• .md — a regular Markdown file that may or may not have runnable steps.
• .xmd — the same format, byte-for-byte. The .xmd extension is a label that signals "this file is meant to be executed."

runxmd run notes.md       # runs — finds steps inside
runxmd run pipeline.xmd   # identical engine, identical grammar

Adding @workflow when you need it

For simple scripts the bare - @plugin syntax is enough. Add @workflow when you need named workflows — so you can run one selectively, or link it from a task.

@workflow deploy
- @shell
  run: docker pull myapp:latest
- @shell
  run: docker restart myapp

runxmd run deploy.md --workflow deploy   # run only this workflow

Stateful docs with @memory

@memory makes a Markdown file a system instead of a static doc.

@memory
name: "world"
runtime.status: "pending"

@workflow hello
- @python
  run: |
    print("hello {{ memory.name }}")

@on_done
set: memory.runtime.status = "done"
render

1. Read-in — memory keys are loaded at run start.
2. Substitution — {{ memory.key }} anywhere in a step resolves live.
3. Write-back — use --write-back to persist runtime.* keys back into the source file after the run.

Field ownership

• runtime.* keys — only the runtime writes these (via @on_done set:).
• Everything else — yours. The runtime reads them but never overwrites them.

The full section set

Steps written outside any @workflow (top-level in the file) run as an implicit unnamed workflow — no annotation needed.

Plugins

A step is - @plugin plus indented params:

Inline code plugins

Write code directly in the document using run: |:

External script plugins

Point at an existing file on disk using path::

- @python_script
  path: scripts/analyze.py
  args: --input data.csv

path: is resolved relative to the MD file's directory — so scripts/foo.py always means "next to the file being run", regardless of where you invoke runxmd from. Absolute paths also work. args: is split on spaces and passed to the interpreter.

Other plugins

Detect, don't install. Language plugins use whatever is already on your machine. If an interpreter is missing, the step fails with a clear message and the run continues — runxmd never installs anything for you.

Prerequisites: runxmd itself has zero dependencies (pure Python ≥ 3.9). Each language plugin requires its interpreter on PATH. Run runxmd check to see exactly what is available on your machine before writing a multi-language doc.

Multi-language example

Mix languages freely in the same file:

# Polyglot Report

- @python
  run: |
    data = [1, 2, 3, 4, 5]
    print("Python sum:", sum(data))

- @node
  run: |
    const nums = [1, 2, 3, 4, 5];
    console.log("JS sum:", nums.reduce((a, b) => a + b, 0));

- @perl
  run: |
    my @nums = (1..5);
    printf "Perl sum: %d\n", eval join("+", @nums);

Each step runs in isolation. If an interpreter is missing, that step is marked ✗ and execution continues with the next step.

Sharing state between steps — session:

Isolation is the default (and the reason step order doesn't matter). When you do want a variable from one step visible in the next, give both steps the same session: name:

- @python
  session: calc
  run: |
    total = sum(range(100))

- @python
  session: calc
  run: |
    print("total:", total)     # sees `total` from the step above

Same-session steps re-run the earlier code as a prelude, so side effects in earlier session steps (prints, file writes, requests) happen again each time a later step runs. Use it for building up a computation; keep the default isolation for everything else.

Watch mode

runxmd watch report.md                  # re-run and re-render on every save
runxmd watch report.md --interval 0.5   # poll faster
runxmd watch report.md --max-runs 3     # stop after 3 runs

Agent mode

runxmd agent turns the doc from a program you run into a goal that runs itself:

Read @goal → plan @tasks → execute each task → update @memory → write back

runxmd agent project.md              # plan (if no tasks), then run linked workflows
runxmd agent project.md --replan     # regenerate tasks from the goal
runxmd agent project.md --autonomous # LLM generates AND runs steps for unlinked tasks
runxmd agent project.md --dry-run    # show the plan without executing or writing

Planning requires ANTHROPIC_API_KEY. See examples/AGENT.xmd.

Commands

runxmd run <file> [--workflow NAME] [--write-back] [--strict] [--check] [--pure] [--raw] [--no-provenance]
runxmd watch <file> [--interval S] [--max-runs N] [--write-back] [--strict] [--pure] [--raw]
runxmd agent <file> [--replan] [--autonomous] [--model M] [--max-tokens N] [--dry-run]
runxmd verify <render> [--source FILE]
runxmd check
runxmd parse <file>
runxmd validate <file>
runxmd --version

Step params: timeout:, stdin:, if:

Any code step also takes:

- @python
  timeout: 10               # kill after 10s (exit 124)
  stdin: "input fed to the script"
  if: memory.enabled        # skip the step unless the guard holds
  run: |
    import sys; print(sys.stdin.read())

if: guards: memory.<key> (truthy), not memory.<key>, memory.<key> == "x" (also != > < >= <=), context (rolling summary set). A skipped step counts as ok and renders nothing.

runxmd verify — is this render still current?

Every render / results / output file carries an invisible provenance header:

<!-- runxmd-provenance
source: report.md
source_sha256: 3f9a…c21
runxmd_version: 1.0.3
generated_utc: 2026-08-27T09:14:22Z
platform: linux-x86_64
interpreters: {python: Python 3.14.5}
non_deterministic_steps: []
-->

runxmd verify report_render.md re-hashes report.md and exits 0 if it still matches, 3 if the source has changed since the render was generated (STALE), 2 if there's no header. Wire it into a pre-commit hook or CI so a stale render can't be trusted by accident.

Use in CI

Raw commands — in any workflow step:

pip install runxmd
runxmd verify docs/report_render.md         # 0 fresh · 3 stale · 2 no header
runxmd run docs/report.md --check           # rebuild in memory, diff, exit 1 on drift
runxmd run docs/report.md --strict          # exit non-zero if any step fails

GitHub Action — this repo ships a composite action:

# .github/workflows/docs.yml
jobs:
  renders-are-current:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shubham10divakar/xmd@v1          # runxmd verify
        with:
          # verify: "docs/*_render.md"         # default: all tracked *_render.* / *_results.* / *_output.*
          check: "docs/report.md README.md"    # also `runxmd run --check` these sources

A stale render fails the job with a ::error:: annotation.

Design principles

• Compute once, read forever. The render output carries real results so models and humans read facts instead of recomputing them — fewer tokens, no guessing.
• Run only what you trust. The document is the program; treat a runnable .md like a shell script.
• No annotation required to get started. A file with bare - @plugin steps runs.
• Source files are read-only by default. Output always goes to a new file.
• Render is the default output. Prose is preserved; only code blocks are replaced.
• Cross-platform. Runs on Windows, Linux, and macOS without changes.
• Your Markdown, not a new format. Everything outside @sections is untouched prose.
• Inline-first. Code lives in the document; the runtime is a thin dispatcher.
• Detect, don't install. Use what's on the machine; fail clearly when it's not.
• Stdlib only. Zero dependencies, including @http.

Status & roadmap

Current: v1.0.3 — see SPEC-v0.0.3.md for the full contract. (The spec document keeps its own v0.0.x numbering, independent of the package version; SPEC-v0.0.3.md is the current one.)

• ✅ Parser, executor, CLI (run / watch / agent / verify / parse / validate / check)
• ✅ Provenance headers + runxmd verify — a render carries the SHA-256 of its source
• ✅ run --strict / run --check — use a document's outputs as a CI doctest
• ✅ Output normalization (paths, $HOME, hostname, separators) + redact: — diffable renders
• ✅ run --pure — refuse non-deterministic steps so the render is a computed fact
• ✅ Plugins: shell, http, filesystem, llm
• ✅ Inline language plugins: Python, Node.js, TypeScript, Ruby, Bash, Go, R, PHP, Perl, PowerShell
• ✅ External script plugins: @python_script, @node_script, and one for every supported language
• ✅ Bare steps without @workflow — implicit unnamed workflow
• ✅ Render output (default) — prose preserved, code replaced with results
• ✅ Results output — step outputs only, for LLM consumption
• ✅ Write output — replica with result: fields for re-running
• ✅ Memory: read / substitute / write-back, with field-ownership safety
• ✅ Reactive runxmd watch
• ✅ Agent engine (@goal → auto-generate @tasks → execute → update memory)
• ✅ runxmd check — interpreter availability report with versions and install hints
• ✅ Cross-platform: Windows, Linux, macOS (PowerShell uses pwsh on Linux/macOS)
• ⏳ Declarative events (@on_file_change, @daily, @on_commit)
• ⏳ Portable @task abstraction
• ⏳ Multi-agent / distributed

Contributions and ideas welcome.

License

MIT — see LICENSE.