Ledge.sh Runnable Markdown Notebook – Features, Use Cases, and Community Feedback

Ledge.sh lets you run code directly inside Markdown notes, turning a plain text document into an interactive notebook

Ledge.sh is a free, Apache‑2.0‑licensed notebook that executes shell commands, Python, SQL, and AI prompts inside fenced code blocks. Press ⌘↩ on a block and its output streams beneath the block, making the note both documentation and live execution environment.

Persistent shells per note

Each note owns its own shell session, so cd, exported variables, or activated virtual environments persist across runs.
⌘↩ runs the block under the caret; ⇧⌘↩ sends the block to a detachable terminal drawer for interactive use.
Front‑matter keys cwd: and env: define the starting directory and environment variables for the note’s shells.
Adding norun to a fence disables the Run button, allowing you to quote commands without executing them.

"Runnable notes in plain Markdown is a nice one‑person stack move—fewer copy/paste hops between the doc and the shell when shipping alone." – michaelastreiko (Hacker News)

Remote‑host execution and server‑backed notes

Point Ledge at any SSH‑accessible machine; the server stores the Markdown files and runs the shells.
No separate account or cloud service is required—only SSH authentication.
Multiple clients (desktop, iPhone, iPad, another laptop) can connect simultaneously to the same server, sharing tabs and panes.
ledge backup encrypts notes to an S3‑compatible bucket hourly, providing automated off‑site backups.

Mobile support

iOS and Android clients act as thin windows onto the remote server; they never store notes locally.
The pairing code printed by ledge pair creates a Secure Enclave‑backed key that authenticates the phone without exposing the private key.
All usual editing features—search, tags, backlinks, daily notes, wikilinks—work on mobile, and command output appears when you return to the app.

Running blocks on arbitrary hosts

Adding a host: line in front‑matter routes every block execution over SSH to the specified host.
Ledge prompts for host selection on first run and remembers the last choice.
confirm fences display the code and target host before execution, preventing accidental runs.
The note’s cwd and env travel with the run, keeping secrets out of the note files.

Pane‑based UI and workspace layouts

⌘D splits the view vertically; ⇧⌘D splits horizontally. Each pane holds independent tabs and notes.
Panes retain their own shell sessions, so you can work on two projects side‑by‑side.
Workspace layouts are saved and restored on launch; ⌘1‑⌘9 switch between saved workspaces.

Secure profiles and encrypted notes

Profiles are plain .env files stored outside the notes folder (e.g., ~/.config/ledge/profiles/deploy.env). A note that declares profile: deploy loads those variables into its shells.
Locked notes encrypt the body on disk with a passphrase; titles, tags, and front‑matter remain visible for navigation.
Search and backlinks skip encrypted bodies, reporting how many notes were omitted.

Agent integration

Ledge ships an MCP server; AI agents like Claude can read, search, create, and edit notes via claude mcp add ledge.
Agents can execute prompt blocks, receiving the AI’s response streamed beneath the block.
Because notes are addressed by title (which survives renames), agents maintain stable references.

"I built Ledge because I spend much of my day copy/pasting commands from my notes into the terminal… I see it might be handy for exploring your own pipelines, but I advise against using this for any serious project management." – Piraty (Hacker News)

Git‑based syncing and collaboration

Notes are ordinary Markdown files; any folder sync solution (iCloud, Dropbox, Syncthing, Git) works out of the box.
Ledge watches the folder for external changes and updates open notes live.
A dedicated Sync note runs git add -A && git commit -m "notes $(date +%F)" && git pull --rebase && git push with a single ⌘↩.
Merge conflicts appear as normal Git conflicts; Ledge keeps the open file while moving the other version to the workspace trash.

Six built‑in note types

Type	Typical Use	Example Block
Data exploration	Quick SQL or Python queries	`sql` / `python` blocks
Project runbook	Start services, run migrations	`sh` block with `docker compose up -d db`
Incident response	Query logs, check Redis	`redis` block
Learning to code	Small language snippets	`ruby` block
Homelab management	Run commands on remote hosts	`host: homelab` + `sh` block
Daily journal	Prompt‑driven task lists	`prompt` block

Community reactions

Positive – Users praised the seamless blend of documentation and execution, noting the reduction of copy‑paste friction and the appeal for solo developers and small teams.
Comparisons – Several commenters likened Ledge to Org‑Babel, Jupyter notebooks, and Observable Framework, but highlighted its native Markdown format and cross‑platform GUI as differentiators.
Critiques & suggestions – Requests include tighter shell‑completion integration, notebook‑style cell execution controls, and potential Obsidian plugin wrappers.
Performance notes – One user reported UI lag on a high‑end Linux machine, suggesting future optimization work.

When to adopt Ledge.sh

DevOps playbooks – Store API keys in profiles, run deployment scripts, and keep logs in the same note.
Data analysis – Mix SQL, Python, and shell pipelines without leaving the notebook.
AI‑augmented workflows – Embed prompt blocks that send queries to Claude or other agents and capture responses inline.
Remote‑first teams – Use the SSH‑backed server model to keep a single source of truth across laptops, phones, and CI runners.

Getting started

# Install the server component on any machine you want to host notes
curl -fsSL https://ledge.sh/server.sh | sh

# Install the desktop client (macOS, Linux, Windows via WSL) – see https://ledge.sh/docs/installation

After installation, create a Markdown file, add a fenced block, place the cursor inside the block, and press ⌘↩. The output will appear below the block, and the note will automatically sync to the configured server.

Final thoughts

Ledge.sh transforms plain Markdown into a live, reproducible notebook that works across desktop, mobile, and remote hosts, while keeping notes as simple files that can be version‑controlled with Git. Its design choices—persistent per‑note shells, secure profiles, and agent integration—address many pain points of existing notebook and run‑book tools, making it a compelling option for developers, DevOps engineers, and AI‑augmented workflows.