# mdflow

```bash
review.md                        # Runs on your resolved engine (default: pi)
review.claude.md                 # Pin an engine in the filename
git diff | explain.md            # Pipe through any command
```

**A Git-native control plane for repeatable agent work.** Define each job as
markdown, run it on the CLI engine you already use, inspect its inputs, and
gate prompt revisions with behavioral evals.

```bash
npx mdflow init
```

One command safely creates a starter `./flows` roster and `.mdflow.yaml` with
zero engine invocations; repeat runs leave an existing roster untouched. Then
bare `md` always opens one searchable Flow Workbench containing project flows,
every globally installed flow, and runnable Markdown flows found directly on
`PATH`, with clear `PROJECT`, `GLOBAL`, `INSTALLED`, and `PATH` provenance. If
the project has no owned roster, global and PATH flows remain
immediately runnable and a searchable **Set up project flows…** row opens guided
setup, a deterministic starter roster, or the printable setup guide without
leaving the Workbench. Want the repo-tailored setup conversation directly? Run
`md init --guided` (or `md init --print-guide` to copy the same guide into
your own agent session).

Prefer flows as the primary way agents work in your repo? Opt in with
`md roster sync --agents`: it maintains one marker-managed mdflow block in
`AGENTS.md` and `CLAUDE.md` so coding agents discover the roster and hand
matching tasks off to flows, and it never touches your text outside the
markers. Every guidance write requires that explicit `--agents` consent —
plain `md roster sync` is README-only and merely reports drift. Guided setup
asks this as an explicit question.

## For coding agents

Use the CLI as the source of truth instead of reconstructing project state from
long prose:

```bash
command -v md || npm install -g mdflow
md doctor --json                 # FREE, static, read-only project diagnosis
npx mdflow init --yes            # LOCAL WRITE, deterministic starter roster
md doctor --json
md explain flows/<name>.md --json
md eval flows/<name>.md --plan   # FREE; a real eval needs separate approval
```

`flows/README.md` contains a managed operator card; update only that marked
block with `md roster sync`. Eval and hook sidecars are executable local code.
Registry install adds one flow, not trusted sidecars. Engine context isolation
is not a host filesystem, network, process, environment, or credential sandbox.

---

## The agent control plane in your repo

**Git-native agent workflows.** One file per job. Any engine. Evals that
guard declared behavior. Feedback can drive reviewable, regression-gated prompt proposals.

- **`./flows` is your repo's agent roster.** One markdown agent per job:
  code review, release notes, issue triage. Diffable in PRs, checked with
  `md eval`, readable by every teammate, human or AI. Start one with
  `npx mdflow init`; the installable skill
  (`npx skills add johnlindquist/mdflow`) teaches your coding agent to build
  and maintain it.
- **Engines are environment, not filename ceremony.** Bare `review.md` runs
  on the resolved engine: `--engine` flag > `MDFLOW_ENGINE` env > filename >
  frontmatter `engine:` > config `engine:` > built-in default (**pi**).
  Implicit choices print a dim `review.md → pi (engine: default)` line.
  Inspectable, never magic. Files with no frontmatter and no explicit engine
  are documents: `md README.md` prints instead of executing. The frontmatter
  key is now `engine:` (`tool:`/`_tool:` still work, with a warning).
- **pi is the default engine**, runs without ambient extensions, skills, or
  context files, and bridges your Codex CLI login automatically.
- **Engine context isolation is the default, where supported.** Flows run with the
  engine's ambient context stripped using its own verified flags — claude
  `--safe-mode --no-session-persistence`, codex `--ignore-user-config
  --ephemeral --skip-git-repo-check -c project_doc_max_bytes=0`, gemini `--extensions none`,
  copilot `--no-custom-instructions --disable-builtin-mcps`, opencode
  `--pure`, pi its context-isolation flags. Skills/MCP/context a flow needs are
  declared explicitly in frontmatter; `_isolated: false` opts back into
  ambient. Engines with no controls (droid, cursor-agent, agy) run ambient
  and warn only on an explicit `_isolated: true` — never pretending. This
  does not sandbox the host filesystem, network, environment, or inline shell
  commands; those remain explicit capabilities of the flow.
- **System prompt as a first-class key:** `_system-prompt:` replaces the
  engine's system prompt, `_append-system-prompt:` appends (string or list).
  Translated per engine (claude/pi flags, codex `model_instructions_file` /
  `developer_instructions` config, gemini `GEMINI_SYSTEM_MD`). Engines with
  no mechanism fail the run instead of silently dropping your prompt.
  Interactive specialists that should wait for a task use `_task: ""` and a
  body of exactly `{{ _task }}`; identity/rules belong in the two instruction
  keys. Static `User task:` wrappers or body-level context would become an
  immediately submitted first turn.
