LLMs as unix scripts. Write the prompt in markdown, run it like a command.
curl -sSL https://raw.githubusercontent.com/xmd-scripts/xmd/main/install.sh | sh
what it is
Write what you want in plain markdown. xmd sends it to any OpenAI-compatible model, gives it file and shell tools sandboxed to your working directory, streams output to stdout and reasoning to stderr.
#!/usr/bin/env xmd
Find all images with a blue
background in this directory.
./find-blue.md
variables
Variables are declared in a YAML block and listed in a preamble the model reads before your script. Pass them as key=value arguments.
#!/usr/bin/env xmd --- vars: name: required --- Say hello to $NAME in a creative way.
./hello.md name=world
includes
Include other markdown files as shared instructions. Reuse tone, format rules, or domain knowledge across any number of scripts. You decide exactly what context each script gets, instead of throwing hundreds of skills at every agent call.
#!/usr/bin/env xmd --- vars: topic: required include: - tone.md - output-format.md --- Write a blog post about $TOPIC.
./blog-post.md topic="the future of coding"
subagents
An xmd script can run another xmd script as a subprocess via shell tools. Each call gets a fresh model context: no shared state, no leakage. Subagent semantics from Unix process isolation.
#!/usr/bin/env xmd --- vars: topic: required --- Write a short essay about $TOPIC. Then run ./critic.md and pass the essay through stdin. Rewrite based on the feedback and output the final version.
unix pipes
Declare a variable as stdin: true and it maps directly to a pipe. Chain scripts the same way you chain shell commands.
cat pitch.md | ./architect.md | ./spec-writer.md > spec.md
--- vars: topic: required draft: stdin: true --- Review how well this $DRAFT covers $TOPIC. Rate it 1–10. Output: ## Rating <n>/10 ## Gaps <one line> ## Suggestion <one actionable fix>
debuggable ai workflows
Pass --debug to dump the full rendered prompt to stderr: every include, every variable, exactly as sent to the model.
cat essay.md | ./review.md --debug topic="the future of coding" 2>prompt.txt
backends
Point XMD_COMPLETION_URL at any backend. Defaults to localhost:11434 (ollama).
XMD_COMPLETION_URL=https://api.openai.com/v1/chat/completions ./script.md
no reinventing the wheel
xmd maps familiar agent concepts to primitives you already know. stdout and exit codes mean it composes naturally with shell scripts for deterministic orchestration.
| feature | xmd — the unix way |
|---|---|
| subagents | process isolation via shell calls |
| MCP servers | CLI programs run by scripts |
| skills & rules | markdown files, composable with includes |
| orchestration | stdin / stdout, pipes, exit codes |
| discovery | --help shows script usage |
| remote agents | ssh for remote scripts |
tell your agent
Read the quickstart yourself, or drop the agent skill directly into your coding agent.
Ready-to-run examples in the repo.