Show HN: Executable Markdown files with Unix pipes

jedwhite · Jan 9, 2026

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 stdin/stdout support.
task.md:

Code:

    #!/usr/bin/env claude-run

    Analyze this codebase and summarize the architecture.

Then:

Code:

    chmod +x task.md

    ./task.md

These aren't just prompts. Claude Code has tool use, so a markdown file can run shell commands, write scripts, read files, make API calls. The prompt orchestrates everything.
A script that runs your tests and reports results (run_tests.md):

Code:

    #!/usr/bin/env claude-run --permission-mode bypassPermissions

    Run ./test/run_tests.sh and summarize what passed and failed.

Because stdin/stdout work like any Unix program, you can chain them:

Code:

    cat data.json | ./analyze.md > results.txt

    git log -10 | ./summarize.md

    ./generate.md | ./review.md > final.txt

Or mix them with traditional shell scripts:

Code:

    for f in logs/\*.txt; do

        cat "$f" | ./analyze.md >> summary.txt

    done

This replaced a lot of Python glue code for us. Tasks that needed LLM orchestration libraries are now markdown files composed with standard Unix tools. Composable as building blocks, runnable as cron jobs, etc.
One thing we didn't expect is that these are more auditable (and shareable) than shell scripts. Install scripts like curl -fsSL [URL]https://bun.com/install[/URL] | bash could become:

Code:

    `curl -fsSL https://bun.com/install.md | claude-run`

Where install.md says something like "Detect my OS and architecture, download the right binary from GitHub releases, extract to ~/.local/bin, update my shell config." A normal human can actually read and verify that.
The (really cool) executable markdown idea and auditability examples are from Pete Koomen (@koomen on X). As Pete says: "Markdown feels increasingly important in a way I'm not sure most people have wrapped their heads around yet."
We implemented it and added Unix pipe semantics. Currently works with Claude Code - hoping to support other AI coding tools too. You can also route scripts through different cloud providers (AWS Bedrock, etc.) if you want separate billing for automated jobs.
GitHub: GitHub - andisearch/claude-switcher: Script automation for Claude Code: executable markdown with shebang support, Unix pipes, provider switching (AWS/Vertex/Azure), and session-scoped API key management.
What workflows would you use this for?

Comments URL: Show HN: Executable Markdown files with Unix pipes | Hacker News

Points: 48

# Comments: 45

Continue reading...

Show HN: Executable Markdown files with Unix pipes

jedwhite