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`

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

Or use the .ag files you have unmodified:

`claude-run --opus --vercel task.ag`

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 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 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.

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.

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.

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.

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.

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”

That’s entirely what Claude Code does.

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.

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.

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.

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.

- 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.

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.

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.

Making a markdown `.md` text file executable with Claude Code is effective in practice because Claude Code can easily understand the content.

(iOS Safari)

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).