This guide demonstrates 10 progressively more impressive ways to use mdflow (md). We start with basic scripts and end with a self-orchestrating swarm that works in parallel across multiple git worktrees.
Concept: Engine Inference
The engine to run (claude) is inferred automatically from the filename. That's just one way to pin an engine — the full resolution ladder is --engine flag > MDFLOW_ENGINE env var > filename > frontmatter engine: > config > the built-in default (pi).
File: 01-hello.claude.md
---
model: haiku
---
Say "Hello! I am an executable markdown file." and nothing else.Run it:
md 01-hello.claude.mdConcept: Template Variables & Defaults
Variables starting with _ define defaults that can be overridden by CLI flags.
File: 02-config.claude.md
---
model: haiku
# Template variables with defaults
_mode: development
_port: 8080
---
Generate a JSON configuration for a server running in **{{ _mode }}** mode on port **{{ _port }}**.
Return ONLY the raw JSON.Run it:
# Use defaults
md 02-config.claude.md
# Override with flags
md 02-config.claude.md --_mode production --_port 3000Concept: Conditionals & Template Variables
Use _varname to define template variables, and LiquidJS tags to change the prompt dynamically.
File: 03-deploy.copilot.md
---
_service_name: ""
_platform: docker
model: gpt-4
---
Generate a deployment script for {{ _service_name }}.
{% if _platform == 'k8s' %}
Generate a Kubernetes Deployment YAML. Include liveness probes.
{% elsif _platform == 'aws' %}
Generate an AWS Lambda SAM template.
{% else %}
Generate a simple Dockerfile.
{% endif %}Run it:
md 03-deploy.copilot.md --_service_name "auth-service" --_platform "k8s"Concept: Command Inlines Execute shell commands inside the prompt to inject the current system state.
File: 04-debug.claude.md
---
model: sonnet
---
I am seeing an error. Here is my current system state:
**Git Status:**
!`git status --short`
**Recent Logs:**
!`tail -n 5 error.log 2>/dev/null || echo "No logs found"`
Based on this, what should I check first?Run it:
md 04-debug.claude.mdConcept: Symbol Extraction Import specific TypeScript interfaces or functions instead of wasting tokens on entire files.
File: 05-mock-gen.claude.md
---
model: sonnet
---
Generate a JSON mock object that satisfies this TypeScript interface:
@./src/types.ts#UserSession
Output only the JSON.Run it:
md 05-mock-gen.claude.md > mock-user.jsonConcept: Glob Imports & Environment Config
Import entire directory trees. We set MDFLOW_FORCE_CONTEXT in _env to override the default token safety limit for large imports.
File: 06-audit.agy.md
---
_env:
MDFLOW_FORCE_CONTEXT: "1"
---
You are a Security Auditor. Scan the following files for hardcoded secrets or unsafe regex:
@./src/**/*.ts
List any vulnerabilities found.Run it:
md 06-audit.agy.mdConcept: Standard Input (Stdin)
Piped input is available as the _stdin template variable, allowing agents to act as filters in Unix pipes.
File: 07-describe-changes.claude.md
---
model: haiku
---
Generate a concise PR description for these changes:
{{ _stdin }}
Include a "Summary" and "Key Changes" section.Run it:
git diff --staged | md 07-describe-changes.claude.mdConcept: Agent Chaining Pipe the output of one agent (The Summarizer) into another (The Critic).
File: 08a-summarize.claude.md
---
model: haiku
---
Summarize the file content into a high-level architecture description:
{{ _stdin }}File: 08b-critique.claude.md
---
model: opus
---
You are a Principal Engineer. Critique this architecture description:
{{ _stdin }}
Identify bottlenecks and suggest scalability improvements.Run it:
cat src/*.ts | md 08a-summarize.claude.md | md 08b-critique.claude.mdConcept: Remote Execution Run an agent directly from a URL without downloading it. Perfect for sharing team SOPs.
Run it:
md https://raw.githubusercontent.com/johnlindquist/mdflow/main/examples/hello.claude.mdRemote URLs are cached locally for 1 hour. Use --_no-cache to force a fresh fetch:
md https://example.com/agent.claude.md --_no-cacheConcept: Multi-Agent Worktree Orchestration An "Architect" agent generates a shell script that spawns multiple "Worker" agents, each running in a purely isolated git worktree.
The Worker: 10-worker.claude.md
---
_task: ""
model: sonnet
---
You are a worker bee. Implement this task in the current directory: {{ _task }}
Write the code to a file named `implementation.ts`.The Architect: 10-architect.claude.md
---
_goal: ""
model: opus
---
You are a Fleet Commander. Break down the goal "{{ _goal }}" into 2 parallel sub-tasks.
Generate a BASH script that:
1. Creates 2 git worktrees (`wt-frontend` and `wt-backend`) on new branches.
2. Inside each worktree, runs `md ../10-worker.claude.md --_task "sub-task description"`.
3. Runs them in the background (`&`) and `wait`s for them to finish.
Output ONLY the raw bash script.Run the Swarm:
# 1. The Architect creates the plan and script
# 2. We pipe the script to sh to execute the swarm immediately
md 10-architect.claude.md --_goal "Build a login page with a fastify backend" | shWhile Part 1 focused on power and complexity, Part 2 focuses on User Experience (UX). These examples demonstrate features designed to make working with AI agents safe, interactive, and easy to understand for your team.
Concept: Variable Recovery
UX Problem: You wrote a prompt with variables, but you don't want to memorize the flags.
Solution: If you forget to provide variables, md detects them and turns the CLI into an interactive form.
File: 11-onboarding.claude.md
---
_name: ""
_department: ""
_manager: ""
model: sonnet
---
Welcome to the team, {{ _name }}!
Please generate a warm onboarding email for a new engineer joining the {{ _department }} team.
Mention that their manager is {{ _manager }}.Run it (without flags):
md 11-onboarding.claude.mdmd responds:
Missing required variables. Please provide values:
? _name: Alice
? _department: Platform
? _manager: Bob
UX Benefit: Turns static scripts into interactive tools automatically.
Concept: Trust & Verification
UX Problem: You are about to run an agent on your entire codebase, but you're nervous about token costs or context size.
Solution: Use --_dry-run to see exactly what would happen—the command, the expanded files, and the token count—without executing anything.
File: 12-refactor.claude.md
---
model: opus
---
Refactor every file in this directory:
@./src/**/*.tsRun it:
md 12-refactor.claude.md --_dry-runOutput:
DRY RUN - Command will NOT be executed
Command: claude --model opus ...
Final Prompt: (Shows full expanded content of all files)
Estimated tokens: ~15,420
UX Benefit: Verify expensive operations before spending money.
Concept: Shebang Support
UX Problem: Typing md filename.md feels like running a script. You want it to feel like a native system command.
Solution: Add a standard Unix shebang line.
File: daily-report (no extension needed)
#!/usr/bin/env md
---
engine: claude
model: haiku
---
Generate a "Daily Standup" update based on my git activity:
!`git log --since="24 hours ago" --oneline`Run it:
chmod +x daily-report
./daily-reportUX Benefit: Abstracts away the tool entirely. It just behaves like a binary.
Concept: Template Variables with Defaults
UX Problem: You want to expose configuration settings (defaults) that users can easily override via flags.
Solution: Variables starting with _ in the frontmatter define defaults that can be overridden via --_varname flags.
File: 14-translator.gpt.md
---
engine: openai
model: gpt-4o
# Default configuration
_lang: Spanish
_tone: Professional
_text: ""
---
Translate the following text into {{ _lang }}. Keep the tone {{ _tone }}.
<text>
{{ _text }}
</text>Run it:
# Use defaults
md 14-translator.gpt.md --_text "Hello World"
# Tweak the knobs via flags
md 14-translator.gpt.md --_text "Hello World" --_lang "Pirate" --_tone "Aggressive"UX Benefit: Creates a stable CLI interface for your prompts.
Concept: Symbol Extraction
UX Problem: Importing entire files is wasteful and distracting when you only need one specific interface.
Solution: Use the #Symbol syntax to extract specific code blocks (Functions, Classes, Interfaces).
File: 15-test-gen.claude.md
---
model: sonnet
---
Write a unit test for this specific function:
@./src/utils.ts#calculateTax
Ensure it returns a type matching:
@./src/types.ts#TaxResultUX Benefit: Precision context reduces hallucinations and token costs.
Concept: Recursive Imports UX Problem: You constantly have to import the same 5 files (auth, database, types) for every task. Solution: Create a "Context Pack"—a markdown file that just imports other files—and import that.
Note: Import statements inside code blocks (``` or `) are now properly ignored by the parser.
File: _context-auth.md
# Auth System Context
@./src/auth/session.ts
@./src/auth/types.ts
@./src/auth/login.tsFile: 16-security-audit.claude.md
---
model: opus
---
Review the authentication flow for security holes.
@./_context-auth.mdUX Benefit: Build a library of "mental models" that are easy to drop into any agent.
Concept: Environment Isolation
UX Problem: You need API keys in your prompts but can't commit them to Git.
Solution: md automatically loads .env files from the markdown file's directory.
Structure:
/my-agents/
├── .env (Contains: API_URL=https://api.staging.com)
└── 17-api-check.claude.md
File: 17-api-check.claude.md
---
model: sonnet
---
Write a curl command to check the health of:
!`echo $API_URL`UX Benefit: Safe, zero-config secret management that works with Git.
Concept: Engine Override
UX Problem: You want to A/B test a prompt against different models without creating multiple files.
Solution: Pick the engine explicitly with the --engine flag — the top rung of the resolution ladder. (The old --_command/-_c and --tool flags still work as deprecated aliases.)
File: 18-story.md (No engine in filename)
Write a two-sentence horror story about a compiler.Run it:
# Test with Claude
md 18-story.md --engine claude --model haiku
# Test with Antigravity
md 18-story.md --engine agyWithout an explicit engine, this file has no frontmatter — so md 18-story.md treats it as a document and prints it instead of executing it.
UX Benefit: Decouple your prompt logic from specific providers.
Concept: Structured Logging
UX Problem: An agent hallucinated or failed, and you need to see exactly what was sent to the API.
Solution: md logs every execution to ~/.mdflow/logs/.
File: 19-mystery.claude.md
---
model: opus
---
(Some complex prompt with dynamic imports...)Run it:
md 19-mystery.claude.mdDebug it:
md logs
# Agent logs:
# /Users/me/.mdflow/logs/19-mystery-claude/UX Benefit: Instant forensic debugging without cluttering your terminal.
Concept: Self-Replication UX Problem: Creating new agents takes time. Solution: Use an agent to write your agents.
File: 20-agent-smith.claude.md
---
_goal: ""
model: sonnet
---
I want to create a new markdown-agent file.
Goal: {{ _goal }}
Write the full content of a `.md` file that accomplishes this.
Include appropriate frontmatter defaults (model, _varname template variables).
Use standard `md` features like `@imports` if the goal implies reading code.
Output ONLY the raw markdown code block.Run it:
md 20-agent-smith.claude.md --_goal "Review my rust code" > review-rust.claude.mdUX Benefit: The tool helps you build the tool.
These examples demonstrate the latest features added to mdflow.
Concept: Typed Interactive Inputs
UX Problem: You want a proper form with different input types, not just text prompts.
Solution: Use the new _inputs object format with typed fields.
File: 21-deploy-wizard.claude.md
---
model: sonnet
_inputs:
_service:
type: text
description: "Service name"
default: "api"
_environment:
type: select
options: [development, staging, production]
_replicas:
type: number
description: "Number of replicas"
_dry_run:
type: confirm
description: "Dry run only?"
---
Generate a deployment manifest for {{ _service }} in {{ _environment }}.
{% if _replicas > 1 %}Use {{ _replicas }} replicas for high availability.{% endif %}
{% if _dry_run %}This is a dry run - just show what would happen.{% endif %}Run it:
md 21-deploy-wizard.claude.mdUX Benefit: Type-safe forms with select dropdowns, number inputs, and confirmations.
Concept: Configuration Debugging
UX Problem: Your agent isn't running as expected, and you need to see what's actually being sent.
Solution: Use md explain to see the fully resolved configuration.
Run it:
md explain review.claude.mdOutput:
╭─ Agent Analysis ──────────────────────────────────────────────╮
│ Command: claude (from filename: review.claude.md) │
│ Interactive: false (default: print mode) │
│ │
│ Config Chain: │
│ ✓ Built-in defaults │
│ ✓ ~/.mdflow/config.yaml │
│ ✗ ./mdflow.config.yaml (not found) │
│ ✓ Frontmatter │
│ │
│ Final Flags: --model opus --print │
│ Token Usage: ~12,450 / 100,000 (12.4%) │
╰───────────────────────────────────────────────────────────────╯
UX Benefit: Understand exactly what md will do before running it.
Concept: Context Visualization
UX Problem: You're importing many files and want to verify the context before sending to the LLM.
Solution: Use --_context to see the context tree and exit.
File: 23-review-all.claude.md
---
model: opus
---
Review this entire codebase:
@./src/**/*.ts
@./tests/**/*.tsRun it:
md 23-review-all.claude.md --_contextOutput:
┌─ Pre-Flight ──────────────────────────────────────────────────┐
│ 📄 23-review-all.claude.md 0.2 KB │
│ ├── 📁 @./src/**/*.ts (24 files) 48.3 KB │
│ └── 📁 @./tests/**/*.ts (12 files) 22.1 KB │
│ │
│ Total: 70.6 KB (~17,650 tokens) │
└───────────────────────────────────────────────────────────────┘
UX Benefit: Know your token budget before committing to an expensive API call.
Concept: Edit Before Execute
UX Problem: You want to tweak the final prompt after all imports are resolved.
Solution: Use --_edit to open the fully resolved prompt in your editor.
File: 24-summarize.claude.md
---
model: haiku
---
Summarize this code:
@./src/main.tsRun it:
md 24-summarize.claude.md --_editYour $EDITOR opens with the fully expanded prompt. Make any changes, save, and close. The edited version is then sent to the LLM.
UX Benefit: Last-chance editing for context-sensitive adjustments.
Concept: Rich Terminal Output UX Problem: LLM output with code blocks looks ugly in the terminal. Solution: mdflow now renders markdown with syntax highlighting by default.
Run it:
md explain-code.claude.md # Beautiful syntax-highlighted outputFor piping to other tools, use --raw:
md generate-json.claude.md --raw | jq .UX Benefit: Professional-looking output that's easy to read.
Concept: Frecency-Based File Picker UX Problem: You have many agents and finding the right one takes time. Solution: The interactive picker now sorts by frecency (frequency + recency).
Run it:
md # No arguments - opens the pickerFiles you use often and recently appear at the top. The algorithm uses Mozilla/z-style recency buckets:
- Used in last 4 hours: 4x multiplier
- Used in last 24 hours: 2x multiplier
- Used in last week: 0.5x multiplier
- Older: 0.25x multiplier
UX Benefit: Your most-used agents are always a keystroke away.