Agents and Ledge
Ledge is built to be worked by AI agents as well as by you. An agent CLI such as Claude Code can read, search, create, and edit your notes through Ledge's MCP server. A terminal launched inside a note already knows which note it is in, and a prompt code fence turns a paragraph of instructions into a runnable block.
Connect an agent
Ledge ships an MCP server. ledge mcp serves it on stdio, so install the ledge command first (see The ledge CLI). Any MCP-speaking agent can use it. For Claude Code it is one line, in your own terminal:
claude mcp add ledge -- ledge mcpThe server exposes eleven tools:
| Read | Write |
|---|---|
list_workspaces, list_notes, read_note, search_notes, backlinks, tags, settings | create_note, daily_note, append_note, edit_note |
Notes are addressed by title, which survives renames, so an agent's references do not go stale. Every tool goes through the same store and the same path guards as the app.
Two boundaries hold in every case: there is no delete tool, and locked notes refuse their bodies to every agent surface (see Note Locking).
Agents and folders
Two notes in different folders may share a title, so list_notes tells them apart: every row says which folder its note is in, and a note at the top level says nothing. Read a note by that title and the answer names its folder too.
Listing, searching, and the tag tools take a folder to narrow to one, and it covers the folders inside it as well. The tools that address a note by title take one too, which is how an agent says which of two notes sharing a title it means. create_note takes one to place a new note, creating the folder if it is new, and daily_note takes one for the day it creates today's note.
Without a folder a new note lands at the top level of the workspace, which is where your own New Note puts one. There is no tool for moving a note afterwards, and none for renaming or deleting a folder: filing is yours, in the sidebar (Notes and Workspaces).
Agents know which note they are in
Every shell a note spawns carries two environment variables: LEDGE_NOTE, the note's file, and LEDGE_WORKSPACE, its workspace folder. An agent launched in a note's terminal drawer picks these up through the MCP server:
read_notewith no arguments reads the note the terminal belongs to.append_noteandedit_notedefault to that note.create_notelands in its workspace, at the top level unless it names a folder.
So "summarize this note" or "add a TODO section here" needs no explanation of what "this" means. Open the note you are working in, press ⌃` for its terminal, start your agent, and talk about "this note" and "this workspace" in plain words.
Prompt fences
A fenced block whose language is prompt is an agent run. Write instructions in it and press ⌘↩. The block's text is piped to the agent CLI in one-shot mode, and the output streams into the panel below like any other run (Running Code).
A prompt fence in a release note, run with ⌘↩:
Notes for the 2.4.2 release, kept as the rollout moves.
Summarize this note in one sentence for the deploy channel.
The answer streams into the panel beneath it. Instructions can also change things: "append a Next steps section to this note", or "create a note titled Retro from what we discussed above".
The block runs from the note's own shell, so the agent inherits the note's cwd, env, and the environment variables above.
Two things to expect. There is a pause before the answer appears, because one-shot mode thinks first and prints once. And since nobody is present to answer follow-up questions, the agent is instructed to act and report rather than ask.
By default the fence runs Claude Code (claude -p) with Ledge's own tools pre-authorized, because a non-interactive run has no one to click "allow". The command is an interpreter entry in Settings (⌘,) under blocks.interpreters, key prompt. Point it at any CLI that reads its prompt on stdin to switch agents.
A daily template carrying a prompt fence such as Summarize [[{{yesterday}}]] gives every day's note a one-keystroke briefing (see Daily Notes and Templates).
What agents cannot see
Agents see the titles, bodies, tags, and links of ordinary notes. They can read the manual inside the app too, so "check the Ledge docs" is a fair instruction.
They never see the body of a locked note. Reads refuse with an explanation, searches skip locked notes and report how many they skipped, and listings flag them so an agent can plan around it.
Settings are readable but not writable. The settings tool shows an agent your settings.jsonc with its comments, so it can answer "which python is that block using" from your actual configuration and name the line to change. Making the change is yours, in the app (⌘,), and it applies at the next launch.
Deletion is yours alone, in the app, where the trash and Undo live.
The manual for LLMs
An agent without Ledge's MCP server can still read this manual. The site serves it in forms made for LLMs, built from the same pages you are reading, so they change when the docs do:
- /llms.txt lists every page with a one-line description.
- /llms-full.txt is the whole manual in one Markdown file.
- Any page with
.mdadded to its address is that page as Markdown, for example /docs/agents-and-ledge.md.
To give an agent the full manual in one step:
curl -s https://ledge.sh/llms-full.txt