mdflow: Executable Markdown for AI Agents

mdflow transforms markdown files into executable AI agent commands. Your markdown files become runnable scripts that route to Claude, Gemini, Codex, or GitHub Copilot based on filename conventions.

Development Process

In this project, we default to working in the main branch. Don't create a new branch or switch to a different branch unless explicitly instructed. If you are already on a topic branch other than main, continue working in this topic branch until instructed otherwise.
Whenever you are done working, commit your changes. Never wait to be asked to commit. In steady state, things are always committed.

Documentation Links

mdflow Website: https://mdflow.dev/
mdflow GitHub: https://github.com/johnlindquist/mdflow
Claude Code CLI Reference: https://code.claude.com/docs/en/cli-reference
Codex CLI Reference: https://developers.openai.com/codex/cli/reference/
Gemini CLI GitHub: https://github.com/google-gemini/gemini-cli
GitHub Copilot CLI: https://github.com/github/copilot-cli

Agent File Location

All new mdflow agents (runnable markdown files) should be created in the agents/ directory.

Basic Structure

# filename.COMMAND.md
---
frontmatter: options
model: opus
---
Your prompt text here

Filename-Based Command Resolution

The AI provider is inferred from the filename:

Filename Pattern	Provider
`task.claude.md`	Claude Code
`task.gemini.md`	Gemini CLI
`task.codex.md`	OpenAI Codex
`task.copilot.md`	GitHub Copilot

Interactive Mode

Add .i. to the filename for interactive sessions:

task.i.claude.md - Interactive Claude session
refactor.i.gemini.md - Interactive Gemini session

Frontmatter Reference

YAML frontmatter converts directly to CLI flags. Keys become --key value arguments.

System Keys (Handled by mdflow)

Key	Description
`_varname`	Template variable with default value
`_interactive` / `_i`	Enable interactive mode
`_subcommand`	Prepend subcommands to the CLI call
`_cwd`	Override working directory
`env`	Set environment variables

Auto-Injected Variables

Variable	Description
`{{ _stdin }}`	Content piped into mdflow
`{{ _1 }}`, `{{ _2 }}`	Positional CLI arguments
`{{ _args }}`	All arguments as a numbered list

Provider-Specific Frontmatter

All other keys become CLI flags for the target provider:

model: opus           # becomes --model opus
json: true            # becomes --json
add-dir: [./src]      # becomes --add-dir ./src

Content Inclusion Syntax

File Imports

@./path/file.ts                    # Include entire file
@./path/file.ts#FunctionName       # Extract specific symbol
@./path/file.ts:10-50              # Specific line range
@./src/**/*.ts                     # Glob pattern (respects .gitignore)
@https://example.com/file.md       # Remote URL (cached 1 hour)

Inline Command Execution

!`git log --oneline -5`            # Execute and inline shell output
!`date`                            # Current date/time

Templating (LiquidJS)

{{ _varname }}                     # Variable interpolation
{% if condition %} ... {% endif %} # Conditional blocks

Usage Examples

Basic Execution

mdflow task.claude.md
mdflow review.gemini.md "argument"
mdflow commit.codex.md

Override Command

mdflow task.md --command claude
mdflow task.md -c gemini

Piping Input

git diff | mdflow review.claude.md
cat README.md | mdflow summarize.gemini.md

Template Variables

mdflow create.claude.md --_feature_name "Auth" --_target_dir "src/billing"

Dry Run (Preview)

mdflow task.claude.md --dry-run    # Shows token estimates, no API call

Example Markdown Files

Code Review with Claude

# review.claude.md
---
model: opus
---
Review this code for bugs and security issues.

@./src/**/*.ts

Interactive Gemini Refactoring

# refactor.i.gemini.md
---
yolo: true
model: gemini-2.5-pro
---
Refactor the authentication module for better testability.

@./src/auth/**/*.ts

Commit Message Generator

# commit.codex.md
---
model: gpt-5-codex
---
Generate a concise commit message for these changes:

!`git diff --staged`

Copilot Code Explanation

# explain.copilot.md
---
model: claude-sonnet-4-5
---
Explain this function in detail:

@./src/utils.ts#parseConfig

Global Configuration

Create ~/.mdflow/config.yaml for default settings:

commands:
  claude:
    model: sonnet
  copilot:
    silent: true
  gemini:
    model: gemini-2.5-pro
  codex:
    sandbox: workspace-write

CLI Parameters Reference

Claude Code CLI

Documentation: https://code.claude.com/docs/en/cli-reference

Core Flags

Flag	Description
`--model`	Model selection: `sonnet`, `opus`, or full model name
`--print`, `-p`	Print response without interactive mode
`--continue`, `-c`	Continue most recent conversation
`--resume`, `-r`	Resume specific session by ID
`--max-turns`	Limit agentic turns in non-interactive mode
`--output-format`	Output format: `text`, `json`, `stream-json`
`--json-schema`	Get validated JSON output matching schema

Directory & Context

Flag	Description
`--add-dir`	Add additional working directories
`--allowedTools`	Tools allowed without prompting
`--disallowedTools`	Tools to disallow
`--tools`	Specify available tools

System Prompt

Flag	Description
`--system-prompt`	Replace entire system prompt
`--system-prompt-file`	Load system prompt from file
`--append-system-prompt`	Append to default system prompt

Permissions & Safety

Flag	Description
`--dangerously-skip-permissions`	Skip permission prompts
`--permission-mode`	Begin in specified permission mode

MCP & Agents

Flag	Description
`--mcp-config`	Load MCP servers from JSON file
`--agents`	Define custom subagents via JSON
`--agent`	Specify an agent for the session

