What I learned from 45 Payo releases
I released the first version of Payo, my CLI for AI coding assistants, on 7 June 2026. On 25 September 2026, npm had 45 releases. Many releases fixed bugs. This note lists 8 lessons from the changelog that also apply to other AI coding tools.
- Published
- Topics
- TypeScript, Bun, Claude Code, Cursor, Git
Why I built Payo
AI coding assistants do not know the rules of your project. They do not know your ORM, your folder layout, your test style or your commit rules. Files like AGENTS.md and Agent Skills fix this, but most people do not write them. Payo asks short questions about your stack. Then it writes these files. Read more about Payo.
The releases
| Versions | Dates (2026) | npm releases | Main changes |
|---|---|---|---|
| 0.x | 7 June to 21 June | 15 | The first versions |
| 1.x | 29 June to 11 July | 7 | Stack detection for existing projects. Support for PHP, C#, Koa, Java and Ruby. |
| 2.x | 14 July to 25 September | 23 | One output layout for all tools. Git hooks and agent gates. Install without Node.js. |
The dates come from the npm registry. The lessons come from the Payo changelog.
1. Write one layout, not one for each tool
Before version 2.0.0, Payo wrote a different format for each tool: .cursorrules, .cursor/rules/*.mdc, .github/instructions/*, .windsurfrules and AI_RULES.md. Version 2.0.0 (14 July) removed all of them. Now Payo writes one AGENTS.md, plus one .agents/skills/<id>/SKILL.md for each topic. Claude Code and Windsurf get links to the same files.
This change also fixed a bug. The Antigravity output used flat files, such as .agents/skills/<id>.md. No Agent Skills reader can find a skill in that form.
2. A confirm prompt goes to the person, not to the model
Payo can add a "change-audit" gate. Before a commit, the agent must check the change against the project skills. The first gate asked for a confirmation. But a confirm prompt goes to the person, and its reason never gets to the model. So a click on "approve" skipped the audit.
In version 2.3.1, the gate denies the command one time for each change set, and it tells the agent what to do. The next try for the same change goes through.
3. Do not let the agent and the git hook do the same work
The git hook ran the secret scan, the linter and the tests. The generated text also told the agent to run the same commands. So the agent ran every check, and then the hook ran every check again on push.
Since version 2.3.1, Payo makes one hook plan for each run. Each check goes to one place only: the new hook, a hook that is already in the repository, or the agent. The text tells the agent not to run what a hook runs.
4. A shell script exits with the status of its last line
Husky hooks and .githooks/ scripts are shell scripts. If the secret scan failed and the format check after it passed, the hook passed. Since version 2.3.2, each check that Payo writes ends with || exit 1.
5. Text from the repository is data, not instructions
Payo puts your free-text answers and values from your files into the prompts for the agent. Since version 1.2.0, this text is between PROJECT DATA markers, with an instruction that it is data and never an instruction. In the same version, each agent CLI runs with the smallest write permission that the tool supports.
6. Check that the agent wrote the file
An agent run can end with success and write nothing. Since version 1.2.0, Payo checks for a real write. An old file that the run did not change, an empty file or a directory does not count as success. Payo removes partial output before it tries again.
7. State the real requirements, and ship less
package.jsonsaid "Node >= 18". But@clack/promptsusesutil.styleText, so Payo crashed at start on older Node.js versions. Since version 1.2.0, the requirement isnode >= 20.12.- The npm package had the demo GIF and the full-size logo. Without them, the package went from 8.3 MB to about 250 KB (version 1.2.0).
- Since version 2.3.0, a one-line script installs Payo without Node.js. It uses Bun or npm if you have one. If not, it downloads a self-contained binary and checks it against the
SHA256SUMSof the release.
8. The tools change, so check their versions
Claude Code 2.1.277 started to read AGENTS.md in projects without a CLAUDE.md. Version 2.1.281 made this work on all backends. Before, Payo always wrote a one-line CLAUDE.md that imports @AGENTS.md. Since Payo 2.4.9 (25 September), Payo checks the installed Claude Code version and skips this file on 2.1.281 or later. The check runs on your machine. A teammate with an older Claude Code must add the line.
Try Payo
curl -fsSL https://payo.uttamgelot.com/install.sh | shOr run npx @uge/payo. The code is on GitHub (MIT license).