Great idea! During my time as a researcher, I heavily used org-babel. I used it to put code for data wrangling, plots, and notes into a single document. The notes would often contain formulas to describe what was done. I would regularly export that to PDF using pdflatex to send it to collaborators. Maybe this is an avenue worth considering for Ledge.
Thanks! I'm looking for ways to extend Ledge further. Math / Science capabilities could be cool (although I'll probably need a contributor that knows those needs to help out)
This seems like the logical evolution of `mask` which i've been using and enjoying for a long time, felt like I needed to give it a shout out https://github.com/jacobdeichert/mask
I was recently researching apps like this for the usecase of writing devops/tech-support "playbooks", and also (related) "runnable readmes". Among many approaches and attempts I found, I most liked the one taken by https://runme.dev, for a bunch of reasons. Did you try it? Do you (plan to) support their features and format? It was still missing a few things I'd like (including some that I see in yours), but to me it also has some advantages over yours - e.g.:
- env vars parametrization;
- a CLI tool with interactive or non-interactive interface (maybe you also have one? I didn't check);
- flags in fence-blocks rather than in frontmatter.
Runme is great. One thing I required was mobile support which I didn't see in Runme. I also thought the VS Code dependency was a bit heavy for me since I otherwise don't use VS Code.
- env vars parametrization: this is an issue I've hit myself and am looking to add a solution for it. Created an issue for it: https://github.com/ledgesh/ledge/issues/9
- CLI: Ledge does have a CLI. One gap is it can't run a code block from the CLI - another good item to add. Created as an issue: https://github.com/ledgesh/ledge/issues/10
- flags: you can add flags in the codeblock in Ledge (like confirm, norun, etc)
I like the concept, I know there have been some other things in the general area but often tied a bit more to data analysis.
I am a big fan of documenting processes as "do nothing scripts" which just repeatedly prompt you to go and do something, and you then incrementally actually add automation. I think this is a nice side of something here as well, as well as things for observability (baked in queries)
I scanned about a bit, so may have missed this but not sure I saw how the code for sh things looked in the markdown. I thought it'd be cool if existing readmes and common ways people put the code in automatically meant opening a readme/quickstart authored by a random person meant I'd get a clicky auto-run set of things.
I don't know if it makes sense to add, so don't take it as a "I need X" however I think you will probably soon hit either for yourself or from requests how to chain things together in non-linear ways. Dependencies, X if Y, running things in parallel, etc. And also things like failures, continue vs rerun, things like that.
Not sure how to add those latter things neatly, or if you should, but I think those are the next features you'll probably see requested and you may need to decide your philosophy for the project and not only what it does but what it explicitly does not try and address.
Side thought, with lots of sandboxing and stuff these days I'm thinking about ledge and what could exist under it for like a "system ran and did things, changes are here and proposed to accept/deny/roll back".
Awesome feedback! For code in the markdown it's just simple blocks like ```sh, ```python, etc. So your README example should mostly work. Regarding flows / conditionals - Right now it's up to the user to look at the response and determine what's next. But I do hit this problem myself - based on a response my workflow may branch off into an entirely different direction. Like you said, I'll have to decide the philosophy about how to approach something like this but it is a real challenge.
I went to look at Atuin Desktop to see what the crossover was with this product, and it's fascinating to see that the repo was archived the day this was posted here!
This is awesome I will definitely play around with it. Fits the niche gap as a standalone app vs something like [Observable Framework](https://observablehq.github.io/framework/) for data analytical type things.
I wish Notion could just integrate these things together and make it work, or someone build an Obsidian plugin. More often than not it would be so convenient to do something like this.
As an Emacs user for over a decade I think this is brilliant, it solves my biggest gripes with org-babel which prevent me from using it in a team setting.
Ledge is a lot like org-babel from Emacs, but for muggles: a familiar UI, and common format go a long way.
Yes, exactly that. Org predates Markdown, however the Achilles heel is that it's tied to Emacs. I love Emacs, but I can't (ethically and pragmatically) force any editor/IDE on anyone. And as soon as a lone emacser commits an org file to a repo, it creates a disconnect.
Markdown (although it doesn't adhere to a strict standard) is ubiquitous, and support for Ledge notebooks degrades gracefully.
If one doesn't have Ledge installed to run it, it can be assumed that their editor is able to render markdown. Even opened in a plain text editor, markdown is a lot easier on the eyes than org (IMHO).
I think it's mainly an issue of preference. Markdown is common these days and already exists in READMEs etc. I know it so I tend to prefer it. I also require the ability to access my notes from my phone and that's more of a challenge with org-babel.
I wonder what would org-babel for team settings look like? Disk/interchange format seems less interesting than what gets shipped around and what the UX feels like.
> I built Ledge because I spend much of my day copy/pasting commands from my notes into the terminal. I was inspired by how much cmux helped me organize my terminals - but there was still a split brain between my notes and frequently Run commands. I've been daily-driving it for the past few weeks and use it for deploys, API calls, smoke tests, etc.
I see it might be handy for exploring your own pipelines (and so are things like https://github.com/akavel/up/ ) , but I advise against using this for any serious project management. Nontrivial and/or crucial code-blocks in markdown files is an anti-pattern.
Once i find I'm re-using code from my markdown notes, I make it a script in ${dotfiles}/bin or in ${project}/scripts and put related docs in there. This feels like the inverse of this tool's imposed workflow and has the upside of composability of tools.
Then use something like a makefile to call these tools/scripts behind generic phony targets (or you can roll your own 'project.sh' entry point script if really needed).
It then becomes just `make release`. it is portable already and does not add yet another host dependency on everybody nor a fricking javascript engine.
Ledge doesn't remove the need to write scripts / automations. But for things like complex deploy pipelines there are still many manual / human steps in between. So I use Ledge to run my automation scripts, do some manual checks, based on those run more automations, etc.
Very cool! I launched something similar as well. My idea was to create a working document in which people could develop their own tools and agents. Conversations with coding agents are treated as editable, executable documents. Both the person and the agent can write on the same page. Rather than correcting a mistake in a follow-up, you can rewrite it, delete a detour, or edit and re-run an earlier prompt. The file is always readable Markdown.
Check out: https://piary.dev/
Feel free to get in touch if you are open to an exchange, you can find my contact details in the write-up.
Interesting. This seems like a good alternative to Jupyter Notebooks. I get annoyed when working with them using agents. They avoid editing the file directly because there is too much JSON bloat (or sometimes image bytes). It'd be great if this had a config option / toggle for 'Notebook mode' that would enable Jupyter-like execution, e.g., run all cells above, below, etc, so I could use it as a notebook.
https://jupytext.org/ may be what you're looking for! It saves Notebook files as Python/text files, and can open them as Notebooks. I've mostly used it for improved version control and easier file inspection, but they recently started advertising the agent use case on their website.
I feel like there has been a few takes on this (atuin desktop comes to mind[0] but apparently it's not a going concern anymore?) why hasn't it caught on?
I'm curious about this too. Org-babel, Jupyter, Atuin Desktop, etc. have explored similar ideas, but none became a mainstream way of working.
For people who used these tools long-term: what held them back? UX/accessibility, or do people simply prefer keeping documents separate from the actual work?
we saw a bunch of issues with desktop, in no particular order
1. authoring runbooks is difficult, most people barely document their work let alone make it executable
2. keeping runbooks up to date is difficult, they are error-prone across systems
3. agents are now pretty good at a number of the tasks these ideas solve for, and are good at working around issues caused by docs becoming out of date/etc
all these tools are great for your own notes, but are very difficult to scale
1. Ledge's bet is it shouldn't feel like authoring at all. I've always had markdown docs chock full of commands and docs so making them runnable was the next logical step for me.
2. True. Keeping any kind of documentation up to date is difficult
3. Also true. I'm hoping Ledge's built-in agent support will bridge that gap and allow agents to help keep the docs up-to-date
And yes, a "Team" notebook is a challenge. Technically anyone with SSH access can all share a Ledge notebook. But that probably doesn't get us all the way there.
Thanks again for providing your thoughts. This by no means is a solved problem but I'm interested to see where it goes!
Thanks for answering. That's really interesting.
Maybe agents flip this around. Instead of humans maintaining executable docs, the actual work generates the document.
It could become something like a PR-style review layer for agent work. You don't necessarily need to understand the underlying code or tooling, but you can inspect what changed, why it changed, and approve or reject it.
Do you think that would address any of the scaling problems you saw?
Ellie, I’ve greatly appreciated your work and your talks! Thanks for sharing your insights.
To give a bit more discouraging advice to Ledge, these tldr insights have made me run circles to resolve. My experience is that one will start getting into build system and dependency mapping to make this sustainable. And then if one wants something more universal, one ends up building something like homebrew, which doesn’t even cover all OSs for good reason.
As you dig deep across system dependency and updates and configurations, there are crazy, crazy, crazy cascading bugs that popup from personal experience. As an example of how this comes up in practice, this is why many teams end up building on Electron as a common cross-platform bug fixer (Tauri has catching up to do although generally works well).
I've used org-babel in big and small contexts for more than a decade. I generally reach for the patter for a few goals:
- Keep diagram source (eg Graphviz dot) with the document.
- Write software developer manuals that can reference code robustly as the code changes (eg include code snippets from source based on regex).
- Literate Coding / Reproducible Research pattern. Eg, org file explains and generates/builds/runs code and graphs/figures which then get included back into the document.
Some of the problems
- At some scale, one needs a DAG (eg make) or to make every command idempotent with fast no-op. Otherwise, each little change to a source block takes too long and there is a worry that something didn't update which should.
- At some scale, the document becomes the size of a library/package and it does not compose and/or I want to run the code outside of the document.
- The unenlightened around me do not use Emacs so an org file is a "me" file. In some ways this is a plus as it keeps others fingers out of my pie but it also means no way to share the baking.
That was in the days before LLMs. As ellieh's #3 points out, things are different now (we all know that). I now have an LLM externalize org-babel. The LLM maintains an org or LaTeX document describing bits of work, an external library/CLI which runs to produce content including putting numerical results into LaTeX macros, a Makefile or Snakemake to regenerate content and figures. When things are found to change prior understanding the LLM remakes a section of prose in the LaTeX document. I then write my own notes or another LaTeX document so that the trip through eyeballs to fingers on the keyboard assures I keep some level of understanding.
Likewise, in the software documentation goal, it's far better to give a good LLM access to the source and have it generate documentation targeting some learning goal with follow exploration via Q&A than it is to read some prepared document that assumes my goal. Software documentation is kind of a relic useful only for those people that have not yet taken up LLM tools.
This is pretty cool. I've been interested in runnable code in markdown for a long time. It's a kind of "literate programming¹" which I've always thought was one of Knuth's best ideas.
More prior art: xcfile²
I've used xc³ for a long time now and it's fairly solid. The idea of runnable markdown is definitely useful. A lot of projects have attempted it and none that I've seen have achieved what I'd call perfection, however, xc gets close enough for my needs.
I'll check out Ledge a bit more thoroughly and give some feedback if I can think of anything constructive. I think xc is probably more suited for my uses, however, I do like electrobun and that seems like a good runtime to build something like this.
Here's what I like about xc:
1. It's built with GO and brings all the power of go's template engine. The portability of go's runtime means that it is just one binary and doesn't have any crazy runtime dependencies.
2. It has a built in dependency system so that each block of code can be predicated on another block completing. It can also ensure that each block in a dependency chain runs just once.
I've built a sort of configuration management system for my home infrastructure with config files in a git repo and all the deployment scripts and dependencies directly in the readme. I use it to maintain and deploy changes to my router, firewall rules, dhcp and dns, git repositories, and various containers.
I have something very similar that works in neovim buffers for those interested (unfortunately mostly AI written, yet to be reviewed, but is being used frequently by me)
I can foresee my team using this for documenting our local tooling. I’m wondering also if it could store a login token to make authenticated requests with, to create sales handovers from.
cool idea, do you have any plans to integrate command generation with the shell completion / aliases / functions? Say I have tons of muscle memory on using ctrl-r fzf to get things from history, or on pressing tab to autocomplete pod names etc. so I would never write out a full kubectl command to execute by hand
Ctrl-R, fzf and tab completion work in the terminal drawer. But completion in the editor doesn't exist currently. Really good idea, however so let me look into it!
Good question. Main differences of Ledge: You don't need Emacs for those of us that don't use it already. Markdown instead of Org syntax. Shells are interactive by default. Mobile apps can run the shell/code.
This is cool. I'll probably use this to store my commonly used prompts so I don't have to retype them all the time. For whatever reason I like being able to see all of their contents upfront like this instead of using skills, which feels like you're working in the dark. Then having the extra execution modes on top of that is great too.
Also, interestingly, this is great for creating task lists. Then you can execute each task one by one. Maybe consider adding something like hooks that lets you update the 'prompt' as well, or some state tag on it or something? (maybe you'll think of a better way to represent this), but basically, instead of having my agent write its todo lists like:
- [] task one
- [x] task two
You could write them as individual prompts in Ledge, and then have some system where it can update the state of the prompt so you could set it to completed once it's finished automatically via the agent.
Edit: Okay I just tried it. Not sure why, but on Linux (Ubuntu 26.04 with a 4090 rtx) it's REALLY laggy for me. Scrolling and resizing the window is glitching hardcore, and typing is very slow.
You described my exact use case :) Great idea about hooks. Something I'll look into for sure.
And, dang - sorry it's laggy for you! I've created a GH issue that includes some things for you to try and I'll work through them myself too: https://github.com/ledgesh/ledge/issues/8
Woooow! I love the idea of having documentation that I can just run directly as I'm reading through it, that also has a nice GUI to it.
There's a similar product called Atuin Desktop (https://github.com/atuinsh/desktop) that uses Tauri for the GUI and the performance is just abysmal (makes my pc fans spin up like crazy when I launch it and navigate around), and have been on a lookout for something that handles the GUI aspect better. Definitely going to try this out.
Jupyter is great. From what I recall it's bash kernel isn't a real terminal session so sudo prompts, top, etc can tend to get a bit wonky. I also have a preference towards Markdown over .ipynb.
This is all valid, but I'd suggest rethinking the slogan "The notebook that runs code" at the top of the README. I much prefer .md too and haven't used notebooks regularly in years, but nevertheless I scoffed when I read that (I thought: hasn't this guy heard of Jupyter?). I believe you'd be better off not calling this a "notebook" at all since that terms tends to describe something slightly different than what you have here.
In truth I think it was just the use of the definite article that got me. This is a notebook that runs code, not the notebook that runs code. I just think this is cool and it could be better differentiated.
Yes, strong Hammacher Schlemmer vibes. I noticed years ago that they try to make every product sound like the pinnacle by prefacing it with "The". Somewhat effective, until you catch on.
Scoffing and thinking "hasn't this guy heard of Jupyter" says more about your attitude than it does the tool or its README copy.
Hasn't this guy heard of [old product that is a huge pain and no one likes]? Why would he ever make something that suits his own interests and preferences?
Yes, exactly. I'm sharing with this creator what my initial knee-jerk reaction was, admittedly exaggerating a bit. In case he'd like to avoid other people having a similar reaction. (And indeed, he thanked me for my feedback.)
It seems like you think that pointing out that I'm sharing my attitude is some sort of gotcha, but I'm confused. Sharing one's attitude is the whole point of posting an internet comment, isn't it?
Here I am using it as frontend to Jupyter and ollama [2].
[1] https://github.com/PratikDeoghare/brashtag
[2] https://youtu.be/IMXgIE0Vljg?si=sBmmZ1nHlbHifKBd
Marimo - recently had a lot of success with this: https://marimo.io/
RMarkdown: https://rmarkdown.rstudio.com/
Quarto: (this is more the editor really I guess) https://quarto.org/
- env vars parametrization;
- a CLI tool with interactive or non-interactive interface (maybe you also have one? I didn't check);
- flags in fence-blocks rather than in frontmatter.
- env vars parametrization: this is an issue I've hit myself and am looking to add a solution for it. Created an issue for it: https://github.com/ledgesh/ledge/issues/9
- CLI: Ledge does have a CLI. One gap is it can't run a code block from the CLI - another good item to add. Created as an issue: https://github.com/ledgesh/ledge/issues/10
- flags: you can add flags in the codeblock in Ledge (like confirm, norun, etc)
Thanks for the great input!
I like the concept, I know there have been some other things in the general area but often tied a bit more to data analysis.
I am a big fan of documenting processes as "do nothing scripts" which just repeatedly prompt you to go and do something, and you then incrementally actually add automation. I think this is a nice side of something here as well, as well as things for observability (baked in queries)
I scanned about a bit, so may have missed this but not sure I saw how the code for sh things looked in the markdown. I thought it'd be cool if existing readmes and common ways people put the code in automatically meant opening a readme/quickstart authored by a random person meant I'd get a clicky auto-run set of things.
I don't know if it makes sense to add, so don't take it as a "I need X" however I think you will probably soon hit either for yourself or from requests how to chain things together in non-linear ways. Dependencies, X if Y, running things in parallel, etc. And also things like failures, continue vs rerun, things like that.
Not sure how to add those latter things neatly, or if you should, but I think those are the next features you'll probably see requested and you may need to decide your philosophy for the project and not only what it does but what it explicitly does not try and address.
Side thought, with lots of sandboxing and stuff these days I'm thinking about ledge and what could exist under it for like a "system ran and did things, changes are here and proposed to accept/deny/roll back".
https://github.com/atuinsh/desktop
I wish Notion could just integrate these things together and make it work, or someone build an Obsidian plugin. More often than not it would be so convenient to do something like this.
To be clear, is the issue with org-babel that it's not accessible to other people on the team? or something else that this solves?
Markdown (although it doesn't adhere to a strict standard) is ubiquitous, and support for Ledge notebooks degrades gracefully. If one doesn't have Ledge installed to run it, it can be assumed that their editor is able to render markdown. Even opened in a plain text editor, markdown is a lot easier on the eyes than org (IMHO).
UX matters.
I see it might be handy for exploring your own pipelines (and so are things like https://github.com/akavel/up/ ) , but I advise against using this for any serious project management. Nontrivial and/or crucial code-blocks in markdown files is an anti-pattern.
Once i find I'm re-using code from my markdown notes, I make it a script in ${dotfiles}/bin or in ${project}/scripts and put related docs in there. This feels like the inverse of this tool's imposed workflow and has the upside of composability of tools.
Then use something like a makefile to call these tools/scripts behind generic phony targets (or you can roll your own 'project.sh' entry point script if really needed). It then becomes just `make release`. it is portable already and does not add yet another host dependency on everybody nor a fricking javascript engine.
ps1: Same goes for weird stuff like https://pypi.org/project/taskipy/ . use `make release` over `poetry run task release`
ps2: if you're copy/pasting-workflow sucks: improve it. vim has :Terminal, it has yank-to-clipoard etc.
[1]: https://www.youtube.com/watch?v=YufgfbUgEgI and xiki.org
Feel free to get in touch if you are open to an exchange, you can find my contact details in the write-up.
0: https://github.com/atuinsh/desktop
For people who used these tools long-term: what held them back? UX/accessibility, or do people simply prefer keeping documents separate from the actual work?
we saw a bunch of issues with desktop, in no particular order
1. authoring runbooks is difficult, most people barely document their work let alone make it executable
2. keeping runbooks up to date is difficult, they are error-prone across systems
3. agents are now pretty good at a number of the tasks these ideas solve for, and are good at working around issues caused by docs becoming out of date/etc
all these tools are great for your own notes, but are very difficult to scale
1. Ledge's bet is it shouldn't feel like authoring at all. I've always had markdown docs chock full of commands and docs so making them runnable was the next logical step for me.
2. True. Keeping any kind of documentation up to date is difficult
3. Also true. I'm hoping Ledge's built-in agent support will bridge that gap and allow agents to help keep the docs up-to-date
And yes, a "Team" notebook is a challenge. Technically anyone with SSH access can all share a Ledge notebook. But that probably doesn't get us all the way there.
Thanks again for providing your thoughts. This by no means is a solved problem but I'm interested to see where it goes!
Very happy to hear what you think of it. I've built it specifically for reviewing outcomes instead of impementations.
Humans define what correct looks like, agents implement and attach evidence (image, videos, etc.) that humans can review.
I've updated the landing page so it's clear that it's in beta and added a small "your data" page for now https://higherlevel.to/your-data
To give a bit more discouraging advice to Ledge, these tldr insights have made me run circles to resolve. My experience is that one will start getting into build system and dependency mapping to make this sustainable. And then if one wants something more universal, one ends up building something like homebrew, which doesn’t even cover all OSs for good reason.
As you dig deep across system dependency and updates and configurations, there are crazy, crazy, crazy cascading bugs that popup from personal experience. As an example of how this comes up in practice, this is why many teams end up building on Electron as a common cross-platform bug fixer (Tauri has catching up to do although generally works well).
- Keep diagram source (eg Graphviz dot) with the document.
- Write software developer manuals that can reference code robustly as the code changes (eg include code snippets from source based on regex).
- Literate Coding / Reproducible Research pattern. Eg, org file explains and generates/builds/runs code and graphs/figures which then get included back into the document.
Some of the problems
- At some scale, one needs a DAG (eg make) or to make every command idempotent with fast no-op. Otherwise, each little change to a source block takes too long and there is a worry that something didn't update which should.
- At some scale, the document becomes the size of a library/package and it does not compose and/or I want to run the code outside of the document.
- The unenlightened around me do not use Emacs so an org file is a "me" file. In some ways this is a plus as it keeps others fingers out of my pie but it also means no way to share the baking.
That was in the days before LLMs. As ellieh's #3 points out, things are different now (we all know that). I now have an LLM externalize org-babel. The LLM maintains an org or LaTeX document describing bits of work, an external library/CLI which runs to produce content including putting numerical results into LaTeX macros, a Makefile or Snakemake to regenerate content and figures. When things are found to change prior understanding the LLM remakes a section of prose in the LaTeX document. I then write my own notes or another LaTeX document so that the trip through eyeballs to fingers on the keyboard assures I keep some level of understanding.
Likewise, in the software documentation goal, it's far better to give a good LLM access to the source and have it generate documentation targeting some learning goal with follow exploration via Q&A than it is to read some prepared document that assumes my goal. Software documentation is kind of a relic useful only for those people that have not yet taken up LLM tools.
https://blog.atuin.sh/atuin-desktop-runbooks-that-run/
More prior art: xcfile²
I've used xc³ for a long time now and it's fairly solid. The idea of runnable markdown is definitely useful. A lot of projects have attempted it and none that I've seen have achieved what I'd call perfection, however, xc gets close enough for my needs.
I'll check out Ledge a bit more thoroughly and give some feedback if I can think of anything constructive. I think xc is probably more suited for my uses, however, I do like electrobun and that seems like a good runtime to build something like this.
Here's what I like about xc:
1. It's built with GO and brings all the power of go's template engine. The portability of go's runtime means that it is just one binary and doesn't have any crazy runtime dependencies.
2. It has a built in dependency system so that each block of code can be predicated on another block completing. It can also ensure that each block in a dependency chain runs just once.
I've built a sort of configuration management system for my home infrastructure with config files in a git repo and all the deployment scripts and dependencies directly in the readme. I use it to maintain and deploy changes to my router, firewall rules, dhcp and dns, git repositories, and various containers.
1. https://en.wikipedia.org/wiki/Literate_programming
2. https://xcfile.dev/
3. https://github.com/joerdav/xc
https://github.com/mktip/bsh.nvim
Also, interestingly, this is great for creating task lists. Then you can execute each task one by one. Maybe consider adding something like hooks that lets you update the 'prompt' as well, or some state tag on it or something? (maybe you'll think of a better way to represent this), but basically, instead of having my agent write its todo lists like:
- [] task one
- [x] task two
You could write them as individual prompts in Ledge, and then have some system where it can update the state of the prompt so you could set it to completed once it's finished automatically via the agent.
Edit: Okay I just tried it. Not sure why, but on Linux (Ubuntu 26.04 with a 4090 rtx) it's REALLY laggy for me. Scrolling and resizing the window is glitching hardcore, and typing is very slow.
And, dang - sorry it's laggy for you! I've created a GH issue that includes some things for you to try and I'll work through them myself too: https://github.com/ledgesh/ledge/issues/8
https://hammacher.com/
Hasn't this guy heard of [old product that is a huge pain and no one likes]? Why would he ever make something that suits his own interests and preferences?
It seems like you think that pointing out that I'm sharing my attitude is some sort of gotcha, but I'm confused. Sharing one's attitude is the whole point of posting an internet comment, isn't it?