Building PodoLay plugins with AI agents

How to have an AI coding agent — Claude Code, Codex, Antigravity, Cursor or VS Code (GitHub Copilot) — build a PodoLay plugin, step by step: installing the tools, creating your first plugin folder, and writing your first request. You can follow it even if you have hardly used a terminal. Agent tools change often — install steps and pricing are as of October 2026; if something differs, follow the agent's official instructions.

Contents

1. How it works
2. Choosing an agent
3. Common setup — terminal, Node.js, Chrome
4. Downloading the SDK
5. Creating your first plugin folder — init
6. Claude Code
7. Codex (OpenAI)
8. Antigravity CLI (Google)
9. Cursor
10. VS Code + GitHub Copilot
11. Your first request — what to say
12. What you do yourself
13. Troubleshooting

1. How it works

The PodoLay plugin SDK is built so that an AI agent can write, test and fix a plugin on its own.

• When node tools.mjs init creates a plugin folder, it also writes an instruction file for agents, AGENTS.md: the plugin API rules, the commands to use, and what to verify before saying the work is done. Most agents (Codex, Antigravity, Cursor, Copilot) read this file automatically when you open the folder. Claude Code reads CLAUDE.md instead — the CLAUDE.md the SDK writes is the single line @AGENTS.md, so it ends up reading the same instructions.
• After writing code, the agent checks its own work with check (validation without the editor) and node test.mjs (tests against a mock editor), then runs the same tests in the sandbox editor — the real editor, with no sign-in and nothing saved to the server — and takes page screenshots (PNG) to check the result visually.
• You say what to build, approve the commands the agent asks to run, look at the result in the browser, and upload the plugin to the portal when it is done.

Work folder (e.g. Documents/podolay)
├── podolay-plugin-sdk-1.6.2-en/   ← the unzipped SDK (tools.mjs, guides, examples) — the folder name carries the SDK version
└── my-plugin/            ← your plugin, created by init — open the agent here
    ├── podolay-plugin.json   manifest
    ├── main.js               plugin code
    ├── AGENTS.md · CLAUDE.md agent instructions
    ├── test.mjs              tests
    └── podolay-plugin.d.ts · jsconfig.json  type definitions (autocomplete)

2. Choosing an agent

Any of them works. If you already use one, use that.

• Terminal agents (Claude Code, Codex, Antigravity) are good at running commands, reading the output and working on their own for a long time. All of the SDK's tests and sandbox controls are terminal commands, so they fit well.
• Editor agents (Cursor, VS Code) show the code on screen, which makes it easier to follow along. They run terminal commands too (and ask first).

3. Common setup — terminal, Node.js, Chrome

3.1 Opening a terminal

• macOS: press ⌘ Space, type "Terminal" and open it.
• Windows: open "PowerShell" or "Terminal (Windows Terminal)" from the Start menu. If the prompt starts with PS, like PS C:\Users\you>, it is PowerShell.

Copy the commands in this guide one line at a time into the terminal and press Enter. Text after # is a comment; you don't need to type it.

3.2 Installing Node.js (18 or later, LTS recommended)

The SDK tools run on Node.js. Nothing else is needed — the SDK has no other dependencies.

• macOS: download the LTS installer (.pkg) from https://nodejs.org and open it. With Homebrew: brew install node.
• Windows: download the LTS installer (.msi) from https://nodejs.org and open it (keep the defaults). Or, in PowerShell:

  winget install OpenJS.NodeJS.LTS

After installing, open a new terminal and check the version:

node -v      # something like v22.x.x is fine (v18 or later)

If node is not found, close the terminal and open a new one. If that doesn't help, restart your computer.

3.3 Google Chrome

Used to open the sandbox editor in a browser. Skip this if you already have it — https://www.google.com/chrome/. (Running the editor without a window, --headless, needs Chrome and the Playwright package — the agent will tell you if it needs them.)

4. Downloading the SDK

1. Create a work folder, for example podolay in your Documents folder.
2. Download podolay-plugin-sdk-<version>-en.zip (e.g. podolay-plugin-sdk-1.6.2-en.zip) with Download SDK at the top of the developer docs.
3. Move the zip into the work folder and unzip it — double-click on macOS, right-click › Extract All on Windows. You get a podolay-plugin-sdk-<version>-en folder (e.g. podolay-plugin-sdk-1.6.2-en). Replace <version> in the commands below with that version.

Or in the terminal — the address without a version, podolay-plugin-sdk-en.zip, is always the latest version:

# macOS
mkdir -p ~/Documents/podolay && cd ~/Documents/podolay
curl -LO https://podolay.com/downloads/podolay-plugin-sdk-en.zip
unzip podolay-plugin-sdk-en.zip

# Windows (PowerShell)
mkdir $HOME\Documents\podolay; cd $HOME\Documents\podolay
Invoke-WebRequest https://podolay.com/downloads/podolay-plugin-sdk-en.zip -OutFile podolay-plugin-sdk-en.zip
Expand-Archive podolay-plugin-sdk-en.zip -DestinationPath .

