jedwhite

I do think getting everything running on a single GPU at this resolution and speed is totally new

Thanks, it seemed to be the case that this was really something new, but HN tends to be circumspect so wanted to check. It's an interesting space and I try to stay current but everything is moving so fast. But I was pretty sure I hadn't seen anyone do that. Its a huge achievement to do it first and make it work for real like this! So well done!

That's an interesting insight about "stacking tricks" together. I'm curious where you found that approach hit limits. And what gives you an advantage if anything against others copying it. Getting real-time streaming with a 20B parameter diffusion model and 20fps on a single GPU seems objectively impressive. It's hard to resist just saying "wow" looking at the demo, but I know that's not helpful here. It is clearly a substantial technical achievement and I'm sure lots of other folks here would be interested in the limits with the approach and how generalizable it is.

Thanks for posting the original ideas that led to all this. "Runtime for prose" is the new "literate programming" - early days but a pointer to some pretty cool future things, I think.

It's already made a bunch of tasks that used to be time-consuming to automate much easier for me. I'm still learning where it does and doesn't work well. But it's early days.

You can tell something is a genuinely interesting new idea when someone posts about it on X and then:

1. There are multiple launches on HN based on the idea within a week, including this one.

2. It inspires a lot of discussion on X, here and elsewhere - including many polarized and negative takes.

Hats off for starting a (small but pretty interesting) movement.

I shared a repo on HN last week that lets you use remote execution with these kinds of script files autonomously - if you want to. It had some interesting negative and positive discussion.

The post mentioned Pete Koomen's install.md idea as an example use case. So now with this launch you can try it with a real intstallation script!

I think it's a really interesting idea worth experimentation and exploration. So it's a positive thing to see Mintlify launch this, and that it's already on Firecrawl.dev's docs!

We can all learn from it.

Show HN discussion of executable markdown here:

https://news.ycombinator.com/item?id=46549444

The claude-run tool lets you execute files like this autonomously if you want to experiment with it.

    curl -fsSL https://docs.firecrawl.dev/install.md | claude-run --permission-mode bypassPermissions

https://github.com/andisearch/claude-switcher

This is still a very early-stage idea, but I'm really stoked to see this today. For anyone interested in experimenting with it, it's a good idea to try in a sandboxed environment.

We made some improvements to support remote markdown script execution and piping.

Run scripts from the web:

    ```bash
    
    curl -fsSL https://andisearch.github.io/ai-scripts/analyze.md | claude-run
    
    echo "Explain what a Makefile does" | claude-run         # Simple prompt
    
    ```

There is a new initiative installmd.org from Nick Khami at Mintlify to support experiments with this approach.

https://installmd.org

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.

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:

    #!/usr/bin/env claude-run

    <instructions>

        Analyze this codebase.

    </instructions>

    chmod +x task.xml && ./task.xml

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.

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”

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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`

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`

It's adjacent conceptually so interesting to check out :)

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.

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.

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.

Thanks, I hadn't seen either of those. It's good to see other projects leveraging runnable markdown, as it has a lot of potential.

I like the literate programming tool. I've always liked experimenting with Jupyter notebooks, and I can see running markdown directly as replacing a lot of the ad hoc things I use them for.

It would be great to see Anthropic add support directly to Claude Code, and OpenAI to Codex. I think this sort of literate scripting will become more common this next year, especially as model reliability improves and the tool-use gets smarter.

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.

API clients seem like a good use case.