Building with a coding agent

If you are writing your plugin with Claude Code, Cursor, Copilot or anything like them, your agent does not need this website. It needs two files sitting in your project.

The two files

AGENTS.md 27.9 KB Everything a plugin has to obey, in one document: every method with the permission it needs, all the permissions, the manifest fields, the events, the limits, the packaging rules, and the mistakes that are easy to make. Built from the Tintero source, so it cannot describe an API that no longer exists. tintero-plugin-sdk.d.ts 1,547 lines The TypeScript definitions. Covers the whole API and the manifest, including the shape of every object you get back. An agent with this can check its own work as it goes, and so can your editor.

Drop both into your project root:

curl -O https://developer.tintero.app/AGENTS.md
curl -O https://developer.tintero.app/tintero-plugin-sdk.d.ts

Most agents pick up a file called AGENTS.md from the project root without being told. If yours does not, point it at the file in your first message.

What a good first prompt looks like

Vague prompts get you plugins that install and then sit there. Say where it appears, what data it touches, and what it does with it:

Read AGENTS.md. Build a Tintero plugin that shows a sidebar panel listing every
character in the project, sorted by how often their name appears in the manuscript.

- Sidebar surface only.
- Read-only: no writes to the project.
- Refresh when the active document changes.
- Package it as plugin.zip with a Makefile target.

Three things are worth spelling out, because they decide the manifest:

• Where it appears. Sidebar panel, full app view, or nowhere at all. See Surfaces.
• Whether it writes. An agent that is not told will ask for write permissions it does not need, and everybody who installs it will see them.
• Whether it goes online. net.fetch needs a list of hosts alongside it, and asking for it without one fails the install.

What to check before you trust the result

An agent working from AGENTS.md gets the shape right. These are the parts worth reading yourself, because they go wrong quietly rather than loudly.

The permission list. Open plugin.json and read scopes. Every line there turns up in the dialog people approve, and agents tend to add permissions just in case. Each one is another reason to say no, so if nothing in the code uses it, delete it.

Rewriting is not creating. project.write.fileContent rewrites a file that already exists. Making a new one needs project.write.files or project.write.docs . This is the single most common mix-up, and it fails while running rather than at install.

JSON.stringify on writes. Document content is a string going in and a string coming out, but the converters hand you objects. A missing stringify is a rejected write.

Loops over the whole project. Reading every file in a long manuscript is the one thing that runs into 100 calls / 1 s. Keep results in tintero.storage and refresh when project.changed fires instead of checking on a timer.

That it installs at all. Load the zip through Settings → Plugins → Load local plugin (dev) on a real project. The installer is strict about paths, the plugin id and the ui.sidebar permission for sidebar plugins, and it does tell you which field is wrong.

Keeping the file current

AGENTS.md is rebuilt every time this site is, from the same source as the API and permission pages. If Tintero gains a method or moves a permission into another risk band, the file follows.

Nothing tells your copy, though. Download it again when you come back to a plugin after a while away, and compare the counts at the top of the API reference against the ones in your file.

If you would rather not use an agent

Nothing here assumes you are. Your first plugin is the same material, walked through by hand, and it takes about ten minutes.