TL;DR
An open-source tool lets you mark up Markdown files with a shebang so they run like shell programs by piping them through Claude Code with full stdin/stdout. The system supports Claude Code’s tool use (so scripts can run commands, access files, and call APIs), Unix pipe semantics, and examples show it replacing glue code and improving auditability.
What happened
A developer created an open-source utility that treats Markdown documents as executable programs by using a shebang that directs execution to a runner (e.g., #!/usr/bin/env claude-run). Marked Markdown files can be made executable (chmod +x) and invoked directly from the shell (./task.md). The runner routes the document through Claude Code, which can employ tool use to run shell commands, read and write files, and make API calls; stdin and stdout are fully supported so these documents participate in standard Unix pipelines (for example: cat data.json | ./analyze.md > results.txt). The project includes an example permission flag (–permission-mode bypassPermissions) and demonstrates replacing Python orchestration code with composable Markdown building blocks that can be used in cron jobs or mixed with shell loops. The implementation is available on GitHub and currently works with Claude Code; the author says they hope to add support for other AI coding tools and alternate cloud routing.
Why it matters
- Makes LLM-driven workflows composable using familiar Unix tools and pipes.
- Reduces custom orchestration code (e.g., Python glue) by turning prompts into executable building blocks.
- Full stdin/stdout support lets AI-driven scripts be chained and integrated with existing shell workflows.
- Markdown-based scripts can be easier for humans to read and audit than opaque install shell snippets.
Key facts
- The tool lets Markdown files include a shebang such as #!/usr/bin/env claude-run to make them executable.
- Executable Markdown supports full stdin and stdout, so it can be used in Unix pipelines.
- Claude Code’s tool use enables executable Markdown to run shell commands, write scripts, read files, and call APIs.
- Files are made runnable with chmod +x and invoked like standard programs (e.g., ./task.md).
- Examples show chaining (cat data.json | ./analyze.md > results.txt) and mixing with shell loops.
- A permission example in the source uses –permission-mode bypassPermissions for a test-run script.
- The author reports this approach replaced much Python glue code in their workflows.
- Project source is published on GitHub (https://github.com/andisearch/claude-switcher).
- The implementation currently works with Claude Code and the author hopes to support other AI coding tools.
What to watch next
- Support for other AI coding tools beyond Claude Code (the author says they hope to add this).
- Options to route execution through different cloud providers for separate billing or isolation (mentioned as possible).
- not confirmed in the source
Quick glossary
- Shebang: A line at the start of a script (beginning with #!) that indicates which interpreter should execute the file.
- stdin/stdout: Standard input and standard output streams used by Unix programs to read input and write output, enabling composition with pipes.
- Unix pipe: A mechanism that sends the output of one program directly as input to another, enabling composition of command-line utilities.
- Claude Code: An AI coding model or environment referenced by the project that supports tool use to run commands and access external resources.
- Executable Markdown: Markdown documents designed to be run like scripts by directing them to an interpreter or runner via a shebang.
Reader FAQ
How do you make a Markdown file executable with this tool?
Include a shebang that points at the runner (for example #!/usr/bin/env claude-run), make the file executable (chmod +x), then run it (./file.md).
Can executable Markdown read and write files or run shell commands?
Yes. The runner sends the document through Claude Code, whose tool use can perform shell commands, file I/O, and API calls according to the source.
Is the project open source and where is the code?
Yes. The implementation is published on GitHub at https://github.com/andisearch/claude-switcher.
Will it support other AI models or providers?
The author expresses a hope to support other AI coding tools and routing through cloud providers, but broader support is not detailed.
I wanted to run markdown files like shell scripts. So I built an open source tool that lets you use a shebang to pipe them through Claude Code with full…
Sources
- Show HN: Executable Markdown files with Unix pipes
- DevOps Notebooks Built with Markdown • RUNME
- f-corvaro/PIPEX: "Unleash the power of Unix pipelines and …
- What is the executable file of pipe operator / pipe character …
Related posts
- Researchers probe commercial AI models, extract entire Harry Potter book
- Bose publishes SoundTouch API docs as speakers near end-of-life
- Embassy: A Rust-based, async-first framework for safe embedded applications