MDFlow transforms markdown files into executable CLI agents for interacting with large language models like Claude, Codex, Gemini, and Copilot. It targets developers and power users seeking to integrate LLM capabilities directly into their command-line workflows, offering a streamlined way to run complex prompts, pipe data between agents, and automate AI-driven tasks.

How It Works

MDFlow leverages a simple yet powerful convention: markdown filenames dictate the command (e.g., task.claude.md executes the claude CLI). YAML frontmatter is parsed into command-line flags, while the markdown body serves as the prompt. This approach aligns with the Unix philosophy, enabling composability through standard input/output piping and transparent execution logging.

Quick Start & Requirements

• Installation: npm install -g mdflow or bun install && bun link.
• Prerequisites: Node.js or Bun runtime. Requires underlying LLM CLIs (e.g., claude, gemini) to be installed and configured separately.
• Links: mdflow setup command for shell integration.

Highlighted Details

• Dynamic Prompts: LiquidJS-based templating allows dynamic prompt generation using frontmatter variables (_varname), CLI flags (--_varname), piped input ({{ _stdin }}), and positional arguments ({{ _1 }}).
• Content Imports: Inline content from local files (@./path), glob patterns (@./src/**/*.ts), specific line ranges (@file:line-range), TypeScript/JavaScript symbols (@file#Symbol), URLs (@http...), and shell command output (!command).
• Interactive Mode: Supports interactive LLM sessions via .i. filename suffixes, _interactive frontmatter, or --_interactive CLI flags.
• Rich Output: LLM output is rendered with syntax highlighting and markdown structure using marked-terminal.
• Agent Inspection: The md explain command previews the resolved command, flags, prompt, and context without execution.
• Environment Management: Integrates with .env files and supports _env frontmatter for setting environment variables.
• Caching: Remote URL imports are cached locally with a configurable TTL.

Maintenance & Community

No specific details on maintainers, community channels, or project health signals were found in the provided documentation.

Licensing & Compatibility

The license type and any compatibility notes for commercial use or closed-source linking are not specified in the provided documentation.

Limitations & Caveats

The project relies on external LLM CLIs being installed and configured. URL imports are limited to markdown and JSON formats. The absence of explicit licensing information presents a significant adoption blocker.