Check that it worked (in the work folder):

node podolay-plugin-sdk-<version>-en/tools.mjs --version
# PodoLay plugin SDK 1.6.0 (API 1.6)

5. Creating your first plugin folder — init

Before opening an agent, create the plugin folder with the SDK's init. This one command creates the plugin skeleton together with the agent instructions (AGENTS.md, CLAUDE.md), tests and type definitions.

# in the work folder (podolay)
node podolay-plugin-sdk-<version>-en/tools.mjs init my-plugin --kind command --id com.myname.myplugin --name "My Plugin"

When it finishes it prints Created: my-plugin (command, com.myname.myplugin) — PodoLay plugin SDK 1.6.0 (API 1.6) and the next steps.

Don't run the agent's own /init. Claude Code and Codex also have an /init command, but that one makes the agent scan the project and rewrite CLAUDE.md or AGENTS.md. The SDK's init already wrote instructions made for PodoLay, so you don't need it, and running it can change or overwrite them. If you ran it by mistake, restore the SDK section with node ../podolay-plugin-sdk-<version>-en/tools.mjs upgrade . (if AGENTS.md was overwritten, delete it first).

Now open your agent in the my-plugin folder. Read only the section for the agent you use.

6. Claude Code

Anthropic's terminal coding agent. You need a Claude Pro, Max, Team or Enterprise subscription or an API (Console) account — the free claude.ai plan doesn't include it. If the terminal feels unfamiliar, the desktop app (claude.com/download) gives you the same Claude Code.

Install

# macOS · Linux
curl -fsSL https://claude.ai/install.sh | bash
# or Homebrew
brew install --cask claude-code

# Windows (PowerShell) — no administrator rights needed
irm https://claude.ai/install.ps1 | iex
# or
winget install Anthropic.ClaudeCode

On Windows, installing Git for Windows lets Claude Code run commands more reliably (without it, it uses PowerShell). When the install finishes, open a new terminal and check with claude --version.

Start and sign in

cd ~/Documents/podolay/my-plugin      # Windows: cd $HOME\Documents\podolay\my-plugin
claude

The first time, a browser opens for sign-in. When it asks whether to trust the folder, allow it.

Check that it read the instructions — type /memory in the chat to see the instruction files it loaded (CLAUDE.md and the @AGENTS.md inside it). Or ask "Summarize the rules in AGENTS.md in three lines."

Approving commands — Claude Code asks before editing files or running commands (node …). Read what it wants to do and approve it. To stop it asking about the same kind of command every time, choose "Yes, and don't ask again". It also asks the first time it reads the guides in the SDK folder (../podolay-plugin-sdk-<version>-en).

Tips

• dev, which starts the sandbox editor, keeps running. Claude Code runs it in the background (AGENTS.md tells it to). If you'd rather start it yourself, run node ../podolay-plugin-sdk-<version>-en/tools.mjs dev . --open in another terminal and tell the agent "I started the dev server".
• If the conversation gets long, start fresh with /clear — it reads the instructions again.

7. Codex (OpenAI)

OpenAI's terminal coding agent. Sign in with a ChatGPT Plus, Pro, Business, Edu or Enterprise account, or use an API key.

Install

# macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# or Homebrew
brew install --cask codex
# or npm (you already have Node.js)
npm install -g @openai/codex

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Start and sign in

cd ~/Documents/podolay/my-plugin
codex

The first time, choose Sign in with ChatGPT and sign in in the browser.

Instructions — Codex reads AGENTS.md in the folder automatically. Check with "If you read AGENTS.md, summarize the rules you will follow." Don't run Codex's /init — it creates a new AGENTS.md (section 5).

Approving commands — /permissions sets what Codex may do without asking (edit files, run commands). Start with it asking. The test commands (check, test, run) connect to the dev server on your computer (localhost:5199). If Codex reports that its sandbox blocks the connection, approve that command, or start the dev server yourself (see the tip in section 6) and ask again.

8. Antigravity CLI (Google)

Google's terminal coding agent (agy), the successor to Gemini CLI — on June 18, 2026 Google replaced Gemini CLI with Antigravity CLI for free-tier and Google One users. You sign in with a Google account.

Install

# macOS · Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# or (macOS) Homebrew
brew install --cask antigravity-cli