OpenAI Codex CLI

Documentation: https://developers.openai.com/codex/cli/reference/

Core Flags

Flag	Description
`--model`, `-m`	Override the model (e.g., `gpt-5-codex`)
`--image`, `-i`	Attach image files to initial prompt
`--profile`, `-p`	Load configuration profile
`--cd`, `-C`	Set working directory
`--config`, `-c`	Override configuration values

Sandbox & Permissions

Flag	Description
`--sandbox`, `-s`	Sandbox mode: `read-only`, `workspace-write`, `danger-full-access`
`--ask-for-approval`, `-a`	When to pause: `untrusted`, `on-failure`, `on-request`, `never`
`--full-auto`	Unattended mode: approval on-failure + workspace-write
`--yolo`	Bypass all approvals and sandboxing

Directory Access

Flag	Description
`--add-dir`	Grant additional directories write access
`--search`	Enable web search capability

Features

Flag	Description
`--enable`	Force-enable a feature flag
`--disable`	Force-disable a feature flag
`--oss`	Use local open source model (requires Ollama)

Subcommands

Command	Description
`codex exec`	Non-interactive execution
`codex resume`	Continue previous session
`codex auth`	Authentication
`codex apply`	Apply diffs from Codex Cloud

Google Gemini CLI

Documentation: https://github.com/google-gemini/gemini-cli

Core Flags

Flag	Description
`--model`, `-m`	Gemini model: `gemini-2.5-pro`, `gemini-2.5-flash`
`--prompt`, `-p`	Non-interactive single prompt
`--prompt-interactive`, `-i`	Interactive session with initial prompt
`--output-format`	Output: `json`, `stream-json`

Context & Files

Flag	Description
`--include-directories`	Include additional directories (max 5)
`--all-files`, `-a`	Recursively include all files as context

Safety & Execution

Flag	Description
`--sandbox`, `-s`	Enable sandbox mode
`--sandbox-image`	Set sandbox container image
`--yolo`	Auto-approve all tool calls

Extensions & Debug

Flag	Description
`--extensions`, `-e`	Specify extensions to use
`--list-extensions`, `-l`	List available extensions
`--debug`, `-d`	Enable verbose debug output
`--show-memory-usage`	Display memory usage

Environment Variables

Variable	Description
`GEMINI_API_KEY`	API key (required)
`GEMINI_MODEL`	Default model
`GEMINI_SANDBOX`	Sandbox setting
`GOOGLE_CLOUD_PROJECT`	GCP project ID

GitHub Copilot CLI

Documentation: https://github.com/github/copilot-cli

Core Flags

Flag	Description
`--prompt`, `-p`	Pass single prompt directly
`--banner`	Show animated splash screen
`--resume`	Resume previous session
`--continue`	Continue from last session

Tool Permissions

Flag	Description
`--allow-all-tools`	Allow all tools without approval
`--allow-tool`	Allow specific tool (supports globs)
`--deny-tool`	Deny specific tool

Tool Specification Patterns

--allow-tool 'shell(npm run test:*)'   # Allow test scripts
--deny-tool 'shell(rm)'                 # Deny rm commands
--allow-tool 'write'                    # Allow file modifications
--allow-tool 'My-MCP-Server(tool)'      # Allow MCP server tool

Slash Commands (Interactive)

Command	Description
`/model`	Switch between models (Claude Sonnet 4.5, GPT-5, etc.)
`/login`	Authenticate with GitHub
`/mcp`	List configured MCP servers
`/feedback`	Submit feedback

mdflow-Specific CLI Flags

Flag	Description
`--command`, `-c`	Override inferred provider
`--_varname`	Set template variable value
`--dry-run`	Preview without API call
`--no-cache`	Force fresh remote URL fetch
`--trust`	Bypass TOFU prompts

Tips for Writing mdflow Markdown

Use descriptive filenames: review-pr.claude.md is clearer than task.claude.md
Leverage globs for context: @./src/**/*.ts includes all TypeScript files
Extract symbols for precision: @./api.ts#handleRequest targets specific functions

Use template variables for reusability:

---
_target: ./src
---
Analyze files in {{ _target }}

Combine piping with files:
```
git diff | mdflow review.claude.md
```
Set sensible defaults in config.yaml to avoid repetitive frontmatter
Use dry-run to estimate token usage before expensive operations

Add shebang for direct execution:

#!/usr/bin/env mdflow
---
model: opus
---

intellectronica/0.README.md

mdflow: Executable Markdown for AI Agents

Development Process

Documentation Links

Agent File Location

Basic Structure

Filename-Based Command Resolution

Interactive Mode

Frontmatter Reference

System Keys (Handled by mdflow)

Auto-Injected Variables

Provider-Specific Frontmatter

Content Inclusion Syntax

File Imports

Inline Command Execution

Templating (LiquidJS)

Usage Examples

Basic Execution

Override Command

Piping Input

Template Variables

Dry Run (Preview)

Example Markdown Files

Code Review with Claude

Interactive Gemini Refactoring

Commit Message Generator

Copilot Code Explanation

Global Configuration

CLI Parameters Reference

Claude Code CLI

Core Flags

Directory & Context

System Prompt

Permissions & Safety

MCP & Agents

OpenAI Codex CLI

Core Flags

Sandbox & Permissions

Directory Access

Features

Subcommands

Google Gemini CLI

Core Flags

Context & Files

Safety & Execution

Extensions & Debug

Environment Variables

GitHub Copilot CLI

Core Flags

Tool Permissions

Tool Specification Patterns

Slash Commands (Interactive)

mdflow-Specific CLI Flags

Tips for Writing mdflow Markdown