Build with a coding agent
Claude Code, Codex or Cursor can write an add-on with you. Every add-on ledgekit makes carries a brief the agent reads first, and an MCP server that gives it the whole loop as tools, including pictures of what it built.
What ledgekit writes
ledgekit new writes these with the rest of the add-on. For an add-on that already exists, run ledgekit agent in its folder.
| File | Read by | What it is |
|---|---|---|
AGENTS.md | Codex, Cursor and most agents | The brief: what an add-on is, the loop after every change, the rules, the placeholders to replace. Yours to edit; only --force writes it again |
CLAUDE.md | Claude Code | Points to AGENTS.md, so there's one brief |
.cursor/rules/ledgekit.mdc | Cursor | The same brief, as a rule for every file |
.mcp.json | Claude Code | Starts ledgekit mcp for this folder |
.cursor/mcp.json | Cursor | The same |
They stay on your Mac: the add-on's .gitignore lists them, ledgekit validate refuses them if they'd be committed, and LedgeAddOns refuses them in a pull request. The MCP files hold absolute paths, so run ledgekit agent again after moving the folder or LedgeKit.
Connecting the agent
- Claude Code. Open the add-on's folder and run
claude. It reads CLAUDE.md, and the first time asks to use the ledgekit server. - Cursor. Open the folder. The rule applies to every file, and the server is in
.cursor/mcp.json. - Codex. It reads AGENTS.md itself. Register the server once, and it finds the add-on from the folder Codex runs in:
codex mcp add ledgekit -- $(which ledgekit) mcpThe tools
| Tool | Does |
|---|---|
ledgekit_doctor | Swift and ledgekit versions, the add-on's manifest, and whether Ledge's developer mode is on. Run first |
ledgekit_new | A new add-on beside the current folder |
ledgekit_test | swift test |
ledgekit_build | The .ledgeaddon |
ledgekit_check | The check, with an optional script and capabilities to deny, returning its JSON report |
ledgekit_run | Installs it in your Ledge and says whether it started |
ledgekit_shots | Ledge's pictures of each surface, returned as images the agent can look at: the narrowest widths beside a camera and every activity shape. all: true adds the rest |
ledgekit_validate | The Store's checks, with submit: true before a pull request |
ledgekit_lint | What review would send back, as JSON with file and line. The brief tells agents to fix findings, never to waive them |
ledgekit_update | Moves the add-on to this ledgekit's LedgeKit; raise: true moves kit.minAPI too |
ledgekit_docs | The brief: the rules and the loop |
Every tool runs the same ledgekit command you would, so an agent and a person get the same answers.
The loop the brief asks for
A green build isn't the end. After every change: the tests, the build, a check that reports no problems, then the shots, looked at, because a surface Ledge accepts can still look wrong. Before saying it's ready, validate; before a pull request, validate --submit.
Working with it
- Say which surface you want and what it shows: “a widget with today's battery cycles and a button to refresh” beats “a battery add-on”.
- Turn on developer mode before asking for shots, or the agent can only check, not look.
- Add what your add-on needs the agent to know to AGENTS.md: an API it calls, a decision you made, a surface you don't want.
- Read what it wrote before you submit. You submit it, and review reads it.