Writing a Pithagoras extension in Creator mode
An extension is a pi package that also brings something to the portal: tools
for the agent, routes on the server, pages and panels in the browser. In this
chat you write one in a folder of your own, install it with
extension_install, and call its tools from your next step. Nothing restarts.
The folder this file is in holds template/, a working extension in plain
JavaScript, and reference/, the full guide and the API's types.
The loop
Copy the template into this chat's folder, and give it its own name:
mkdir -p extensions && cp -r <the folder this SKILL.md is in>/template extensions/<name>
Then change name in extensions/<name>/package.json, and the tool's
name, my_extension_echo, in server.js.
Edit it: server.js for tools and routes, web/client.js and
web/client.css for what is drawn.
Install it: extension_install { path: "extensions/<name>" }. A copy of
the folder is taken and installed; your folder stays yours to change.
Read what the install says of the server half. server.running: false,
a failure or a crash means it does not work yet: call
extension_status { name: "<name>" } for its lines, and fix the code.
Call its tool from your next step. Where a subagent of this chat works in
the background, the tools come once this run ends.
Change something, and install again: nothing reloads by itself. Each
install loads every half again, at its new revision.
extension_status with no name lists what was made in Creator mode;
extension_remove { name } uninstalls one and deletes its copy. Every install
and removal is in Settings → Audit, and the person can switch an extension off
or remove it in Settings → Extensions. One they switched off stays off when you
install it again.
package.json
{
"name": "<name>",
"version": "0.1.0",
"type": "module",
"keywords": ["pi-package"],
"pi": {},
"pithagoras": { "client": "./web/client.js", "style": "./web/client.css", "server": "./server.js", "isolated": true }
}
- One name, without a scope: letters, digits,
-, _ and .. It is what
everything goes by: its routes are at /api/x/<name>/…, its pages at
/x/<name>/<id>. A name that an extension of the portal has, or that
another installed package has, is refused.
"pi": {}, always, and nothing in it that runs code: no
pi.extensions, and no folder extensions/ at the package's top (pi would
load that as a pi half). A pi half runs in every chat's pi inside the portal,
where your extension's own process does not reach. Give tools through the
server half instead (below).
"type": "module", as the template has it.
- The browser half in a folder of its own (
web/): the portal serves that
whole folder to whoever is signed in, and a module at the package's root is
not loaded.
- The template's licence is Apache-2.0; the person may change it.
- Links in your folder are left out of the copy, not followed. Install
packages with
npm install in the folder (npm copies them; pnpm links
them), and the copy takes node_modules with it. At most 64 MB, 10,000
files, 32 folders deep and 2,000 entries in one folder (node_modules
included) are copied.
Which half does what
| Half |
Runs |
For |
Server half (server.js) |
Once, for all chats, in a process of its own |
Tools (chats.extend), routes, what must be there when no chat is running |
Browser half (web/client.js) |
In each page signed in to the portal |
Everything drawn: a tool call's card, a page, a panel |
A tool belongs in the server half: it is registered in every chat's pi from
there, and it shares what the routes know.
The server half
Its default export is called with portal; it may return a function that
stops it. The members you will use most:
portal. |
|
chats.extend((pi, chat) => …) |
Tools for every chat's pi: pi.registerTool({ … }) |
router |
An Express router: routes at /api/x/<name>/…, behind the portal's login |
http.json() |
The body parser for a route that takes JSON |
chats.send(chatId, data), chats.onOpen(fn) |
To the pages open on a chat, heard there with portal.server.on |
chats.get(id), chats.list(), chats.folder(id) |
A chat, the chats, the folder a chat works in |
files.list, read, write, open… |
A chat's folder, read and changed with the portal's checks: never fs on a chat's folder |
dataDir() |
A folder of the extension's own, for what it keeps |
log(text) |
A line in its log, which extension_status shows |
A tool:
pi.registerTool({
name: "<name>_<verb>",
label: "What it does",
description: "What the model reads to decide when to call it.",
parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
guard: { outside: true },
async execute(_id, params) {
return { content: [{ type: "text", text: "…" }], details: { /* for its card */ } };
},
});
- Parameters are JSON schema.
guard says what it does: outside: true for a tool that returns what
it read from the outside world (a page, a feed, an API), so that it is held
as data and not as instructions; acts for one that changes things
("persist", "publish", "upload", "write-to-path"…), which the guard
then holds after a suspected prompt injection.
offByDefault: true keeps it off in every chat until somebody switches
it on in Settings → Tools. Without it, it is on in every chat.
- Never one of pi's own tool names (
bash, read, write, edit,
grep, find, ls…), nor another tool's: start its name with the
extension's.
Its own process
Every extension made here runs its server half in a process of its own, so it
has less than one in the portal's process:
- In
chats.extend, pi has registerTool, on, registerCommand,
sendMessage and sendUserMessage, and nothing else. Register while the
factory runs (five seconds at most), not later.
execute, a handler and a command are given no ctx. renderCall and
renderResult are left out, and any other function in a tool's definition
is refused.
- No
provide and no voice. requires and extensions.use only of an
extension in the portal's process, such as the portal's own: nothing can
build on a half in a process of its own, another made extension included.
- It has 15 seconds to start. Keep synchronous work under 10 seconds and its
heap under 512 MB: past either (or 1 GB of memory, on Linux) its process is
ended, as its crash.
A crash (a throw nothing catches, a rejection nobody hears, process.exit(),
a loop that never ends) ends its process. A call of its tool that was running
answers at once with the crash and its last lines, and it stays off until it
is installed again: fix it, and install it again.
The browser half
Plain JavaScript, made with the portal's React and no JSX, so nothing needs
building:
export default function (portal) {
const { React, ui } = portal;
const h = React.createElement;
portal.slots.register("chat.tool", { id: "card", tool: "<name>_<verb>", component: ({ call, card }) => call.status === "done" ? h("p", null, call.output) : card });
}
- Slots:
chat.tool (a call of its tool, in place of the portal's card),
nav.page (a page in the sidebar), chat.panel (a panel beside the
conversation), settings.page (its page in Settings),
chat.composer.above, chat.header.action.
portal.chats.use(chatId, pick): a hook, the chat as the page has it.
portal.api.json(portal.api.url("/route")): its server half's routes.
portal.server.on((chatId, data) => …): what chats.send says.
- Colours are the portal's variables:
rgb(var(--fg)), --fg-muted,
--fg-faint, --line, --accent, --raised, --danger… Give class names
a prefix of the extension's, in its own stylesheet. No Tailwind classes:
the page has only those the portal itself uses, and they change with it.
ui has the portal's own parts: ui.LoadFailed, ui.Empty,
ui.RowsSkeleton, ui.confirm, ui.classes.
Where to look next
reference/extension-ui.md, the whole guide (about 160 KB: grep it by its
headings, ## and ### ).
reference/server.d.ts: everything the server half's portal has.
reference/index.d.ts: the browser half's portal, and every slot.
/app/extensions/kanban/src: a full extension, written in TypeScript.
1---2name: "extension-creator"3description: "Use in Creator mode, when asked to write, change, fix or install a Pithagoras extension (a tool for the agent, a page, a panel, a route): the loop of copying the template, editing it, installing it with extension_install, reading extension_status and calling the new tool, and the rules a made extension follows."4metadata:5 source: https://skillmd.com/skills/thecodacus/extension-creator6---78# Writing a Pithagoras extension in Creator mode910An extension is a pi package that also brings something to the portal: tools11for the agent, routes on the server, pages and panels in the browser. In this12chat you write one in a folder of your own, install it with13`extension_install`, and call its tools from your next step. Nothing restarts.1415The folder this file is in holds `template/`, a working extension in plain16JavaScript, and `reference/`, the full guide and the API's types.1718## The loop19201. Copy the template into this chat's folder, and give it its own name:2122 ```bash23 mkdir -p extensions && cp -r <the folder this SKILL.md is in>/template extensions/<name>24 ```2526 Then change `name` in `extensions/<name>/package.json`, and the tool's27 name, `my_extension_echo`, in `server.js`.282. Edit it: `server.js` for tools and routes, `web/client.js` and29 `web/client.css` for what is drawn.303. Install it: `extension_install { path: "extensions/<name>" }`. A copy of31 the folder is taken and installed; your folder stays yours to change.324. Read what the install says of the server half. `server.running: false`,33 a `failure` or a `crash` means it does not work yet: call34 `extension_status { name: "<name>" }` for its lines, and fix the code.355. Call its tool from your next step. Where a subagent of this chat works in36 the background, the tools come once this run ends.376. Change something, and install again: nothing reloads by itself. Each38 install loads every half again, at its new revision.3940`extension_status` with no name lists what was made in Creator mode;41`extension_remove { name }` uninstalls one and deletes its copy. Every install42and removal is in Settings → Audit, and the person can switch an extension off43or remove it in Settings → Extensions. One they switched off stays off when you44install it again.4546## package.json4748```json49{50 "name": "<name>",51 "version": "0.1.0",52 "type": "module",53 "keywords": ["pi-package"],54 "pi": {},55 "pithagoras": { "client": "./web/client.js", "style": "./web/client.css", "server": "./server.js", "isolated": true }56}57```5859- **One name, without a scope**: letters, digits, `-`, `_` and `.`. It is what60 everything goes by: its routes are at `/api/x/<name>/…`, its pages at61 `/x/<name>/<id>`. A name that an extension of the portal has, or that62 another installed package has, is refused.63- **`"pi": {}`**, always, and nothing in it that runs code: no64 `pi.extensions`, and no folder `extensions/` at the package's top (pi would65 load that as a pi half). A pi half runs in every chat's pi inside the portal,66 where your extension's own process does not reach. Give tools through the67 server half instead (below).68- **`"type": "module"`**, as the template has it.69- **The browser half in a folder of its own** (`web/`): the portal serves that70 whole folder to whoever is signed in, and a module at the package's root is71 not loaded.72- The template's licence is Apache-2.0; the person may change it.73- Links in your folder are left out of the copy, not followed. Install74 packages with `npm install` in the folder (npm copies them; pnpm links75 them), and the copy takes `node_modules` with it. At most 64 MB, 10,00076 files, 32 folders deep and 2,000 entries in one folder (`node_modules`77 included) are copied.7879## Which half does what8081| Half | Runs | For |82| --- | --- | --- |83| Server half (`server.js`) | Once, for all chats, in a process of its own | Tools (`chats.extend`), routes, what must be there when no chat is running |84| Browser half (`web/client.js`) | In each page signed in to the portal | Everything drawn: a tool call's card, a page, a panel |8586A tool belongs in the server half: it is registered in every chat's pi from87there, and it shares what the routes know.8889## The server half9091Its default export is called with `portal`; it may return a function that92stops it. The members you will use most:9394| `portal.` | |95| --- | --- |96| `chats.extend((pi, chat) => …)` | Tools for every chat's pi: `pi.registerTool({ … })` |97| `router` | An Express router: routes at `/api/x/<name>/…`, behind the portal's login |98| `http.json()` | The body parser for a route that takes JSON |99| `chats.send(chatId, data)`, `chats.onOpen(fn)` | To the pages open on a chat, heard there with `portal.server.on` |100| `chats.get(id)`, `chats.list()`, `chats.folder(id)` | A chat, the chats, the folder a chat works in |101| `files.list`, `read`, `write`, `open`… | A chat's folder, read and changed with the portal's checks: never `fs` on a chat's folder |102| `dataDir()` | A folder of the extension's own, for what it keeps |103| `log(text)` | A line in its log, which `extension_status` shows |104105A tool:106107```js108pi.registerTool({109 name: "<name>_<verb>",110 label: "What it does",111 description: "What the model reads to decide when to call it.",112 parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },113 guard: { outside: true },114 async execute(_id, params) {115 return { content: [{ type: "text", text: "…" }], details: { /* for its card */ } };116 },117});118```119120- **Parameters** are JSON schema.121- **`guard`** says what it does: `outside: true` for a tool that returns what122 it read from the outside world (a page, a feed, an API), so that it is held123 as data and not as instructions; `acts` for one that changes things124 (`"persist"`, `"publish"`, `"upload"`, `"write-to-path"`…), which the guard125 then holds after a suspected prompt injection.126- **`offByDefault: true`** keeps it off in every chat until somebody switches127 it on in Settings → Tools. Without it, it is on in every chat.128- **Never one of pi's own tool names** (`bash`, `read`, `write`, `edit`,129 `grep`, `find`, `ls`…), nor another tool's: start its name with the130 extension's.131132## Its own process133134Every extension made here runs its server half in a process of its own, so it135has less than one in the portal's process:136137- In `chats.extend`, `pi` has `registerTool`, `on`, `registerCommand`,138 `sendMessage` and `sendUserMessage`, and nothing else. Register while the139 factory runs (five seconds at most), not later.140- `execute`, a handler and a command are given no `ctx`. `renderCall` and141 `renderResult` are left out, and any other function in a tool's definition142 is refused.143- No `provide` and no `voice`. `requires` and `extensions.use` only of an144 extension in the portal's process, such as the portal's own: nothing can145 build on a half in a process of its own, another made extension included.146- It has 15 seconds to start. Keep synchronous work under 10 seconds and its147 heap under 512 MB: past either (or 1 GB of memory, on Linux) its process is148 ended, as its crash.149150A crash (a throw nothing catches, a rejection nobody hears, `process.exit()`,151a loop that never ends) ends its process. A call of its tool that was running152answers at once with the crash and its last lines, and it stays off until it153is installed again: fix it, and install it again.154155## The browser half156157Plain JavaScript, made with the portal's React and no JSX, so nothing needs158building:159160```js161export default function (portal) {162 const { React, ui } = portal;163 const h = React.createElement;164 portal.slots.register("chat.tool", { id: "card", tool: "<name>_<verb>", component: ({ call, card }) => call.status === "done" ? h("p", null, call.output) : card });165}166```167168- **Slots:** `chat.tool` (a call of its tool, in place of the portal's card),169 `nav.page` (a page in the sidebar), `chat.panel` (a panel beside the170 conversation), `settings.page` (its page in Settings),171 `chat.composer.above`, `chat.header.action`.172- **`portal.chats.use(chatId, pick)`**: a hook, the chat as the page has it.173- **`portal.api.json(portal.api.url("/route"))`**: its server half's routes.174- **`portal.server.on((chatId, data) => …)`**: what `chats.send` says.175- **Colours** are the portal's variables: `rgb(var(--fg))`, `--fg-muted`,176 `--fg-faint`, `--line`, `--accent`, `--raised`, `--danger`… Give class names177 a prefix of the extension's, in its own stylesheet. No Tailwind classes:178 the page has only those the portal itself uses, and they change with it.179- `ui` has the portal's own parts: `ui.LoadFailed`, `ui.Empty`,180 `ui.RowsSkeleton`, `ui.confirm`, `ui.classes`.181182## Where to look next183184- `reference/extension-ui.md`, the whole guide (about 160 KB: grep it by its185 headings, `## ` and `### `).186- `reference/server.d.ts`: everything the server half's `portal` has.187- `reference/index.d.ts`: the browser half's `portal`, and every slot.188- `/app/extensions/kanban/src`: a full extension, written in TypeScript.