- **New engines:** `cursor-agent` and `agy` (Google Antigravity, the gemini
  CLI successor; the old gemini adapter remains for Code Assist
  Standard/Enterprise).
- **Evals:** `md eval flows/review.md` runs `flows/review.eval.ts`.
  Behavioral cases in isolated temporary workspaces, cost printed before running,
  results in a trust ledger. *If a guardrail isn't covered by an eval, it's
  a wish.*
- **Evolution is proposal-first:** `md feedback flows/review.md "missed the
  race condition"` records durable evidence. `md evolve plan` previews proof,
  capabilities, writes, and bounded invocation cost for free; `md evolve
  propose` drafts and evaluates private off-path snapshots. The source stays
  byte-identical until a separate `md evolve apply <run-id>`. mdflow says
  “verified improvement” only when a feedback-linked case fails on current and
  passes on the proposal; otherwise a green candidate is merely
  “regression-safe.” Legacy `evolve: auto` now means queued proposal-only work,
  never unattended application.

See [`docs/evolve.md`](docs/evolve.md) for the normative change-with-proof
protocol, `docs/V3-FLOWS.md` for the historical v3 design record, [`docs/public-api.md`](docs/public-api.md) for the
stable CLI contract, and [`GUIDE-NEW-FEATURES.md`](GUIDE-NEW-FEATURES.md) for
workflows (`_steps`), structured outputs (`_output`), context providers
(`@git:diff`), the flow registry, `--json` mode, and run telemetry.

Security-sensitive behavior is documented in [`SECURITY.md`](SECURITY.md).
Contributions are welcome; see [`CONTRIBUTING.md`](CONTRIBUTING.md).

---

## What Is This?

Markdown files become first-class CLI commands. Write a prompt in markdown, run it like a script. The command is inferred from the filename.

```markdown
# review.claude.md
---
model: opus
---
Review this code for bugs and suggest improvements.

@./src/**/*.ts
```

```bash
review.claude.md                 # Runs: claude --model opus <prompt>
review.claude.md --verbose       # Pass extra flags
```

---

## How It Works

### 1. Filename → Command

Name your file `task.COMMAND.md` and the command is inferred:

```bash
task.claude.md    # Runs claude
task.codex.md     # Runs codex
task.copilot.md   # Runs copilot (print mode by default)
task.agy.md       # Runs agy (Google Antigravity, the gemini CLI successor)
task.gemini.md    # Runs gemini (Code Assist Standard/Enterprise only — sunset for individuals)
```

### 2. Frontmatter → CLI Flags

Every YAML key becomes a CLI flag passed to the command:

```yaml
---
model: opus              # → --model opus
dangerously-skip-permissions: true  # → --dangerously-skip-permissions
mcp-config: ./mcp.json   # → --mcp-config ./mcp.json
add-dir:                 # → --add-dir ./src --add-dir ./tests
  - ./src
  - ./tests
---
```

### 3. Body → Prompt

The markdown body is passed as the final argument to the command.

---

## Unix Philosophy

mdflow embraces the Unix philosophy:

- **No magic mapping** - Frontmatter keys pass directly to the command
- **Stdin/stdout** - Pipe data in and out
- **Composable** - Chain agents together
- **Transparent** - See what runs in logs

```bash
# Pipe input
git diff | mdflow review.claude.md

# Chain agents
mdflow plan.claude.md | mdflow implement.codex.md
```

---

## Installation

Start through `npx` to bootstrap a flow roster in any repo:

```bash
npx mdflow init
```

Keep it installed for daily runs:

```bash
npm install -g mdflow
# or
bun install && bun link
```

