jq for Markdown
mq gives Markdown a query language similar to jq. It can select a named section, filter headings, extract links or code blocks, and work with MDX components without making an AI model read the whole document first.
The most useful agent workflow is simple: extract the smallest complete section that contains the rules or evidence for the current task, inspect it, then put that result into the prompt. This reduces context without replacing the source with an AI-written summary.
On Swipe’s real AGENTS.md, the command for selecting the “Issue flow” section
reduced 7,165 bytes to 609 while retaining all 12 lines in that section. mq also
selected the complete top-level MDX components from a published issue, including
the nested content inside each item.
Keep the first use read-only
mq supports updates as well as queries, but read-only extraction is the safer starting point. Its output is semantically faithful rather than byte-for-byte: list indentation, whitespace, and MDX layout can be reserialized. An open issue also reports that update mode can drop backslash escapes and change meaning.
The query runtime denies auxiliary file reads, writes, network requests, command
execution, and environment access unless their corresponding --allow-* flags
are granted. Files explicitly supplied on the command line are necessarily
readable. The local CLI keeps them on the machine; the hosted playground or API
needs the content to be uploaded.
Install and limitations
mq is free and MIT licensed. It is available through Homebrew, Cargo, Docker, release binaries, a browser playground, and an MCP server.
The project describes itself as under active development, and Markdown coverage is not complete. Always compare an extracted section with the source when it contains instructions, code, or unusual Markdown extensions. Use the output as a bounded view of the original document, not as a new source of truth.