piclaw-addons: Instructions file for Codex

Developing piclaw add-ons

This guide covers how to create, test, and publish an extension for piclaw.

---

Quick start

Install-path rule: first-party piclaw-addons must install via public GitHub-hosted tarball URLs from catalog.json. Do not change docs, generated catalog entries, or runtime integration back to npmjs.org package specs or authenticated GitHub Packages reads. Runtime install/remove must remain zero-auth.

# 1. Create your addon directory
mkdir -p addons/my-addon/skills/my-skill

# 2. Write your entry point, package.json, and skill
# 3. Sync the catalog
bun run sync:catalog

# 4. Validate the repository contracts
bun install --frozen-lockfile
bun run check:catalog
bun run typecheck:earendil-compat
bun run test:earendil-compat
bun test standalone-import.test.ts
bun pm pack --dry-run

# 5. Commit on a feature branch and open a pull request
git switch -c feat/my-addon
git add addons/my-addon package.json catalog.json
git commit -m "feat: add my-addon"
git push -u origin feat/my-addon
gh pr create

---

Addon structure

Important: standalone add-on packages must be self-contained. If an add-on is published as its own npm package (for example @rcarmo/piclaw-addon-portainer), it must not rely on repo-root files outside its package directory at runtime. Do not import ../../lib/compat/* from a published standalone package unless those files are vendored into that package.

addons/<slug>/
├── index.ts          # Runtime entry point (default export)
├── web/
│   └── index.ts      # Optional browser-side settings pane / web entry
├── package.json      # Package manifest
├── skills/           # Optional: agent skills
│   └── my-skill/
│       └── SKILL.md
└── *.ts              # Supporting modules

---

Entry point

The default export is a function that receives the ExtensionAPI:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

const baseDir = dirname(fileURLToPath(import.meta.url));

export default function myAddon(pi: ExtensionAPI) {
  // Register skills for agent discovery
  pi.on("resources_discover", () => ({
    skillPaths: [join(baseDir, "skills", "my-skill", "SKILL.md")],
  }));

  // Register a tool
  pi.registerTool({
    name: "my_tool",
    label: "my_tool",
    description: "What this tool does.",
    parameters: MyToolSchema,
    async execute(_toolCallId, params, _signal, _update, ctx) {
      return { content: [{ type: "text", text: "result" }] };
    },
  });
}