On Windows, follow the install steps in the official Antigravity documentation (https://antigravity.google). The program is installed into ~/.local/bin — if agy --version doesn't work in a new terminal, follow the installer's instructions for adding that folder to your PATH.

Start and sign in

cd ~/Documents/podolay/my-plugin
agy

A browser opens for Google sign-in.

Instructions — Antigravity reads AGENTS.md (and GEMINI.md) in the folder. Check with "If you read AGENTS.md, summarize the rules"; if it says it didn't, start your first request with "Read AGENTS.md first and follow it."

Approving commands — it asks before running commands. You can turn on automatic approval in its settings, but start with it asking.

Still using the old Gemini CLI? By default it reads only GEMINI.md. Create .gemini/settings.json in the plugin folder with { "context": { "fileName": ["AGENTS.md"] } } (older versions: "contextFileName": "AGENTS.md"), or tell it to read AGENTS.md in your first request.

9. Cursor

A code editor app with a built-in AI agent (based on VS Code).

Install — download it from https://cursor.com, install it and sign in with a Cursor account.

Open the folder — use File › Open Folder… to open the my-plugin folder (the plugin folder, not the work folder or the SDK folder). Cursor applies AGENTS.md automatically when it sits at the top of the opened folder.

Using the agent — open the AI chat panel on the right and set the mode to Agent. It edits files as you ask and has you press Run before each terminal command.

If the instructions aren't picked up — occasionally AGENTS.md is left out. Put @AGENTS.md at the start of your first request to make sure it is included.

Tip — thanks to jsconfig.json and podolay-plugin.d.ts, typing podolay. in main.js shows API autocomplete and descriptions.

10. VS Code + GitHub Copilot

Install

1. Install VS Code from https://code.visualstudio.com.
2. In Extensions on the left, find and install GitHub Copilot, then sign in with your GitHub account (a Copilot plan is required — the free plan has low usage limits).

Open the folder — use File › Open Folder… to open the my-plugin folder.

Using the agent — open the Copilot chat panel and choose the Agent mode. It edits files as you ask and asks before running terminal commands.

Instructions — VS Code automatically attaches the AGENTS.md at the top of the workspace to chat requests (setting chat.useAgentsMdFile, on by default). If it doesn't seem to read it, check that this setting is on and start your first request with "Read AGENTS.md first."

11. Your first request — what to say

Tell the agent what to build (who uses it and for what), how it is invoked (menu, shortcut, context menu, tool), and what counts as done. For example:

Read AGENTS.md first and follow it.
Make a command that numbers the selected objects 1, 2, 3 …
- It appears as 'Number objects' in the object context menu, with the shortcut ⌥⇧N.
- Each number is white text in a small red circle at the object's top-left corner, all in a single Undo step.
- Skip locked objects.
Write tests in test.mjs, make check and test pass, then take a shot of the page in the sandbox editor and show me.

Read AGENTS.md first and follow it.
Make a 'QR code' graphic that you draw with a tool, with the URL (text) and the color editable in the Inspector.
Keep render a pure function and compute the QR code yourself without external libraries. When done, check it with shot.
Try the Inspector fields with p.inspect in test.mjs, and check the handle positions with shot --ui while the object is selected.

Tips that help:

• One thing at a time. Split a big plugin: "first just the manifest and an empty command", "next the tests", and so on.
• Ask it to verify. "Only say you're done after check has 0 errors, node test.mjs passes, tools.mjs test passes and you've checked the shot" — AGENTS.md says this too, but saying it makes sure.
• Have it read the docs when unsure. "Read §9 of API.md and tell me which properties tx.set can change" — API.md and README.md are in the SDK folder (English versions in en/).
• Paste errors as they are. If something looks wrong in the browser, write down what you clicked and what you saw. The editor's Plugins menu › Log helps too.

12. What you do yourself

The agent does most of the work, but these are yours:

1. Look at it — click around in the sandbox editor (browser) the agent opened. Tools you drag with the mouse, Inspector fields and panel screens need human eyes. The agent can look ahead too — changing Inspector values with the mock editor's p.inspect, handle positions with shot --ui, and panel html with podolay-ui-stub.js in Playwright (developer guide §8.8).
2. Apply as a developer — under Portal › My Account › Developer. Once approved, you can test in dev mode on your own documents and upload (sandbox testing works without applying).
3. Upload — upload the zip made by node ../podolay-plugin-sdk-<version>-en/tools.mjs pack . with Portal › Developer › Upload a version, then Request review. Before uploading, check that you raised version in the manifest. If you ship a guide and samples (help, API §3.8), the agent can write the guide (docs/*.md) and sample files (samples/), but sample layouts are yours: share the layout (no recipients) to make a copy in your Shared folder, then give its id to the agent to put in help.layouts.
4. New SDK — when dev or check says a new SDK is out ("A new SDK is available: …"), unzip the new zip next to the current SDK folder (in the work folder) and, from the plugin folder, run the new SDK folder's tool: node ../podolay-plugin-sdk-<new version>-en/tools.mjs upgrade . (the SDK paths in the agent instructions and test imports move to the new folder). The download address and commands are spelled out in the developer guide §8.9.1 and in the upgrade section of the plugin folder's AGENTS.md — you can also just ask the agent to "upgrade the SDK".

13. Troubleshooting

The full development workflow is in the developer guide, and every API is in the API reference.