thedecipherist/markdownai

MarkdownAI is a tool for writing live Markdown documents that are meant to be read by an AI assistant like Claude rather than by a browser. The pitch is plain in the tagline, "documentation that cannot lie." Instead of writing a value into a doc and watching it go stale as the underlying code, database, or environment changes, you write small directives like @env, @http, @db, and @query, and those directives are resolved every time the document is rendered. The authors are clear that this is not a template engine in the Jinja or Handlebars sense. The key differences they call out: the consumer is an AI rather than a browser, the directives run when Claude opens the file rather than at build time, and the resolution happens inside an MCP server before Claude ever sees the file. By the time Claude reads the document, the conditional branches are already chosen, the database queries have already run, and the environment values are already substituted, so the assistant does not have to stop and run shell commands to gather basic facts. A second feature called @phase lets a long workflow be split into named chunks that the MCP server hands out one at a time. A 20-step deployment runbook, for example, does not have to load all 20 steps into the AI's context at once. The model reads phase 1, calls next_phase, and only then receives phase 2. The README presents this as a way to keep complex runbooks, debugging guides, or onboarding sequences from flooding the context window, with each transition between phases being explicit. The project ships as an npm package, @markdownai/markdownai, and as a VS Code extension. It requires Node.js 18 or newer, claims 754 passing tests, and is released under the MIT license. The README points to a hosted documentation site and a separate user guide for the full reference, along with a Quick Start section, a directive reference, and a 78-feature user manual stored inside the repo.