Coding agents

Macotron has no plugin editor of its own. It is built for a coding agent to write plugins for you: open the workdir in Claude Code, Codex, or another agent, say what you want, and the agent writes a .js file that Macotron loads.

cd ~/Macotron
claude
> Add a plugin that shows my battery percentage in the menu bar
  and turns red under 20%.

What Macotron writes for agents

Every time Macotron starts, it writes two files into the workdir:

• AGENTS.md: what the folder is, the plugin rules, the API in brief, the log commands, and how to check a plugin. Codex, Cursor, and most other agents read this file.
• CLAUDE.md: one line that points Claude Code at AGENTS.md.

Both files start with <!-- DO NOT EDIT — Macotron overwrites this file. -->. Macotron rewrites them on every launch, so your edits would be lost. Put your own notes in README.md instead; Macotron writes that file once and then leaves it alone.

Macotron also copies the full typed API to .cache/macotron.d.ts. AGENTS.md tells the agent to read it before it guesses at a call. The .gitignore Macotron writes keeps AGENTS.md, CLAUDE.md, and .cache/ out of git.

Start an agent from Settings

Open Settings → Plugins and select Create. The menu lists:

• Agents: Claude Code, Codex, Cursor CLI, pi.dev, and Gemini CLI. Macotron opens a Terminal window in the workdir and starts the agent. You install the agent yourself; if it is missing, Terminal says so.
• Editors: Cursor, Visual Studio Code, Zed, Xcode, and Terminal, opened on the workdir.
• Empty Plugin…: type a title, and Macotron writes a starter file with a header and one launcher command, then opens it.
• Open Plugins Folder: shows the folder in Finder.

A good loop

1. Turn on Enable Hot Reloading in the Macotron menu, so each save loads at once. Turn it off when you finish. See Security for why it is off by default.
2. Ask the agent for one feature at a time.
3. Have the agent check its work with /Applications/Macotron.app/Contents/MacOS/Macotron --check plugins/name.js. AGENTS.md tells it how.
4. If something does not work, ask the agent to read the log. AGENTS.md includes the log stream and log show commands. Plugins that log their steps are much easier to fix; see Logging.
5. Try the result. Open Settings → Plugins to see the new hotkeys, commands, and options.

Git

When Apple's developer tools are installed, Macotron runs git init in the workdir. It never commits. AGENTS.md tells agents to commit often on main and never to commit secrets, so you can undo a bad change with git. Git is optional; Macotron works without it.

Things to tell your agent

AGENTS.md already covers these, but they are the most common mistakes:

• Use only macotron.* and tools that ship with macOS. No Homebrew, npm, or pip.
• API keys go in a password option or macotron.keychain, not in the source or settings.json.
• Configure plugins through options in macotron.plugin(), not by editing pluginSettings in settings.json.
• Save user choices in localStorage, because plugin variables reset on every reload.

See also

• Writing plugins
• Plugin settings
• The AGENTS.md that Macotron writes