alt Hacker NewsShow HN: Executable Markdown files with Unix pipes
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.
chmod +x task.md
./task.md
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.
cat data.json | ./analyze.md > results.txt
git log -10 | ./summarize.md
./generate.md | ./review.md > final.txt
for f in logs/\*.txt; do
cat "$f" | ./analyze.md >> summary.txt
done
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`
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?
Comments
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>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?
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
I found this useful.
This could be dinosaur mindset from 2022, but would it not make sense to prompt the LLM to create a bash script based on these instructions, so it could be more deterministic? Claude code is pretty reliable, but this is probably only one and a half nines at best.
As for safety, running this in a devcontainer[1][2] or as part of a CI system should be completely fine.
1. (conventional usage) https://code.visualstudio.com/docs/devcontainers/containers
2. (actual spec) https://containers.dev/
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?
I'm not the target demographic, but this seems like a step backwards.
Like, once upon a time maybe you gave your jr programmer a list of things to do, and depending on their skill, familiarity with the cli, hangover status, spelling abilities, etc, you'll get different results. So you write a deterministic shell script.
A few people have already mentioned similar tools here but one worth mentioning is Atuin Desktop (yes, the same shell history Atuin): https://blog.atuin.sh/atuin-desktop-runbooks-that-run/
"Executable runbooks" is the name given to the concept there
Executable markdown? Why not just write a shell script?
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.
Does it help get repeatable results if you say, "Use a random seed of 42 for this task"? Or if you somehow lower the temperature, so it's more deterministic?
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.
Jupyter notebooks also exist. Also see https://en.wikipedia.org/wiki/Literate_programming
Did something similar some time ago: https://gitlab.com/ceving/mdexec
cat StarWars.mkv > claude "Make Leia the hero Jedi warrior, and Luke the handsome prince she rescues" > vlc
I get the intent, but it’s bizarre to hear invocation of nondeterministic tools that occasionally delete people’s entire drives “more auditable”.
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?
Ive been doing this for a couple weeks
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.
A shitty org-mode reinvention, now without being reproducible.
1)What…
…could possibly go wrong?
Internal screaming intensifies
There's something similar in concept here: https://runme.dev/
And we're officially going down the drain with linux / command line:
``` #!/usr/bin/env claude-run --permission-mode bypassPermissions ```
[dead]
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)