# Agents and Ledge

Source: https://ledge.sh/docs/agents-and-ledge

> Ledge is built to be worked by AI agents as well as by you.

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](https://ledge.sh/docs/the-ledge-cli)). Any MCP-speaking agent can use it. For Claude Code it is one line, in your own terminal:

```sh
claude mcp add ledge -- ledge mcp
```

The 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](https://ledge.sh/docs/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](https://ledge.sh/docs/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_note` with no arguments reads the note the terminal belongs to.
* `append_note` and `edit_note` default to that note.
* `create_note` lands 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](https://ledge.sh/docs/running-code)).

A prompt fence in a release note, run with ⌘↩:

```prompt
Summarize this note in one sentence for the deploy channel.
```

Output:

```txt
2.4.2 ships the retry-queue fix and invoice export; staging
has soaked clean for two days and prod flips tomorrow 09:00.
```

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](https://ledge.sh/docs/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](https://ledge.sh/llms.txt) lists every page with a one-line description.
* [/llms-full.txt](https://ledge.sh/llms-full.txt) is the whole manual in one Markdown file.
* Any page with `.md` added to its address is that page as Markdown, for example [/docs/agents-and-ledge.md](https://ledge.sh/docs/agents-and-ledge.md).

To give an agent the full manual in one step:

```sh
curl -s https://ledge.sh/llms-full.txt
```