The notebook that runs_
Latency spike — 31 Jul
cwd: ~/Projects/api
---
p99 alarm at 09:12. Working it from this note — playbook in Oncall handbook. #api
kubectl top pods -n api --sort-by=cpu | head -4
One replica is hot: x2vn at 912m CPU, its siblings near 140m.
from statistics import quantiles
q = quantiles([float(x) for x in open("p99_samples.txt")], n=100)
print(f"p50 {q[49]:.0f} ms · p99 {q[98]:.0f} ms")Confirmed: p99 at 2.1 s against the 120 ms baseline. Restarted x2vn at 09:31; recovering.
Write an incident update from this note for #api-oncall
Ledge is a Markdown notebook for developers and DevOps. Write a note, press ⌘↩ on a code block, and its output streams in beneath it. In your shell, in your project, on your machine, or on a server you point it at.
Each note has its own shell
Shell blocks run in a persistent shell that belongs to the note. A cd, an exported variable, or an activated virtualenv carries into the next run.
- ⌘↩ runs the block under the caret. Output streams in beneath it.
- ⇧⌘↩ sends the block to the note's terminal drawer, a second shell you can keep typing in.
- A running block takes input. Answer a
sudopassword or a[y/N]in the output panel. cwd:andenv:in the frontmatter set where the note's shells start and what they carry.norunon a fence takes the Run button away. Use it for a command you are quoting, not running.
Invoice rounding bug
Totals drift by a cent on partial refunds. Repro first. #billing
cd services/billing && source .venv/bin/activate
pytest -q --tb=no tests/test_refunds.py
Keep your notes on a server
Point Ledge at a machine over ssh and the notes live there. The server holds the files and runs the shells. The app on your Mac is the window onto it.
- No account, no service, and no port to open. The only thing between you and the server is ssh.
- Shells and running blocks belong to the server. If the connection drops, they keep going, and their output arrives when it returns.
- Your Mac, your phone, and a second window can all be on one server at once, each with its own tabs.
- Sign in with an ssh key, or with a password kept in your Mac's keychain. Ledge pins the server's host key and refuses any other.
- Install with
bun add -g ledge-server, or run the Docker image.ledge-server backup-pathsprints what to back up.
cwd: ~/api
---
Cut 2.4.2 from the server, not the laptop. The build takes a minute.
make release
The shell ran on the server the whole time. The wire is what dropped.
The same notes on your phone
Ledge runs on iPhone and iPad as a window onto the same server. The phone holds no notes. It reads, edits, and runs what is on the server.
- Read, edit, and create notes with live preview. Search, tags, backlinks, daily notes, and wikilinks all work.
- Tap Run on a block and it runs on the server. Switch apps and it keeps running. The output is waiting when you come back.
^C,^D, Escape, and the arrow keys sit above the keyboard, so you can interrupt a command or quit a pager.- Pairing uses a key made in the Secure Enclave that never leaves the phone. Its line in
authorized_keyscan speak to Ledge and nothing else. - Locked notes unlock with the passphrase. The phone stores none of it.
Release 2.4.2
Image pushed from the server. Watch the rollout from the train.
kubectl rollout status deploy/api
Run blocks on other machines
Add a host: line to the frontmatter and every run in the note happens over ssh on that host. The note itself stays where it is.
- Declare several hosts and Ledge asks which one on every run. Enter repeats your last pick.
- Mark a block
confirmand Ledge shows the code, names the machine, and asks before running it. - Authentication is your own
ssh. Keys, agents,~/.ssh/config, and 2FA work as they do in a terminal. - The note's
cwdandenvtravel with the run. Profiles and secrets never do. python,node, and other interpreted blocks run on the host too, with a per-machine interpreter override in Settings.
cwd: ~/Projects/api
host: staging, deploy@prod
---
Stale session keys after the 2.4.1 deploy. Flush staging, verify, then prod.
redis-cli -n 2 flushdb
Put notes side by side
⌘D splits the view left and right, ⇧⌘D top and bottom, and either side can split again. Each pane has its own tabs.
- Every note keeps its own shell, so two panes are two working environments. A run keeps streaming in the pane you left.
- Drag a tab to another pane. It keeps its caret, scroll position, undo history, and any output still streaming.
- ⌃Tab cycles tabs. ⌃1 to ⌃9 jump to one by position.
- Each workspace saves its layout and restores it at the next launch. ⌘1 to ⌘9 switch workspaces, layout and all.
- One terminal drawer spans the window and follows the focused note.
Tax backfill
Every invoice gets a tax_rate before the flag flips.
python3 backfill_tax.py
Secrets stay out of your notes
A profile is a named file of environment variables kept outside your notes folder. A note that names it gets the variables in its shells. The note carries only the name.
profile: deployin the frontmatter reads~/.config/ledge/profiles/deploy.env, a plain dotenv file readable only by you.- Notes get synced, backed up, and read by agents. A profile value stays on the machine.
- Any number of notes can share one profile. An
env:line overrides a value for one note. - A built-in editor shows the values masked, with one toggle to reveal them.
envFile: .envloads the project's own dotenv for everything that is not a secret.
cwd: ~/Projects/api
profile: deploy
---
Backup restore drill. The AWS keys come from the deploy profile.
aws s3 ls s3://ledge-api-backups/nightly/ | tail -2
Built to be worked by agents
Ledge ships an MCP server. claude mcp add ledge -- ledge mcp connects Claude Code, and any MCP agent can read, search, create, and edit your notes through it.
- Notes are addressed by title, which survives renames, so an agent's references do not go stale.
- A terminal opened inside a note knows which note it is in. "Add a TODO section here" needs no explanation.
- A
promptcode block is a runnable block. ⌘↩ pipes it to the agent and the reply streams in beneath it. - Agents can read your settings and the manual, so "check the Ledge docs" is a fair instruction.
- There is no delete tool, and locked notes refuse their bodies to every agent.
Release 2.5.0
Tag after the migration bake. Checklist in Release runbook. #release
git log --oneline v2.4.1..HEAD | head -3
9f31c22 storage: chunked uploads for assets over 50 MB 41b0a07 api: rate limit per token, not per IP c2ade19 fix: retry idempotent writes on 5xx
Lock the notes that matter
Locking encrypts a note's body on disk behind a passphrase. Agents never see it, sync services carry ciphertext, and reading it requires an unlock.
- The title, frontmatter, and tags stay visible, so links and navigation keep working.
- Search and backlinks skip locked bodies and say how many notes they skipped.
- One passphrase covers every locked note. ⌘L relocks, and the vault relocks itself after 15 minutes idle.
- Images pasted into a locked note are sealed with it.
- A locked note is self-contained. On another machine it unlocks with the passphrase alone. There is no recovery.
This note is locked. Its body stays sealed on disk, away from agents and search, until you unlock.
Unlock Notes…Sync with anything, share with git
Notes are plain files in ordinary folders, so syncing them is syncing a folder: iCloud Drive, Dropbox, git, Syncthing, or whatever you already use. There is no database on the side.
- Ledge watches the folder and follows outside changes live, even in an open note.
- Push a workspace to a git remote and the people you work with clone it. Each clone attaches as an ordinary workspace, and a pull shows up in the sidebar with nothing to refresh.
- One note changed in two clones is a git conflict like any other. If a pull rewrites a note you have open, your version keeps the file and the other goes to the workspace trash.
- A Sync note in the workspace pulls, commits, and pushes with one ⌘↩.
- Profiles never enter the folder, locked notes travel as ciphertext, and the trash stays out of git.
Sync
This workspace is a repo. One run commits and pushes every note in it.
git add -A && git commit -m "notes $(date +%F)" || true git pull --rebase && git push
The notes app underneath
Everything else you expect from a notes app is here.
Your languages
Python, Node, Ruby, and PHP run out of the box. A redis block feeds redis-cli, pointed at staging or prod by the note's REDIS_URL. TypeScript uses the Bun runtime bundled with the app, so ts blocks run with nothing installed. Adding an interpreter is one line in Settings.
A workspace is a folder
Attach a project folder and its Markdown files become notes where they are, running their blocks in the project. ⌘1 to ⌘9 switch workspaces, and each keeps its own pane layout. Closing one detaches it and touches no files.
Live preview
Syntax hides away from the caret: **bold** shows bold, links show their label, tables and images render in place, and a checkbox is clickable. Move the caret in and the exact characters come back. One setting shows every character all the time.
Paste anything
Copy part of a web page, a Slack thread, or a Google Doc, and ⌘V pastes it as Markdown: headings, lists, checkboxes, links, and tables included. ⇧⌘V pastes the plain text. An image on the pasteboard lands in the workspace as a file, rendering in place; pasted into a locked note, it is encrypted from the first byte.
Daily notes and templates
⌘J opens today's note, stamped from your daily template. Templates are ordinary notes with {{date}} and {{yesterday}} tokens, and one carrying a prompt block gives every morning a one-keystroke briefing.
Find your way back
⌘P opens a note by title; type # for full-text search. Wikilinks address titles, so a retitle never leaves a stale link. Backlinks and outline each get a panel.
Tags and favorites
Tag a note with inline #hashtags or a frontmatter tags: line, and ⌥⌘T lists every tag with its count. Press f on a note's row, or click its star, and it sits in a Favorites section at the top of the sidebar, however deep in a folder it lives. Both are frontmatter, so they travel with the file.
Deleting is undoable
⌫ moves a note to the workspace trash and shows an Undo strip. The Trash section in the sidebar holds it for 30 days, where r restores it and permanent deletion asks first.
The ledge CLI
Lists, reads, searches, creates, and appends from any terminal, and the app follows along live. Results go to stdout, everything conversational to stderr, so pipes stay clean, and --json switches any verb to machine-readable output.
The notebook that runs code_
Free and open source under Apache-2.0. No account, no telemetry, no database on the side. Your notes are Markdown files on your Mac or on a server you run, and they stay yours.