@markdownai

the AI workflow engine.

Packages: @markdownai/core  ·  @markdownai/engine  ·  @markdownai/parser  ·  @markdownai/renderer  ·  @markdownai/mcp

MarkdownAI is a phase-aware AI workflow engine for Claude and AI agents. It phases runbooks, injects live data, and delivers scoped context one step at a time. Add @markdownai to the first line of any .md file and it becomes executable - fetching real values from your environment, databases, APIs, and shell at render time.

This org contains the full MarkdownAI toolchain as a set of focused, composable packages.

v1.3

• Reusable partials with bound data: @template <path> data=<expr> [as=<name>] / inlines another .md file at the call site and binds the expression to {{ data.* }} inside the partial. @data <name> ... @data-end composes a single object from any in-scope values using <key> = <expression> assignments, dot-notation, and ...<expression> spreads. Reads inherit from the caller; writes stay local, so the same partial composes cleanly inside @foreach.

v1.0

• Iteration: @foreach and @set turn documents into programs.
• Filesystem writes: @mkdir, @copy, @append-if-missing, @update-frontmatter, @render-template behind a write_enabled security gate.
• Execution: @test and @check inline the full runner output and expose exit code plus recognized summary as separate labels.
• Targeted reads: @read-frontmatter for single YAML fields, @hash for content hashing.
• @if content helpers: file.containsLine, file.containsSection, file.frontmatterField.
• Three-jail path security: independent source_root, data_root, and write_root. Data ops now default to the process working directory. Breaking change for 0.x users - set filesystem.data_root = "auto" to restore the old behavior.
• SessionStart hook: mai init installs a hook that renders <project>/CLAUDE-MarkdownAI.md on every session and injects it into Claude Code's context. Your CLAUDE.md is never modified.
• Ironclad PreToolUse hook: detects MarkdownAI documents behind YAML frontmatter (Claude Code slash commands) and ships the full 9-tool MCP catalogue inline in its redirect message.

See changed.md for the full change log.

Packages

@markdownai/core

The mai CLI. Everything you need to render, validate, and manage live documents from the terminal.

npm install -g @markdownai/core
mai render ./docs/status.md

Includes all security commands (mai security shell enable), caching, format output, and the MCP integration.

@markdownai/engine

The execution core. Takes a parsed AST and evaluates all directives - shell queries, HTTP requests, database connections, environment resolution, caching, and security enforcement.

If you want to embed MarkdownAI rendering inside your own Node.js app, start here.

import { execute, parse } from '@markdownai/engine'

const ast = parse(source)
const result = execute(ast, { ctx: { security: { allowShell: true } } })
console.log(result.output)

@markdownai/parser

Pure AST production. Reads MarkdownAI source and returns a typed AST with no side effects. No execution, no IO - just parsing.

Use this if you need to analyze or transform MarkdownAI documents without running them.

import { parse } from '@markdownai/parser'

const ast = parse(source)
// ast.nodes - array of typed directive and markdown nodes

@markdownai/renderer

11 output format modules that turn rendered output into different targets: standard Markdown, AI-optimized context, structured JSON, and more.

The renderer handles post-execution formatting and is consumed by both @markdownai/engine and @markdownai/mcp.

@markdownai/mcp

MCP (Model Context Protocol) server for Claude Code and other AI tools. Exposes MarkdownAI rendering as MCP tools so AI assistants can render live documents during a session.

mai-serve  # starts the MCP stdio server

Works with Claude Code hooks to intercept file reads and render live context automatically.

Quick Start

# Install the CLI globally
npm install -g @markdownai/core

# Create a live document
cat > status.md << 'EOF'
@markdownai

# Project Status

**Files in src:** @count src/**/*.ts
**Node version:** @query "node --version" label="node_ver"
{{ node_ver }}
EOF

# Render it
mai render status.md

Links

• Full documentation and spec
• Report issues
• npm org page