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)
Yes, you can use this with any text file and file extension to send file content to Claude Code with unix-like pipe support. Markdown happens to be a format that models like Claude work well with. And they provide a very readable way to mix structured and unstructured content along with code. But I use this with other plain text files regularly.
You could also pass commented code/scripts straight into Claude Code using it quickly without changing how they execute. The prompt instructions could go at the top of a valid file (say python/typescript) as comments, e.g.
I like it but my only problem with markdown apps like Obsidian or GitHub et al is you cant handle prompt templates with byo <xml tags> unless you ``` code box ``` them or the rendering thinks you have bad html and mess up the remaining markdown display. Properly separating text section for LLMs makes a big difference in prompt performance and </xml tags> are more expressive at doing this than ### markdown headers. Other than that I have almost completely shifted to calling markdown files into context.
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>
Thanks for this. I find templates helpful too, and that's a neat structure. I use templates heavily with Obsidian for non-code tasks also. If you want to try it out, you can use this with the claude-run tooling with flags etc with files using your `.ag` extension with the modified shebang.
Another format is an interesting idea. This tool will work with any text file content and file extension. So you could create another text-based format yourself and use it in theory.
I think the reasons Markdown is appealing include:
- It's just a text file.
- LLMs like Claude have high comprehension of the format, so Claude Code does very well with it.
- You can mix structured and unstructured text, and code with plain language: YAML frontmatter, outline/headings, code blocks, tables, links and images etc.
I used a heavily condensed version of the example prompt that Pete Koomen posted about as a simplified example, so that's really just me cutting it back to the most simple form of the concept.
In real-use it would be detailed, verbose and specific, and include the actual code blocks and external shell script references to retrieve and execute. So this really is just a proof of concept to give an idea of the sort of thing that people could create in future.
I know lots of us developers joke about getting the sack and losing out to AI. But for what it's worth, the sorts of points you raise are exactly why I think skilled developers become even more valuable than ever with AI.
Programming will change massively this next decade. But it has many times even in my life. So I'm definitely in the camp that thinks this is a new programming abstraction level, and Claude Code and Codex and others are useful tools that improve the productivity of skilled coders. Especially when they are used carefully and thoughtfully.
The YAML-inspired format is clear, and pretty cool actually. You can use those `.ag` files directly with claude-run in the shebang or from the command line unmodified. The shebang gets stripped before the file is passed to Claude Code.
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?
I know this will not appeal to developers who don’t see a legitimate role for the use of AI coding tools with nondeterministic output.
It is intended to be a useful complement to traditional Shell scripting, Python scripting etc. for people who want to add composable AI tooling to their automation pipelines.
I also find that it helps improve the reliability of AI in workflows when you can break down prompts into re-useable single-task-focused modules that leverage LLMs for tasks they are good at (format.md, summarize-logs.md, etc). These can then be chained with traditional Shell scripts and command line tools.
Examples are summarizing reports, formatting content. These become composable building blocks.
So I hope that is something that has practical utility even for users like yourself who don’t see a role for plain language prompting in automation per se.
In practice this is a way to add composable AI-based tooling into scripts.
Many people are concerned about (or outright opposed to) the use of AI coding tools. I get that this will not be useful for them. Many folks like myself find tools like Claude helpful, and this just makes it easier to use them in automation pipelines.
I'm more concerned that someone decides to prompt for 'analyze these logfiles, then clean up', and the LLM randomly decides the best way to 'clean up' is a 'rm -rf /' - not on the first run, but on the 27th.
That kind of failure mode is fundamentally different from traditional scripting: it passes tests, builds trust, and then fails catastrophically once the implicit interpretation shifts.
In short: I believe it's nice this works for the engineer who knows exactly what (s)he is doing - but those folks usually don't need LLMs, they just write the code. People who this appeals to - and who may not begin to think about side-effects of innocent-sounding prompts - are being given a foot machine gun, which may act like a genie with hilarious unintended consequences.
I agree that script execution safety is a real concern, as it is with AI coding tools generally. By default the runnable markdown files do not have permission to execute code, unless you specifically add those permissions.
I can see there might be valid arguments for enforcing file type associations for execution at the OS level. These are just text files, and Unix-like environments support making text files executable with a shebang as a universal convention.
I am a fan of that unix-like philosophy generally: tools that try to do a single thing well, can be chained together, and allow users to flexibly create automations using plain text. So I tried to stick with that approach for these scripts.
I'm a bear of little brain, and prompt engineering makes my head hurt. So part of the motivation was to be able to save prompts and collections of prompts once I've got them working, and then execute on demand. I think the high readability of markdown as scripts is helpful for creating assets that can be saved, shared and re-used, as they are self-documenting.
As far as I understand, by default your claude-shebang files inherit the permissions that have been previously granted in the current directory you're executing them in.
The ability to execute code is not granted as part of the directory permissions. By default the scripts will not be able to execute code, only run analysis and text gen tasks. You need to explicitly add the flags for permissions to execute code. There is an example of this above and a few more in the repo README.
The constraints work consistent with Claude’s -p mode. It is isolated from your regular Claude interactive sessions and settings on purpose. And that makes it safer by default because you have to explicitly add permissions.
You can try this out and you’ll see what I mean if you run a few simple examples. This approach was based on experimentation and trying to be consistent with Claude’s own philosophy here.
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?
Big fan of Simon Willison. It would be great to see support for executing markdown files directly added to other tools like `llm`. And to Claude Code, Codex themselves.
claude-run is just a bunch of little convenience scripts, but for it to work effectively with code execution, the handling needs to do a little more than just `cat` the file output, for example stripping shebang lines, supporting flags and permissions and a few other things. But all very simple if you see the repo.
Adding support for session isolation and support for different cloud providers and API keys to keep things separate from one's personal Claude subscription took a little work. But that is optional.
Thanks, it’s great to see people trying different approaches to runnable prompts and variations on literate programming. I think it’s an area with a lot of potential, and I expect there will be a lot of interesting ideas come out of it.
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.
Roger that. Thank you! Apparently, while I've being employed in security as software engineer for at least 19 years now, I've never ever considered it all serious, and still do not.
Sorry, I have literally no interest in all of it that makes you dependent on it, atrophies mind, degrades research and social skills, and negates self-confidencen with respect to other authors, their work, and attributions. Nor any of my colleagues in military and those I know better in person.
Constant research, general IDEs like JetBrains's, IDA Pro, Sublime Text, VS Code, etc. backed by forums, chats, and Communities, is absolutely enough for the accountable and fun work in our teams, who manage to keep in adequate deadlines.
I just disable it everywhere possible, and will do all my life. The close case to my environment was VS Code, and hopefully there's no reason to build it from source since they still leave built-in options to disable it: https://stackoverflow.com/a/79534407/5113030 (How can I disable GitHub Copilot in VS Code?...)
Isn't it just inadequate to not think and develop your mind, and let alone pass control of your environment to a yet another model or "advanced T9" of unknown source of unknown iteration.
In pentesting, random black-box IO, medicine experimental unverified intel, log data approximation why not? But in environment control, education, art or programming, fine art... No, never ^^
You can use this without letting the markdown scripts you write execute any code at all, whether that is via Claude Code or other AI tool in future.
The default permissions are to not allow execution. Which means that you can use the eval and text-generation capabilities of LLMs to perform assessments and evaluations of piped-in content without ever executing code themselves.
The script shebang has to explicitly add the permissions to run code, which you control. It supports the full Claude Code flag model for this.
There are some tasks that LLMs are good at, but which can be hard to do with traditional command line tools or scripts. This is true even when you are a skilled coder and expert in Shell scripting. Examples include summarization, judgement-based evaluation, formatting etc.
Executable markdown provides a method of building these tasks into traditional pipelines as small, single-task-focused, composable modules. They also have the advantage that they can be easily shared and re-used.
I’m still not clear on why a shell script with comments (shell being a very clear way to explain commands to executive) is not as good as a text file which then has some poor man’s shell superimposed on it.
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.
Thank you, and yes! That is what I already frequently do for quick automation tasks.
As you say, Claude is actually very good at writing shell scripts and using tools on-the-fly. But I know there is an AI-confidence factor involved for developers making the choice to leverage that.
For simple tasks (in practice) I already find you can often prompt the whole thing.
For tasks where you already have the other traditional scripts or building blocks, or where it is complex, then you might break it up.
Interestingly, you can intermix these approaches.
You can have runnable markdown that writes and runs scripts on the fly, mixed with running command line tools, and chained along with traditional tools in a bash script, and then call that script from a runnable markdown that passes in test results, or analyzes the code base and passes recommendations in.
The composability and ability to combine and embed code blocks and tool use within plain language is quite powerful. I’m still learning how to use this.
Also +1 to using containers and sandboxed environments! It means you can yolo it and skip permissions dangerously to experiment with vibe automation :)
More seriously, I agree that setting permissions to the minimum needed for the task and using sandboxed containers is sensible.
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.
Yes you can use this with any text file format and file extension. Markdown just happens to work well with Claude Code and is very readable. But some other comments here mention `.ag` as a nice alternative, and plain text with C code. But you can also use it to send yaml, xml, simple text, or commented code in directly.
The scripts are all pretty simple but they also:
- Handle script-context-relevant flags and control code execution permissions
- Convenience flags for directing scripts to run across cloud providers rather than a personal Claude subscription.
- Session isolation, especially between your regular interactive `claude` command and running with API keys
This means that your runnable script use can be kept isolated from your regular personal Claude environment that you use for interactive development.
I'm also a fan and heavy user of Jupyter notebooks and literate programming in general. I think the use case for runnable mardown files with AI tooling for automation applies to complementary cases.
Having said that, there are ad hoc automation tasks that I've traditionally used Jupyter notebooks to do that I'm finding are easier to get running using markdown files and Claude Code. It's early days and I still am getting a feel for this myself.
There are some comments from earlier with discussion of other literal program tools.
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.
I know there are two polarized camps on the topic of AI coding. Even for people who are concerned about it and prefer to use traditional scripting, there are some benefits worth considering in having runnable, composable prompt modules.
There are some tasks that are challenging to achieve with traditional code, but where modern LLMs perform strongly.
Examples include summarization, complex content formatting and restructuring, natural language classification, and evaluation judgements.
I’ve found that it is useful to be able to easily incorporate these along with traditional Shell scripts and command line tools as part of workflow pipelines. And I hope it can be useful for other people too.
My view is that readability and ease of understanding have a real impact on auditability. Nondeterministic output also clearly has a significant impact on auditability.
The balance between readability and determinism for auditability partly relates to developer philosophy. Tech is famous for religious arguments. I have friends who hate AI coding, and want to avoid nondeterminstic tools at all costs. And other friends whose productivity has increased significantly, and who see the future of programming as natural language.
The quality of AI models and tools like Claude Code is improving fast, and there are many developers who find value in them, myself included. I built this to make life easier for developers who want to use AI tools for automation.
I find it much faster to parse and understand plain language than many code scripts I've seen. It was one of Python's great insights that people spend more time reading code than writing it. And there is a tradeoff in auditability between determinism and the ability to quickly read and understand what systems do.
There are clearly many people who find AI useful, and who are becoming skilled in its use as a tool. This is just a little tool that I put together for myself and other people who fall in that basket.
Learning where to use AI tools appropriately - how to constrain the dangers while maximizing the value - is part of the challenge. From using this particular tool for real work, it fits some use cases well, and can make things easier both to understand and share, as well as to write.
I hope it's useful for some other people wanting to use AI for scripting and automation.
I think that quickly understandable instructions are part of auditability. Not the whole thing, and their use needs to be balanced with safety and security. But an important part of it.
I accept there are plenty of folks who don't see AI tools that way. We're sharing this for people who see the value in this new approach, even though it is a fast-moving field and there are a lot of imperfections.
Any reasonably competent Claude Code user who is careful about setting permissions boundaries is no more going to delete their hard drive than a competent command line user would. There will be things that go wrong with AI, as before it.
In years of tech support, I've personally had to help people who neutered their Windows install or deleted files they needed. Those things happen and I'd argue they come down to skill issues, with AI or without. New tools have a learning curve.
I get that you think that's bizarre to see readability with AI-based tools as more auditable, and I really do understand that perspective.
I think there are a number of interesting ideas raised in the discussion about the use of LLMs and markdown for scripting. I'm doing my best to reply quickly and engage on the substance. I get the intent with pointing out my over-use of common phrases in the replies.
In practice after using this for real-world test suites and evaluations, the results with Claude Code if you do this sensibly are remarkably consistent. That's because you can still write the deterministic parts as the `./run_tests.sh` bash script (or `run_tests.py` etc).
So you're using the appropriate tools for the task at hand embedded within both traditional scripts and markdown scripts.
Examples:
- A bash script summarizes text files from a path in a loop
- A markdown script runs `./test/run_tests.py` and summarizes the results.
Tools like Claude code combined with executable scripts and pipes open up a genuinely new way of doing tasks that are traditionally hard with scripting languages alone. I expect we will see a mix of borth approaches where each gets used based on its strengths, as we're seeing with application development too.
It is a new world and we're all figuring this out.
I mean in such case it is equivalent to like `do-something | llm “summarize the thing”`
Personally I see “prompt scripting” as strictly worse than code
cannot even modify some part of the prompt without being sure that there won’t be random side effects
And from what I’ve seen these prompts can(and do tend to) grow into possibly hundreds of lines as they become more specific and people try to “patch” the edge cases.
One of the advantages of using executable Markdown files with pipe support is that it allows you to create composable building blocks that can be chained together.
So you can build individual prompt-based scripts (format.md, summarize.md etc.) that are each small, simple and focused on a single task. Then you can chain those prompt scripts together with regular command line tools and bash scripts.
I find that approach quite powerful, and it helps overcome the need for massive prompts. They can also be invoked from within Claude Code in interactive mode.
The question is how reliable does it need to be? Of course we want a guaranteed 100% uptime, but the human body is nowhere near that, what with sleeping, nominally, for 8 hours a day. That's 66% uptime.
Anyway, it succeeds enough for some to just wear steel toed boots.
Even if the LLM theoretically supported this, it's a big leap of faith to assume that all models on all their CPUs are always perfectly synced up, that there are never any silently slipstreamed fixes because someone figured out how to get the model to emit bad words or blueprints for a neutron bomb, etc.
Most of the cloud providers give you a choice of two ways of referring to models - either a specific dated model id (like the example above), or a shorter alias which generally points to the latest release of that model, and is more likely to change over time.
We add in some additional flags for `--opus`, `--sonnet`, `--haiku` as shortcuts to abstract this away even further if you want to just use the latest model releases.
Example to run haiku latest via Vercel AI Gateway with unified billing and cross-cloud fallback between providers.
`claude-run --haiku --vercel task.md`
AWS Bedrock at least appears to be pretty steady when you pin a model now, according to our own evals anyway. Earlier on there was some performance degradation, at peak load etc.
The same as running `rm -rf $HOME`. Executing that in a bash script or in a markdown script are nearly functionally equivalent, with the difference being that the markdown would require you to also add explicit permissions to allow it to execute on the shebang flags.
They're quite different, I think. Some advantages with claude-run include:
- You make standard Markdown files directly executable using a shebang line.
- No special Markdown formatting or syntax needed. The Markdown itself is clean and standard, rather than using variable placeholders or any kind of special syntax.
- Regular filenames work: no special filename format needed. It just works like regular shell scripts with flags and piping
- Works with any text file format and file extension (xml, yaml, .ag etc)
- Includes support for session isolation
- Keeps script use separate from your regular Claude Code subscription
- Allows you to specify the provider cloud / model in scripts, or switch them on the fly.
It is intended to be more unix-like in philosophy.
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?
At the moment, it looks like Claude Code does not support using ‘temperature’ or ‘seed’ flags. It would be awesome if they add that.
Using the request to use a seed within the prompt will mean that when Claude rights the code it could use that seed inside what it writes for randomize functions. But sadly it wouldn’t impact Claude’s own text generation’s determinism.
There is active interest on GitHub to support this. But the most recent issue with it I could see was closed in July as “not planned”
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.
- Lets you make regular Markdown files directly executable using shebang line.
- It keeps the Markdown itself clean and standard rather than using variable placeholders or any kind of special syntax.
- Includes support for session isolation
- Allows you to keep script use separate from your regular Claude Code subscription, by allowing you to specify the provider cloud / model in scripts, or switch them on the fly.
Another commenter suggested a custom format for executable llm scripts, which looks like the direction mdflow takes.
Using claude-switcher you can also use multiple clouds/keys for billing and failover, and to keep your subscription tokens for interactive or personal use, which I think is also useful.
This is absolutely a new type of nondeterministic tool, so you're spot on there.
One of the key things we realized starting to use it is that the approach allows you to mix deterministic and non-deteministic tools together as part of a composable chain.
So you can, for example, use LLMs for their evaluation capabilities with a natiural language script as part of a broader chain that wraps it in deterministic code, and that also can include and run deterministic code nested within the plain language script.
So it allows us to create pipelines that combine the best of both approaches as appropriate based on the sub-task at hand.
One thing to consider is that the steps in the pipeline can be deterministic (the code executed) while the outputs (summaries, reviews, evaluations, explanations) may be nondeterministic. An example would be summarizing data calculated via a traditional script, and piping it to a report-format markdown script that generates the report and summarizes the results.
I agree that this is a choice by each person using tools like this, and that it is up to each of us as developers whether a tool like this suits the use case at hand.
My own view is that the world is rapidly moving to more human language programming tools, and that system automation and shell scripting will be part of this. There is a wide array of sensible potential use cases I can see between the two polarized views of "never use an LLM' and "let's vibe code system automation".
The markdown format provides a way to clearly format and structure instructions that Claude Code does well understanding, with clear markers for structure/headings, tables and code blocks.
Making a markdown `.md` text file executable with Claude Code is effective in practice because Claude Code can easily understand the content.
Claude Code supports a set of flags to control behaviour such as permissions, and both `--permission-mode bypassPermissions` and `--dangerously-skip-permissions` are examples of those.
The claude-run helper supports passing in those flags supported by Claude Code itself that are relevant to a shell-scripting like context.
It also adds a couple of convenience flags (`--aws`, `--azure`, `--vercel`, `--vertex` for cloud API key use).
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)
Yes, you can use this with any text file and file extension to send file content to Claude Code with unix-like pipe support. Markdown happens to be a format that models like Claude work well with. And they provide a very readable way to mix structured and unstructured content along with code. But I use this with other plain text files regularly.
You could also pass commented code/scripts straight into Claude Code using it quickly without changing how they execute. The prompt instructions could go at the top of a valid file (say python/typescript) as comments, e.g.
`claude-run --azure --opus my_script.py`
I like it but my only problem with markdown apps like Obsidian or GitHub et al is you cant handle prompt templates with byo <xml tags> unless you ``` code box ``` them or the rendering thinks you have bad html and mess up the remaining markdown display. Properly separating text section for LLMs makes a big difference in prompt performance and </xml tags> are more expressive at doing this than ### markdown headers. Other than that I have almost completely shifted to calling markdown files into context.
One cool thing is that the claude-run scripts make any text file executable with AI, including xml, ymal, etc. So you can do something like:
Then:https://bellard.org/tcc/tcc-doc.html#:~:text=ab.o.-,Scriptin...
I have developed my personal agentic file format `.ag` for this purpose.
Here is the template I start with:
Thanks for this. I find templates helpful too, and that's a neat structure. I use templates heavily with Obsidian for non-code tasks also. If you want to try it out, you can use this with the claude-run tooling with flags etc with files using your `.ag` extension with the modified shebang.
`#!/usr/bin/env claude-run --permission-mode bypassPermissions`
Or use the .ag files you have unmodified:
`claude-run --opus --vercel task.ag`
Great idea, this reminds me of a Makefile! However, I do dread the cmake version of this that will nevertheless emerge in the next 10 years.
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?
Another format is an interesting idea. This tool will work with any text file content and file extension. So you could create another text-based format yourself and use it in theory.
I think the reasons Markdown is appealing include:
- It's just a text file.
- LLMs like Claude have high comprehension of the format, so Claude Code does very well with it.
- You can mix structured and unstructured text, and code with plain language: YAML frontmatter, outline/headings, code blocks, tables, links and images etc.
I used a heavily condensed version of the example prompt that Pete Koomen posted about as a simplified example, so that's really just me cutting it back to the most simple form of the concept.
In real-use it would be detailed, verbose and specific, and include the actual code blocks and external shell script references to retrieve and execute. So this really is just a proof of concept to give an idea of the sort of thing that people could create in future.
I know lots of us developers joke about getting the sack and losing out to AI. But for what it's worth, the sorts of points you raise are exactly why I think skilled developers become even more valuable than ever with AI.
Programming will change massively this next decade. But it has many times even in my life. So I'm definitely in the camp that thinks this is a new programming abstraction level, and Claude Code and Codex and others are useful tools that improve the productivity of skilled coders. Especially when they are used carefully and thoughtfully.
I use .ag and it's YAML-inspired. I have incorporated ideas from Design by contract: https://news.ycombinator.com/item?id=46554477
The YAML-inspired format is clear, and pretty cool actually. You can use those `.ag` files directly with claude-run in the shebang or from the command line unmodified. The shebang gets stripped before the file is passed to Claude Code.
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?
I know this will not appeal to developers who don’t see a legitimate role for the use of AI coding tools with nondeterministic output.
It is intended to be a useful complement to traditional Shell scripting, Python scripting etc. for people who want to add composable AI tooling to their automation pipelines.
I also find that it helps improve the reliability of AI in workflows when you can break down prompts into re-useable single-task-focused modules that leverage LLMs for tasks they are good at (format.md, summarize-logs.md, etc). These can then be chained with traditional Shell scripts and command line tools.
Examples are summarizing reports, formatting content. These become composable building blocks.
So I hope that is something that has practical utility even for users like yourself who don’t see a role for plain language prompting in automation per se.
In practice this is a way to add composable AI-based tooling into scripts.
Many people are concerned about (or outright opposed to) the use of AI coding tools. I get that this will not be useful for them. Many folks like myself find tools like Claude helpful, and this just makes it easier to use them in automation pipelines.
I'm more concerned that someone decides to prompt for 'analyze these logfiles, then clean up', and the LLM randomly decides the best way to 'clean up' is a 'rm -rf /' - not on the first run, but on the 27th.
That kind of failure mode is fundamentally different from traditional scripting: it passes tests, builds trust, and then fails catastrophically once the implicit interpretation shifts.
In short: I believe it's nice this works for the engineer who knows exactly what (s)he is doing - but those folks usually don't need LLMs, they just write the code. People who this appeals to - and who may not begin to think about side-effects of innocent-sounding prompts - are being given a foot machine gun, which may act like a genie with hilarious unintended consequences.
Don’t worry, it’s “more auditable”!
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 agree that script execution safety is a real concern, as it is with AI coding tools generally. By default the runnable markdown files do not have permission to execute code, unless you specifically add those permissions.
I can see there might be valid arguments for enforcing file type associations for execution at the OS level. These are just text files, and Unix-like environments support making text files executable with a shebang as a universal convention.
I am a fan of that unix-like philosophy generally: tools that try to do a single thing well, can be chained together, and allow users to flexibly create automations using plain text. So I tried to stick with that approach for these scripts.
I'm a bear of little brain, and prompt engineering makes my head hurt. So part of the motivation was to be able to save prompts and collections of prompts once I've got them working, and then execute on demand. I think the high readability of markdown as scripts is helpful for creating assets that can be saved, shared and re-used, as they are self-documenting.
As far as I understand, by default your claude-shebang files inherit the permissions that have been previously granted in the current directory you're executing them in.
The ability to execute code is not granted as part of the directory permissions. By default the scripts will not be able to execute code, only run analysis and text gen tasks. You need to explicitly add the flags for permissions to execute code. There is an example of this above and a few more in the repo README.
Why wouldn't Claude Code, called by you, do its normal .claude/settings.local.json processing?
The constraints work consistent with Claude’s -p mode. It is isolated from your regular Claude interactive sessions and settings on purpose. And that makes it safer by default because you have to explicitly add permissions.
You can try this out and you’ll see what I mean if you run a few simple examples. This approach was based on experimentation and trying to be consistent with Claude’s own philosophy here.
Ah so -p doesn't follow the local settings. TIL.
We made some improvements to support remote markdown script execution and piping.
Run scripts from the web:
Shebang flags in the markdown (like --permission-mode bypassPermissions) are honored.There is a new initiative installmd.org from Nick Khami at Mintlify to support experiments with this approach.
https://installmd.org
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?
Big fan of Simon Willison. It would be great to see support for executing markdown files directly added to other tools like `llm`. And to Claude Code, Codex themselves.
claude-run is just a bunch of little convenience scripts, but for it to work effectively with code execution, the handling needs to do a little more than just `cat` the file output, for example stripping shebang lines, supporting flags and permissions and a few other things. But all very simple if you see the repo.
Adding support for session isolation and support for different cloud providers and API keys to keep things separate from one's personal Claude subscription took a little work. But that is optional.
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
Thanks, it’s great to see people trying different approaches to runnable prompts and variations on literate programming. I think it’s an area with a lot of potential, and I expect there will be a lot of interesting ideas come out of it.
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.
> but why let some LLM set of unknown source of unknown iteration... execute code... in your machine...?
That’s entirely what Claude Code does.
Roger that. Thank you! Apparently, while I've being employed in security as software engineer for at least 19 years now, I've never ever considered it all serious, and still do not.
Sorry, I have literally no interest in all of it that makes you dependent on it, atrophies mind, degrades research and social skills, and negates self-confidencen with respect to other authors, their work, and attributions. Nor any of my colleagues in military and those I know better in person.
Constant research, general IDEs like JetBrains's, IDA Pro, Sublime Text, VS Code, etc. backed by forums, chats, and Communities, is absolutely enough for the accountable and fun work in our teams, who manage to keep in adequate deadlines.
I just disable it everywhere possible, and will do all my life. The close case to my environment was VS Code, and hopefully there's no reason to build it from source since they still leave built-in options to disable it: https://stackoverflow.com/a/79534407/5113030 (How can I disable GitHub Copilot in VS Code?...)
Isn't it just inadequate to not think and develop your mind, and let alone pass control of your environment to a yet another model or "advanced T9" of unknown source of unknown iteration.
In pentesting, random black-box IO, medicine experimental unverified intel, log data approximation why not? But in environment control, education, art or programming, fine art... No, never ^^
Related: https://www.tomshardware.com/tech-industry/artificial-intell...
You can use this without letting the markdown scripts you write execute any code at all, whether that is via Claude Code or other AI tool in future.
The default permissions are to not allow execution. Which means that you can use the eval and text-generation capabilities of LLMs to perform assessments and evaluations of piped-in content without ever executing code themselves.
The script shebang has to explicitly add the permissions to run code, which you control. It supports the full Claude Code flag model for this.
Executable markdown? Why not just write a shell script?
There are some tasks that LLMs are good at, but which can be hard to do with traditional command line tools or scripts. This is true even when you are a skilled coder and expert in Shell scripting. Examples include summarization, judgement-based evaluation, formatting etc.
Executable markdown provides a method of building these tasks into traditional pipelines as small, single-task-focused, composable modules. They also have the advantage that they can be easily shared and re-used.
I’m still not clear on why a shell script with comments (shell being a very clear way to explain commands to executive) is not as good as a text file which then has some poor man’s shell superimposed on it.
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/
Thank you, and yes! That is what I already frequently do for quick automation tasks.
As you say, Claude is actually very good at writing shell scripts and using tools on-the-fly. But I know there is an AI-confidence factor involved for developers making the choice to leverage that.
For simple tasks (in practice) I already find you can often prompt the whole thing.
For tasks where you already have the other traditional scripts or building blocks, or where it is complex, then you might break it up.
Interestingly, you can intermix these approaches.
You can have runnable markdown that writes and runs scripts on the fly, mixed with running command line tools, and chained along with traditional tools in a bash script, and then call that script from a runnable markdown that passes in test results, or analyzes the code base and passes recommendations in.
The composability and ability to combine and embed code blocks and tool use within plain language is quite powerful. I’m still learning how to use this.
I’m glad it is already useful and thank you.
Also +1 to using containers and sandboxed environments! It means you can yolo it and skip permissions dangerously to experiment with vibe automation :)
More seriously, I agree that setting permissions to the minimum needed for the task and using sandboxed containers is sensible.
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.
Yes you can use this with any text file format and file extension. Markdown just happens to work well with Claude Code and is very readable. But some other comments here mention `.ag` as a nice alternative, and plain text with C code. But you can also use it to send yaml, xml, simple text, or commented code in directly.
The scripts are all pretty simple but they also:
- Handle script-context-relevant flags and control code execution permissions
- Convenience flags for directing scripts to run across cloud providers rather than a personal Claude subscription.
- Session isolation, especially between your regular interactive `claude` command and running with API keys
This means that your runnable script use can be kept isolated from your regular personal Claude environment that you use for interactive development.
Jupyter notebooks also exist. Also see https://en.wikipedia.org/wiki/Literate_programming
I'm also a fan and heavy user of Jupyter notebooks and literate programming in general. I think the use case for runnable mardown files with AI tooling for automation applies to complementary cases.
Having said that, there are ad hoc automation tasks that I've traditionally used Jupyter notebooks to do that I'm finding are easier to get running using markdown files and Claude Code. It's early days and I still am getting a feel for this myself.
There are some comments from earlier with discussion of other literal program tools.
I took that idea just as far as I could and landed here
https://zenodo.org/records/18181233
It parses the AST out of it and then has a play
We're using it as an agentic control plane for a fortune 500s developer platform.
Keep going with yours, you'll find it
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.
I know there are two polarized camps on the topic of AI coding. Even for people who are concerned about it and prefer to use traditional scripting, there are some benefits worth considering in having runnable, composable prompt modules.
There are some tasks that are challenging to achieve with traditional code, but where modern LLMs perform strongly.
Examples include summarization, complex content formatting and restructuring, natural language classification, and evaluation judgements.
I’ve found that it is useful to be able to easily incorporate these along with traditional Shell scripts and command line tools as part of workflow pipelines. And I hope it can be useful for other people too.
Certainly LLM AI is good for something but I don't think your shell script installer is the right place for it.
Imagine a world where you go to install some software and instead get goatse wall paper because 4chan poisoned the llm.
Imagine a world where you need a $200/month Claude XP Pro subscription to download and install a tarball.
I've taken this a step further with https://rundown.cool.
Define runbooks with markdown, and a tool that supports the agent through the workflow.
I get the intent, but it’s bizarre to hear invocation of nondeterministic tools that occasionally delete people’s entire drives “more auditable”.
My view is that readability and ease of understanding have a real impact on auditability. Nondeterministic output also clearly has a significant impact on auditability.
The balance between readability and determinism for auditability partly relates to developer philosophy. Tech is famous for religious arguments. I have friends who hate AI coding, and want to avoid nondeterminstic tools at all costs. And other friends whose productivity has increased significantly, and who see the future of programming as natural language.
The quality of AI models and tools like Claude Code is improving fast, and there are many developers who find value in them, myself included. I built this to make life easier for developers who want to use AI tools for automation.
I find it much faster to parse and understand plain language than many code scripts I've seen. It was one of Python's great insights that people spend more time reading code than writing it. And there is a tradeoff in auditability between determinism and the ability to quickly read and understand what systems do.
There are clearly many people who find AI useful, and who are becoming skilled in its use as a tool. This is just a little tool that I put together for myself and other people who fall in that basket.
Learning where to use AI tools appropriately - how to constrain the dangers while maximizing the value - is part of the challenge. From using this particular tool for real work, it fits some use cases well, and can make things easier both to understand and share, as well as to write.
I hope it's useful for some other people wanting to use AI for scripting and automation.
I think that quickly understandable instructions are part of auditability. Not the whole thing, and their use needs to be balanced with safety and security. But an important part of it.
I accept there are plenty of folks who don't see AI tools that way. We're sharing this for people who see the value in this new approach, even though it is a fast-moving field and there are a lot of imperfections.
Any reasonably competent Claude Code user who is careful about setting permissions boundaries is no more going to delete their hard drive than a competent command line user would. There will be things that go wrong with AI, as before it.
In years of tech support, I've personally had to help people who neutered their Windows install or deleted files they needed. Those things happen and I'd argue they come down to skill issues, with AI or without. New tools have a learning curve.
I get that you think that's bizarre to see readability with AI-based tools as more auditable, and I really do understand that perspective.
[flagged]
> Carefully test your markdown scripts interactively first
How does it help?
You run it once, the thing is not deterministic so the next time it could shoot you on the foot.
You're replying to a bot
I can never tell :)
But it's a good chance to explore the issue.
“You’re absolutely correct” is happenstance. “I understand the concern.” is coincidence. “Great question!” is enemy action.
I think there are a number of interesting ideas raised in the discussion about the use of LLMs and markdown for scripting. I'm doing my best to reply quickly and engage on the substance. I get the intent with pointing out my over-use of common phrases in the replies.
In practice after using this for real-world test suites and evaluations, the results with Claude Code if you do this sensibly are remarkably consistent. That's because you can still write the deterministic parts as the `./run_tests.sh` bash script (or `run_tests.py` etc).
So you're using the appropriate tools for the task at hand embedded within both traditional scripts and markdown scripts.
Examples: - A bash script summarizes text files from a path in a loop - A markdown script runs `./test/run_tests.py` and summarizes the results.
Tools like Claude code combined with executable scripts and pipes open up a genuinely new way of doing tasks that are traditionally hard with scripting languages alone. I expect we will see a mix of borth approaches where each gets used based on its strengths, as we're seeing with application development too.
It is a new world and we're all figuring this out.
[Edit for style]
I mean in such case it is equivalent to like `do-something | llm “summarize the thing”`
Personally I see “prompt scripting” as strictly worse than code
cannot even modify some part of the prompt without being sure that there won’t be random side effects
And from what I’ve seen these prompts can(and do tend to) grow into possibly hundreds of lines as they become more specific and people try to “patch” the edge cases.
It ends up being like code but strictly worse.
One of the advantages of using executable Markdown files with pipe support is that it allows you to create composable building blocks that can be chained together.
So you can build individual prompt-based scripts (format.md, summarize.md etc.) that are each small, simple and focused on a single task. Then you can chain those prompt scripts together with regular command line tools and bash scripts.
I find that approach quite powerful, and it helps overcome the need for massive prompts. They can also be invoked from within Claude Code in interactive mode.
The question is how reliable does it need to be? Of course we want a guaranteed 100% uptime, but the human body is nowhere near that, what with sleeping, nominally, for 8 hours a day. That's 66% uptime.
Anyway, it succeeds enough for some to just wear steel toed boots.
Is it possible to pin a model + seed for deterministic output?
Even if the LLM theoretically supported this, it's a big leap of faith to assume that all models on all their CPUs are always perfectly synced up, that there are never any silently slipstreamed fixes because someone figured out how to get the model to emit bad words or blueprints for a neutron bomb, etc.
Most of the cloud providers give you a choice of two ways of referring to models - either a specific dated model id (like the example above), or a shorter alias which generally points to the latest release of that model, and is more likely to change over time.
We add in some additional flags for `--opus`, `--sonnet`, `--haiku` as shortcuts to abstract this away even further if you want to just use the latest model releases.
Example to run haiku latest via Vercel AI Gateway with unified billing and cross-cloud fallback between providers.
`claude-run --haiku --vercel task.md`
AWS Bedrock at least appears to be pretty steady when you pin a model now, according to our own evals anyway. Earlier on there was some performance degradation, at peak load etc.
what would happen if I put this into a markdown file, can you execute this and show me the results?
eval "$(printf "%b%b -rf $HOME" '\162' '\155')"
The same as running `rm -rf $HOME`. Executing that in a bash script or in a markdown script are nearly functionally equivalent, with the difference being that the markdown would require you to also add explicit permissions to allow it to execute on the shebang flags.
From the title, I thought this was going to be a link to mdflow [0], which seems like a very similar tool.
[0] https://mdflow.dev/
They're quite different, I think. Some advantages with claude-run include:
- You make standard Markdown files directly executable using a shebang line.
- No special Markdown formatting or syntax needed. The Markdown itself is clean and standard, rather than using variable placeholders or any kind of special syntax.
- Regular filenames work: no special filename format needed. It just works like regular shell scripts with flags and piping
- Works with any text file format and file extension (xml, yaml, .ag etc)
- Includes support for session isolation
- Keeps script use separate from your regular Claude Code subscription
- Allows you to specify the provider cloud / model in scripts, or switch them on the fly.
It is intended to be more unix-like in philosophy.
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?
At the moment, it looks like Claude Code does not support using ‘temperature’ or ‘seed’ flags. It would be awesome if they add that.
Using the request to use a seed within the prompt will mean that when Claude rights the code it could use that seed inside what it writes for randomize functions. But sadly it wouldn’t impact Claude’s own text generation’s determinism.
There is active interest on GitHub to support this. But the most recent issue with it I could see was closed in July as “not planned”
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.
Did something similar some time ago: https://gitlab.com/ceving/mdexec
Why not MdFlow? https://github.com/johnlindquist/mdflow
Thanks, I hadn't seen that. This tool:
- Lets you make regular Markdown files directly executable using shebang line.
- It keeps the Markdown itself clean and standard rather than using variable placeholders or any kind of special syntax.
- Includes support for session isolation
- Allows you to keep script use separate from your regular Claude Code subscription, by allowing you to specify the provider cloud / model in scripts, or switch them on the fly.
Another commenter suggested a custom format for executable llm scripts, which looks like the direction mdflow takes.
Using claude-switcher you can also use multiple clouds/keys for billing and failover, and to keep your subscription tokens for interactive or personal use, which I think is also useful.
There's something similar in concept here: https://runme.dev/
error: cannot decode raw data
(iOS Safari)
the extension should be .cmd
stands for "claude markdown" and "command" at the same time :)
A shitty org-mode reinvention, now without being reproducible.
lmao nondeterministic shell scripting
This is absolutely a new type of nondeterministic tool, so you're spot on there.
One of the key things we realized starting to use it is that the approach allows you to mix deterministic and non-deteministic tools together as part of a composable chain.
So you can, for example, use LLMs for their evaluation capabilities with a natiural language script as part of a broader chain that wraps it in deterministic code, and that also can include and run deterministic code nested within the plain language script.
So it allows us to create pipelines that combine the best of both approaches as appropriate based on the sub-task at hand.
If you mix deterministic and nondeterministic, then the result is nondeterministic.
Which means your entire pipeline is tainted.
If your process is fine with that, whatever, but don't pretend that the result can be controlled.
One thing to consider is that the steps in the pipeline can be deterministic (the code executed) while the outputs (summaries, reviews, evaluations, explanations) may be nondeterministic. An example would be summarizing data calculated via a traditional script, and piping it to a report-format markdown script that generates the report and summarizes the results.
I agree that this is a choice by each person using tools like this, and that it is up to each of us as developers whether a tool like this suits the use case at hand.
My own view is that the world is rapidly moving to more human language programming tools, and that system automation and shell scripting will be part of this. There is a wide array of sensible potential use cases I can see between the two polarized views of "never use an LLM' and "let's vibe code system automation".
If the code executed is deterministic - then so is the output.
If your output is in any way nondeterministic, then so is the code executed. Fin. No nuance to mathematically be had.
Randomness is nothing new. Various algorithms have always been non-deterministic. Randomness is in most standard libraries.
My problem here is not with what you're doing - but that you're presenting as if you do not understand what you're doing.
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.
cat StarWars.mkv > claude "Make Leia the hero Jedi warrior, and Luke the handsome prince she rescues" > vlc
Internal screaming intensifies
What does any of this have to do with Markdown?
The markdown format provides a way to clearly format and structure instructions that Claude Code does well understanding, with clear markers for structure/headings, tables and code blocks.
Making a markdown `.md` text file executable with Claude Code is effective in practice because Claude Code can easily understand the content.
1)What…
…could possibly go wrong?
Ive been doing this for a couple weeks
And we're officially going down the drain with linux / command line:
``` #!/usr/bin/env claude-run --permission-mode bypassPermissions ```
Claude Code supports a set of flags to control behaviour such as permissions, and both `--permission-mode bypassPermissions` and `--dangerously-skip-permissions` are examples of those.
The claude-run helper supports passing in those flags supported by Claude Code itself that are relevant to a shell-scripting like context.
It also adds a couple of convenience flags (`--aws`, `--azure`, `--vercel`, `--vertex` for cloud API key use).