mdflow runs on [Bun](https://bun.sh). If Bun is missing, the interactive
launcher offers to install it; non-interactive environments must install Bun
first.

## Quick Start

```bash
# Safely scaffold a starter roster (`--guided` for a repo-tailored session)
npx mdflow init

# Open the Flow Workbench
md

# Or create and run a project flow directly
md create "Review staged changes for bugs"
md review-staged-changes-for-bugs

# Create a personal flow you can run from any project
md create "Turn meeting notes into an action plan" --global
md turn-meeting-notes-into-an-action-plan

# Preview without spending an engine invocation
md review-staged-changes-for-bugs --_dry-run

# Override the engine explicitly
mdflow task.md --engine claude
MDFLOW_ENGINE=codex mdflow task.md

# One-shot ad-hoc mode (no file required)
md.claude "Summarize: !`git diff --staged`"
md.i.codex "Help me debug this test failure"

# Pass additional flags to the command
mdflow task.claude.md --verbose --debug
```

> **Note:** Both `mdflow` and `md` commands are available.
>
> For the full command and frontmatter contract, see [`docs/public-api.md`](docs/public-api.md).

### The Flow Workbench

Run bare `md` for the everyday surface. It works in a new project with zero
flows and in an established project with a full roster:

- Search project, global, installed, and PATH flows together; every row shows its provenance.
- Press `Enter` to run or `Tab`/`→` to open dry-run, edit, hooks, feedback, and evolution actions.
- Press `Ctrl+O` to turn a plain-language outcome into a new scoped flow.
- In a project with no local roster, search for `setup` or select **Set up project flows…**.

Every action displays its exact shell equivalent and whether it is free,
invokes an engine, or writes locally. The Workbench never auto-applies a prompt
revision. `a` and `r` open a dedicated `LOCAL WRITE` confirmation screen;
`Enter`/`c` confirms the displayed command and `Esc` returns without writing.

---

## Engine Resolution

Engines are resolved by a ladder, most explicit first:

1. **CLI flag**: `--engine claude` (deprecated aliases: `--_command`/`-_c`, `--tool`)
2. **Environment variable**: `MDFLOW_ENGINE`
3. **Filename pattern**: `task.claude.md` → `claude` (must name a real engine)
4. **Frontmatter**: `engine: claude` (deprecated aliases `tool:`/`_tool:` warn)
5. **Config** `engine:` (project config beats `~/.mdflow/config.yaml`)
6. **Built-in default**: `pi`

Resolution never fails — the default always applies. Implicit choices print a
dim explanation line on stderr. A file with no frontmatter and no explicit
engine is a document: `md README.md` prints it instead of executing it.

Bundled engines: `claude`, `codex`, `copilot`, `gemini`, `droid`, `opencode`,
`pi` (default), `cursor-agent`, `agy` (Google Antigravity).

---

## Flag Hijacking

Some CLI flags are "hijacked" by mdflow: they're consumed and never passed to the underlying command. This allows generic markdown files without command names to be executed.

### `--engine`

Override the engine for any markdown file (deprecated aliases: `--_command`,
`-_c`, `--tool` — they still work but warn):

```bash
# Run a generic .md file on any engine
mdflow task.md --engine claude

# Override the filename-inferred engine
mdflow task.claude.md --engine gemini  # Runs gemini, not claude
```

### `_varname` Template Variables

Frontmatter fields starting with `_` (except internal keys like `_interactive`, `_cwd`, `_subcommand`) define template variables:

```yaml
---
_feature_name: Authentication   # Default value
_target_dir: src/features       # Default value
---
Build {{ _feature_name }} in {{ _target_dir }}.
```

```bash
# Use defaults
mdflow create.claude.md

# Override with CLI flags (consumed by mdflow, not passed to command)
mdflow create.claude.md --_feature_name "Payments" --_target_dir "src/billing"
```

The `--_feature_name` and `--_target_dir` flags are consumed by mdflow for template substitution. They won't be passed to the command.

**No frontmatter declaration required:** You can pass `--_varname` flags without declaring them in frontmatter. If the variable is used in the body but not provided, you'll be prompted for it:

```yaml
---
print: true
---
{% if _verbose == "yes" %}Detailed analysis:{% endif %}
Review this code: {{ _target }}
```

```bash
mdflow review.claude.md --_verbose yes --_target "./src"
```

### Positional Arguments as Template Variables

CLI positional arguments are available as `{{ _1 }}`, `{{ _2 }}`, etc.:

```yaml
---
print: true
---
Translate "{{ _1 }}" to {{ _2 }}.
```

```bash
mdflow translate.claude.md "hello world" "French"
# → Translate "hello world" to French.
```

Use `{{ _args }}` to get all positional args as a numbered list:

```yaml
---
print: true
---
Process these items:
{{ _args }}
```

```bash
mdflow process.claude.md "apple" "banana" "cherry"
# → Process these items:
# → 1. apple
# → 2. banana
# → 3. cherry
```

### `_stdin` - Piped Input

When you pipe content to mdflow, it's available as the `_stdin` template variable:

```yaml
---
model: haiku
---
Summarize this: {{ _stdin }}
```

```bash
cat README.md | md summarize.claude.md
```

### Interactive Form Inputs

Use `_inputs` to define typed interactive prompts with validation:

```yaml
---
model: sonnet
_inputs:
  _name:
    type: text
    description: "Enter your name"
    default: "World"
  _env:
    type: select
    options: [dev, staging, prod]
  _count:
    type: number
    description: "How many items?"
  _confirm:
    type: confirm
    description: "Are you sure?"
  _secret:
    type: password
    description: "API key"
---
Hello {{ _name }}! Deploying to {{ _env }} with {{ _count }} items.
```

**Input types:**

- `text` - Free text input (default if no type specified)
- `select` - Choose from a list of options
- `number` - Numeric input
- `confirm` - Yes/no boolean
- `password` - Hidden input for secrets

**Legacy format:** `_inputs: [_name, _value]` (array of variable names) still works.

---

## Frontmatter Reference

### System Keys (handled by md)

| Field | Type | Description |
| ------- | ------ | ------------- |
| `_varname` | string | Template variable with default value (use `{{ _varname }}` in body) |
| `_inputs` | object/array | Interactive form inputs (see above) |
| `_env` | object | Set process environment variables |
| `$1`, `$2`... | string | Map positional args to flags (e.g., `$1: prompt`) |
| `_interactive` / `_i` | boolean | Enable interactive mode (overrides print-mode defaults) |
| `_subcommand` | string/string[] | Prepend subcommand(s) to CLI args |
| `_cwd` | string | Override working directory for inline commands |
| `_hooks` | boolean/string | Lifecycle hooks file: unset = auto-discover `<flow>.hooks.ts`, `false` = disable, path = shared hooks file (see Lifecycle Hooks) |
| `context_window` | number | Override token limit for context (default: model-based) |

### Auto-Injected Template Variables

| Variable | Description |
| ---------- | ------------- |
| `{{ _stdin }}` | Content piped to mdflow |
| `{{ _1 }}`, `{{ _2 }}`... | Positional CLI arguments |
| `{{ _args }}` | All positional args as numbered list (1. arg1, 2. arg2, ...) |

### All Other Keys → CLI Flags

Every other frontmatter key is passed directly to the command:

```yaml
---
model: opus                           # → --model opus
dangerously-skip-permissions: true    # → --dangerously-skip-permissions
mcp-config: ./mcp.json                # → --mcp-config ./mcp.json
p: true                               # → -p (single char = short flag)
---
```

**Value conversion:**

- `key: "value"` → `--key value`
- `key: true` → `--key`
- `key: false` → (omitted)
- `key: [a, b]` → `--key a --key b`

---

## Lifecycle Hooks

A flow's hooks live in a TypeScript file **named after the flow** — that's
the whole wiring:

```
review.codex.md          # the flow
review.codex.hooks.ts    # its hooks — discovered and wired automatically
```

Scaffold one (or pick events interactively by omitting them):

```bash
md hooks add review.codex.md stop userPromptSubmit
md hooks list review.codex.md
md hooks remove review.codex.md stop
```

The generated file is an executable, dependency-free Bun program exporting
handlers keyed by canonical event names:

```ts
#!/usr/bin/env bun
const handlers: Record<string, HookHandler> = {
  userPromptSubmit: async (payload) => {
    // return a string to inject context;
    // return { decision: "block", reason: "…" } to reject the prompt
  },
  stop: async (payload) => {
    // return { decision: "block", reason: "…" } to force the turn to continue
  },
};
```

On every run, mdflow reads which events the file handles (from its text —
inspection never executes it) and translates them into the engine's native
hook mechanism. **codex** and **claude** are supported today (the same hooks
file works unchanged on both — its dispatcher normalizes event names):

- **codex** — an inline `-c hooks={…}` override plus a prepared, hooks-free
  codex home under `~/.mdflow/`, so your own codex config and credentials
  are never modified.
- **claude** — an inline `--settings` blob plus `--setting-sources ""` to
  exclude your ambient settings hooks. Claude's `--safe-mode` disables
  injected hooks, so a hooked claude run drops it and prints a one-line
  disclosure that CLAUDE.md/skills/plugins/MCP are no longer isolated for
  that run (your ambient settings hooks still are).
Debug a hook standalone by piping a payload to it:

```bash
echo '{"hook_event_name":"Stop"}' | ./review.codex.hooks.ts
```

Events: `sessionStart`, `userPromptSubmit`, `preToolUse`, `postToolUse`,
`permissionRequest`, `preCompact`, `postCompact`, `subagentStart`,
`subagentStop`, `stop`, `sessionEnd`. In print mode, codex fires
`sessionStart`/`userPromptSubmit`/`preToolUse`/`postToolUse`/`stop`, and
claude additionally fires `sessionEnd`; the rest are registered but
scenario-dependent. Once a run is underway, a hook that crashes or times out
fails open (the engine continues) — except that the scaffolded dispatcher
fails **closed** for guard events (`userPromptSubmit`, `preToolUse`,
`permissionRequest`): if one of those handlers throws, mdflow emits the
engine's block/deny response rather than letting the guarded action through.
Discovery problems are the opposite: a hooks file that exists but can't be
used (missing, uninspectable, escaping path) fails the run loudly, because
silently dropping declared hooks would change the flow.

Consent and containment rules:

- **Inspection never executes.** `md explain`, `md hooks list`, dry runs,
  and the Workbench read the handlers map from the file's text; only a real
  run may execute the hook program (it's about to run anyway).
- **Hooks run isolated.** Hooked runs exclude your ambient hooks so mdflow's
  injected hooks are the only ones that fire — on codex via a prepared,
  hooks-free codex home (its trust bypass can never enable hooks you haven't
  reviewed), on claude via `--setting-sources ""`. `_isolated: false`
  combined with a hooks file is an error on both.
- **Paths are contained.** A flow's `_hooks:` may only point inside the
  flow's own directory, and remote flows can't declare `_hooks` paths at
  all. Only `--_hooks` typed on the command line escapes containment.
- **`md install` fetches only the flow markdown** — hook files are never
  downloaded from a registry.

Control: `_hooks: false` disables discovery; `_hooks: ./shared.hooks.ts`
points several flows at one file (within the flow's directory);
`--_hooks <path|false>` overrides from the CLI. Engines without a verified
hook mechanism fail a run whose hooks file exists — disable with
`_hooks: false` or switch engines.

---

## Print vs Interactive Mode

All commands run in **print mode by default** (non-interactive, exit after completion). Use the `.i.` filename marker, `_interactive` frontmatter, or CLI flags to enable interactive mode.

### Print Mode (Default)

```bash
task.claude.md      # Runs: claude --print "..."
task.copilot.md     # Runs: copilot --silent --prompt "..."
task.codex.md       # Runs: codex exec "..."
task.gemini.md      # Runs: gemini "..." (one-shot)
```

### Interactive Mode

Add `.i.` before the command name in the filename:

```bash
task.i.claude.md    # Runs: claude "..." (interactive session)
task.i.copilot.md   # Runs: copilot --silent --interactive "..."
task.i.codex.md     # Runs: codex "..." (interactive session)
task.i.gemini.md    # Runs: gemini --prompt-interactive "..."
chat.i.md           # Default engine, interactive ("i" is never an engine name)
```

Or use `_interactive` (or `_i`) in frontmatter:

```yaml
---
_interactive: true   # or _interactive: (empty), or _i:
model: opus
---
Review this code with me interactively.
```

Or use CLI flags:

```bash
mdflow task.claude.md --_interactive  # Enable interactive mode
mdflow task.claude.md -_i             # Short form
```

---

## Configuration Layers

mdflow resolves configuration in this order (later entries override earlier ones):

1. Built-in command defaults
2. Global config (`~/.mdflow/config.yaml`)
3. Project config at git root (`mdflow.config.yaml`, `.mdflow.yaml`, `.mdflow.json`)
4. Project config at current working directory (`mdflow.config.yaml`, `.mdflow.yaml`, `.mdflow.json`)
5. Agent frontmatter
6. CLI passthrough flags

Set global defaults per command in `~/.mdflow/config.yaml`:

```yaml
commands:
  claude:
    model: sonnet # Default model for claude
  copilot:
    silent: true  # Always use --silent for copilot
```

Set project defaults in your repository root:

```yaml
# mdflow.config.yaml
commands:
  claude:
    model: opus
```

**Built-in defaults:** All commands default to print mode with tool-specific defaults.

---

## Examples

### Claude with MCP Server

```markdown
# db.claude.md
---
model: opus
mcp-config: ./postgres-mcp.json
dangerously-skip-permissions: true
---
Analyze the database schema and suggest optimizations.
```

### Gemini YOLO Mode

```markdown
# refactor.gemini.md
---
model: gemini-3-pro-preview
yolo: true
---
Refactor the authentication module to use async/await.
```

### Codex with Sandbox

```markdown
# analyze.codex.md
---
model: o3
sandbox: workspace-write
full-auto: true
---
Analyze this codebase and suggest improvements.
```

### Copilot (no frontmatter needed!)

```markdown
# task.copilot.md
Explain this code.
```

This runs: `copilot --silent --prompt "Explain this code."` (print mode)

For interactive mode, use `.i.` in the filename:

```markdown
# task.i.copilot.md
Explain this code.
```

This runs: `copilot --silent --interactive "Explain this code."`

### Template Variables

```markdown
# create-feature.claude.md
---
_feature_name: ""
_target_dir: src/features
model: sonnet
---
Create a new feature called "{{ _feature_name }}" in {{ _target_dir }}.
```

```bash
mdflow create-feature.claude.md --_feature_name "Auth"
```

### Environment Variables

Use `_env` (underscore prefix) to set environment variables for the command:

```markdown
# api-test.claude.md
---
_env:
  API_URL: https://api.example.com
  DEBUG: "true"
---
Test the API at !`echo $API_URL`
```

---

## Imports & Command Inlines

Inline content from other files or command output directly in your prompts.

### File Imports

Use `@` followed by a path to inline file contents:

```markdown
---
model: claude
---
Follow these coding standards:
@./docs/coding-standards.md

Now review this code:
@./src/api.ts
```

- `@~/path` - Expands `~` to home directory
- `@./path` - Relative to current markdown file
- `@/path` - Absolute path

Paths (including symlinks) must resolve inside the import root, normally the invocation directory. A directly imported file can contain nested `@` context references. Its text is data: shell markers, shebang fences and Liquid expressions inside it are not executed. Declare commands and Liquid control flow in the flow itself. The same data rule applies to URL content, provider output and values supplied on stdin or the command line.

If you intentionally interpolate a value *into an authored shell command*, you are still constructing a shell program. On POSIX shells, pass each external argument through the `q` filter as a standalone word; do not add another layer of quotes.

### Glob Imports

Use glob patterns to include multiple files at once:

```markdown
Review all TypeScript files in src:
@./src/**/*.ts
```

Glob imports:

- Respect `.gitignore` automatically
- Include common exclusions (`node_modules`, `.git`, etc.)
- Are limited to ~100,000 tokens by default
- Set `MDFLOW_FORCE_CONTEXT=1` to override the token limit

Files are formatted as XML with path attributes:

```xml
<api path="src/api.ts">
...file content...
</api>

<utils path="src/utils.ts">
...file content...
</utils>
```

### Line Range Imports

Extract specific lines from a file:

```markdown
@./src/api.ts:10-50
```

This imports only lines 10-50 from the file.

### Symbol Extraction

Extract specific TypeScript/JavaScript symbols (interfaces, types, functions, classes, etc.):

```markdown
@./src/types.ts#UserInterface
@./src/api.ts#fetchUser
```

Supported symbols:

- `interface Name { ... }`
- `type Name = ...`
- `function Name(...) { ... }`
- `class Name { ... }`
- `const/let/var Name = ...`
- `enum Name { ... }`

### Command Inlines

Use `` !`command` `` to execute a shell command and inline its output:

```markdown
Current branch: !`git branch --show-current`
Recent commits:
!`git log --oneline -5`

Based on the above, suggest what to work on next.
```

> **Security:** template variables are substituted into the command string
> **unescaped** and run via your shell, just like a shell script. When a
> variable can carry untrusted input — piped `{{ _stdin }}`, positional
> `{{ _1 }}`/`{{ _args }}`, or `--_var` flags — pass it through the
> `shell_escape` filter (alias `q`) so shell metacharacters can't execute:
>
> ```markdown
> Matches: !`grep {{ _1 | q }} server.log`
> ```

### URL Imports

Fetch content from URLs (markdown and JSON only):

```markdown
@https://raw.githubusercontent.com/user/repo/main/README.md
```

**Caching:** Remote URLs are cached locally at `~/.mdflow/cache/` with a 1-hour TTL. Use `--_no-cache` to force a fresh fetch:

```bash
mdflow agent.claude.md --_no-cache
```

**URL policy controls:** Restrict allowed URL imports with environment variables:

```bash
export MDFLOW_IMPORT_URL_ALLOWLIST="raw.githubusercontent.com,docs.example.com"
export MDFLOW_IMPORT_URL_BLOCKLIST="*.internal.example.com"
```

Both variables accept comma-separated or newline-separated host rules.
`MDFLOW_URL_ALLOWLIST` and `MDFLOW_URL_BLOCKLIST` are legacy aliases.

---

## Environment Variables

mdflow automatically loads `.env` files from the markdown file's directory.

### Loading Order

Files are loaded in order (later files override earlier):

1. `.env` - Base environment
2. `.env.local` - Local overrides (not committed)
3. `.env.development` / `.env.production` - Environment-specific
4. `.env.development.local` / `.env.production.local` - Environment-specific local

### Example

```
my-agents/
├── .env                    # API_KEY=default
├── .env.local              # API_KEY=my-secret (gitignored)
└── review.claude.md
```

Environment variables are available:

- In command inlines: `` !`echo $API_KEY` ``
- In the spawned command's environment

---

## CLI Options

```
Usage: md <file.md> [flags for the command]
       md                              # Open the Flow Workbench
       md <command> [options]
       md.COMMAND "prompt" [flags]      # Ad-hoc execution (no file needed)

Commands:
  md init [--guided] [-y] [--agents] [--print-guide]
                                Safely scaffold a starter flow roster
                                (--guided tailors it with an installed agent CLI;
                                --agents adds AGENTS.md/CLAUDE.md guidance;
                                --print-guide prints the setup prompt, free)
  md create "<intent>"          Create a project flow (--global for a personal flow)
  md capture                    Print the guide an in-session agent (Claude Code,
                                Codex, ...) follows to capture the current
                                conversation as a flow (free)
  md doctor [--json]            Inspect project readiness + safe next actions (free)
  md explain <agent.md>         Show resolved config without executing
  md render <flow.md>           Render prompt + full config as a shareable HTML page (free)
  md hooks add|list|remove <flow.md> [event…]  Manage the flow's lifecycle hooks file
  md eval <flow.md> [--plan]    Run or cost-preview the flow's eval suite
  md eval add|list|remove|coverage  Scaffold suites, verdicts, and the coverage ratchet
  md feedback <flow.md> "msg"   Record durable evolution evidence (free)
  md complain <flow.md> "msg"   Alias for md feedback
  md evolve plan|propose <flow> Plan for free or create a private proposal
  md evolve show|apply <run-id> Review or explicitly apply a proposal
  md evolve history [flow.md]   List proposal history (use evolve --help for more)
  md install <url|gh:...@ref>   Install a flow into the registry (--global for user scope)
  md remove <name>              Remove an installed registry flow
  md list                       List installed registry flows
  md roster --json              Machine-readable roster of project/global/registry flows
  md roster sync [--check] [--agents]  Update or check the managed operator card
                                (--agents opts into AGENTS.md/CLAUDE.md guidance)
  md setup                      Configure shell (PATH, aliases)
  md logs                       Show agent log directory
  md help                       Show this help

Ad-hoc execution (one-shot mode):
  md.claude "What is 2+2?"                    # Quick prompt to Claude
  md.codex "Write a function"                 # Quick prompt to Codex
  md.copilot "Help me debug"                  # Quick prompt to Copilot
  md.droid "Build an app"                     # Quick prompt to Droid
  md.opencode "Refactor this"                 # Quick prompt to OpenCode
  md.i.claude "Start a chat"                  # Interactive mode
  md.claude "Explain: @error.log" --model opus  # With @imports and flags

Create flows:
  md create "Review staged changes for bugs"               # project: ./flows/
  md create "Turn notes into an action plan" --global       # personal: ~/.mdflow/
  md                              Then browse, run, edit, or improve them

Engine resolution (most explicit wins):
  1. --engine flag (deprecated aliases: --_command/-_c, --tool)
  2. MDFLOW_ENGINE environment variable
  3. Filename pattern (e.g., task.claude.md → claude; must name a real engine)
  4. Frontmatter key (engine: claude; deprecated: tool:/_tool:)
  5. Config engine: (project .mdflow.yaml beats ~/.mdflow/config.yaml)
  6. Built-in default: pi
  A file with no frontmatter and no explicit engine is printed as a document.

Agent file discovery (in priority order):
  1. Explicit path:      md ./path/to/agent.md
  2. Project flows:      ./flows/
  3. Legacy project:     ./.mdflow/
  4. Personal flows:     ~/.mdflow/
  5. $PATH directories
  6. Current directory:  ./

All non-system frontmatter keys are passed as CLI flags to the command.
Global defaults can be set in ~/.mdflow/config.yaml

Remote execution:
  md supports running agents from URLs (npx-style).
  On first use, you'll be prompted to trust the domain.
  Trusted domains are stored in ~/.mdflow/known_hosts

md-specific flags (consumed, not passed to command):
  --engine          Specify the engine to run (deprecated aliases: --_command/-_c, --tool)
  --_dry-run        Show command/prompt plan; skip engine and inline commands
  --_edit           Open resolved prompt in $EDITOR before execution
  --_trust          Skip trust prompt for remote URLs (TOFU bypass)
  --_no-cache       Force fresh fetch for remote URLs (bypass cache)
  --raw             Output raw markdown without rendering (for piping)
  --_context        Show context tree and exit (no execution)
  --_quiet          Skip context dashboard display before execution
  --_no-menu        Disable post-run action menu (for scripting/piping)
  --json            Emit a single JSON result object and disable interactive UI

Examples:
  md task.claude.md -p "print mode"
  md task.claude.md --model opus --verbose
  md commit.agy.md
  md task.md                      # engine via the ladder (default: pi)
  md task.md --engine claude
  md eval task.md                 # run the flow's eval suite
  md task.claude.md --_dry-run    # Preview without executing
  md https://example.com/agent.claude.md            # Remote execution
  md https://example.com/agent.claude.md --_trust   # Skip trust prompt

Without arguments:
  md              Open the Flow Workbench: browse, create, run, and improve flows
```

### Environment Variables

| Variable | Description |
| ---------- | ------------- |
| `MDFLOW_FORCE_CONTEXT` | Set to `1` to disable the 100k token limit for glob imports |
| `MDFLOW_IMPORT_URL_ALLOWLIST` | Comma/newline-separated allowlist rules for URL imports |
| `MDFLOW_IMPORT_URL_BLOCKLIST` | Comma/newline-separated blocklist rules for URL imports |
| `MDFLOW_URL_ALLOWLIST` | Legacy alias for `MDFLOW_IMPORT_URL_ALLOWLIST` |
| `MDFLOW_URL_BLOCKLIST` | Legacy alias for `MDFLOW_IMPORT_URL_BLOCKLIST` |
| `MDFLOW_FETCH_TIMEOUT` | HTTP fetch timeout in milliseconds (default: `10000`) |
| `MDFLOW_COMMAND_TIMEOUT` | Inline command timeout in milliseconds (default: `30000`) |
| `MDFLOW_AGENT_TIMEOUT` | Agent process timeout in milliseconds (default: `0` = disabled) |
| `NODE_ENV` | Controls which `.env.[NODE_ENV]` file is loaded (default: `development`) |

---

## Shell Setup

Make `.md` files directly executable:

```bash
mdflow setup   # One-time setup
```

Then run agents directly:

```bash
task.claude.md                   # Just type the filename
task.claude.md --verbose         # With passthrough args
```

### Manual Setup (zsh)

Add to `~/.zshrc`:

```bash
alias -s md='mdflow'
export PATH="$HOME/agents:$PATH"  # Your agent library
```

---

## Installing Shared Flows

Install versioned flows from a URL or GitHub into the registry:

```bash
md install gh:myorg/agents/code-review.claude.md@v1.2 --project
md install https://example.com/agents/review.claude.md --global  # user scope (~/.mdflow/registry/)
md list                     # list installed flows
md remove review.claude.md  # remove one
```

Each install records its source, requested ref (if supplied), registry-relative path and SHA-256 in `.mdflow/mdflow.lock.json`. A registry run verifies the installed bytes against that lock before it processes the flow. Commit **both** the reviewed flow and its lock to run those same bytes in CI. A URL or branch can change on reinstall; a digest is not a publisher signature. To edit an installed flow, copy it out of the registry first.

---

## Building Your Agent Library

Create a directory of agents and add it to PATH:

```
~/agents/
├── review.claude.md     # Code review
├── commit.gemini.md     # Commit messages
├── explain.claude.md    # Code explainer
├── test.codex.md        # Test generator
└── debug.claude.md      # Debugging helper
```

```bash
export PATH="$HOME/agents:$PATH"
```

Now use them from anywhere:

```bash
review.claude.md                 # Review current directory
commit.gemini.md "add auth"      # Generate commit message
git diff | review.claude.md      # Review staged changes
```

---

## Rich Output Rendering

By default, LLM output is rendered with syntax highlighting and visual markdown structure (headers, code blocks, etc.). This uses `marked-terminal` for beautiful terminal output.

To bypass rendering (e.g., for piping to other commands):

```bash
md task.claude.md --raw | jq .
```

---

## Context Dashboard

Before execution, md shows a pre-flight dashboard with your context tree and token estimates:

```
┌─ Pre-Flight ──────────────────────────────────────────────────┐
│  📄 review.claude.md                                   1.2 KB │
│  ├── 📁 @./src/**/*.ts                     (12 files) 24.5 KB │
│  └── 📄 @./README.md                                   3.1 KB │
│                                                               │
│  Total: 28.8 KB (~7,200 tokens)                              │
└───────────────────────────────────────────────────────────────┘
```

Use `--_quiet` to skip the dashboard, or `--_context` to show it and exit without executing.

---

## The `md explain` Command

Inspect what an agent will do without running it:

```bash
md explain review.claude.md
```

Shows:

- Resolved command and source (filename, flag, etc.)
- Final flags after config merging (built-in → global → project → frontmatter)
- Expanded prompt preview with token count
- Trust status for remote URLs
- Environment variables that will be set

---

## Edit Before Execute

Use `--_edit` to open the fully resolved prompt in your `$EDITOR` before execution:

```bash
md task.claude.md --_edit
```

This lets you review and tweak the final prompt (after template substitution and import expansion) before sending it to the LLM.

---

## Notes

- On typed failures, mdflow emits a stable error code prefix like `[CONFIG_FILE_PARSE_FAILED]`.
- See [`docs/public-api.md#error-codes`](docs/public-api.md#error-codes) for the full error-code catalog.
- If no frontmatter is present, the file is printed as-is (unless command inferred from filename)
- Template system uses [LiquidJS](https://liquidjs.com/) - supports conditionals, loops, and filters
- Logs are always written to `~/.mdflow/logs/<agent-name>/` for debugging
- Use `md logs` to show the log directory
- Piped input is available as `{{ _stdin }}` template variable
- Template variables use `_` prefix: `_name` in frontmatter → `{{ _name }}` in body → `--_name` CLI flag
- Remote URLs are cached at `~/.mdflow/cache/` with 1-hour TTL (use `--_no-cache` to bypass)
- Imports inside code blocks (``` or `) are ignored by the parser
- Interactive file picker sorts by frecency (frequency + recency) for quick access to common agents
