HN Explorer

Show HN: Executable Markdown files with Unix pipes

126 points by jedwhite ↗ HN
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:

    #!/usr/bin/env claude-run

    Analyze this codebase and summarize the architecture.
Then:

    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`):

    #!/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:

    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:

    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 https://bun.com/install | bash` could become:

    `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: https://github.com/andisearch/claude-switcher

What workflows would you use this for?

40 comments

[ 4.3 ms ] story [ 57.0 ms ] thread
serious_angel
Oh dear... but... but why let some LLM set of unknown source of unknown iteration... execute code... in your machine...?

I was excited in the possibly extravagant implementation idea and... when I read enough to realize it's based on some yet another LLM... Sorry, no, never. You do you.

[deleted]
(comment deleted)
chrismorgan
I get the intent, but it’s bizarre to hear invocation of nondeterministic tools that occasionally delete people’s entire drives “more auditable”.
[deleted]
(comment deleted)
signalnine
lmao nondeterministic shell scripting
rvz
Exactly. The above is a terrible idea.

I guess these so called “developers” these days did not ever think about why this is needed. Ever.

The “senior/staff” engineers of 2025 are now at the same knowledge level of juniors in 2015 or were not at all “senior” to begin with ideas like this.

imcritic
What does any of this have to do with Markdown?
tedk-42
And we're officially going down the drain with linux / command line:

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

wiether
I think I get the idea... but why not officially create a new file type altogether?

Not only it would avoid any confusion (Markdown wasn't meant to be executable?) but it would allow future extensions in a domain that is moving fast.

The recent incident (https://news.ycombinator.com/item?id=46532075) regarding Claude Code's changelog shows that pure Markdown can break things if it is consumed raw.

Also, regarding: "Detect my OS and architecture, download the right binary from GitHub releases, extract to ~/.local/bin, update my shell config."

I have a hard time seeing how this is "more auditable" than a shell script with hardcoded URLs/paths.

"the right binary" is something that would make me reject an issue from a PM, asking for clarifications because it's way too vague.

But maybe that's why I'll soon get the sack?

rvz
1)What…

…could possibly go wrong?

bsima
Ive been doing this for a couple weeks
Someone
There’s nothing specific markdown to this. It could just as well be some other markup language, plaintext, or even any other textual language.

You could, for example, put a C program on lines 2 and further and expect/hope/pray Claude to interpret or compile and run that (adding a comment “run the following program; download and compile an interpreter or compiler if needed first” as an instruction to Claude would improve your chances)

PurpleRamen
Looks more like executable prompt-files, as there seem to be no extra markdown-handling except removing the shebang. I know AIs are good at handling Markdown-Syntax, but do they support other markup-languages too? So you could use whatever you want here.
trollbridge
Executable markdown? Why not just write a shell script?
JohnKemeny
I have developed my personal agentic file format `.ag` for this purpose.

Here is the template I start with:

    #!/usr/bin/env gpt-agent
     
    input: <target/context (e.g., cwd)>
     
    task: |
      <one clear objective>
     
    output: |
      <deliverables + required format>
     
    require:
      - <must be true before start; otherwise stop + report>
     
    invariant:
      - <must stay true while working (scope + safety)>
     
    ensure:
      - <must be true at the end (definition of done)>
     
    rescue: |
      <what to do if any requirement/invariant/ensure cannot be met>
zahlman
Aside from what several others said about having done something similar locally, wouldn't this be a trivial modification to Simon Willison's `llm` wrapper?
rewilder12
IDK man it feels like you are making a less-useful unsafe wheel.

- file types exist for a reason

- this is just prompt engineering which is already easy to do

DocTomoe
So ... you are letting a nondeterministic LLM operate on the shell, via quasi-shellscript. This will appeal mostly to people who do not have the skillset to write an actual shell-script.

In short, isn't that like giving a voice-controlled scalpel to a random guy on the street an tell them 'just tell it to neurosurgery', and hope it accidentally does the right procedure?

anthk
A shitty org-mode reinvention, now without being reproducible.
calvinmorrison
One silly fun thing about PHP is php tags. So you can do notebooks like this for kinda free... if you want to execute code? just put it in <?php ?> blocks.