Docs / Reference
Building modules
Build your own extensions for AyCode without AyCode’s source: one folder, one program, clear permissions.
Your first module in a minute
- Settings → Modules → New module and pick an empty folder.
- AyCode writes a module that runs right away: the manifest
aycode-module.json, a skill, a program inserver/index.mjswith the SDKserver/aycode.mjs, and tests. The folder is linked afterwards. - The module’s card shows what it may do. Allow and turn on, then mention $module-name in a chat.
- Tests run without AyCode:
node --test server/index.test.mjs.
The SDK is a single file without dependencies (Node 18 or newer). The guide is in the new folder as README.md.
Separate from AyCode
Your own code runs as its own program, an MCP server the agents call, never inside AyCode. The program talks to AyCode only through the module API: on this computer only (127.0.0.1), with its own key per module, versioned. Through the API, one module cannot speak for another or read its storage.
On the Mac the program runs walled in (macOS sandbox): it reads the system, its runtime (Node) and its own folder, but nothing in your home folder, so no vault, no projects, no keys. It writes only to its data folder (AYCODE_MODULE_DATA) and its temp folder. On the network it reaches only AyCode, and the internet only with the network permission. It cannot make other programs act for it. A program that cannot be walled in does not start on the Mac at all, and the module’s card says why.
On Windows and Linux there are no such walls yet: there the program runs with your user’s rights and can do anything you can. Permissions there only govern what AyCode gives it. The boundary is then where it comes from: public modules must be signed, and you choose to trust a publisher. Each module’s card says whether its program runs walled in.
Permissions
Every module may use its own settings and storage. Everything else is listed in the manifest under permissions, and you confirm it before turning the module on. If an update asks for more, AyCode asks again.
| Permission | What the module may do |
|---|---|
brain:read | search and read notes in your second brain, look up what AyCode remembered |
brain:propose | suggest note changes; you confirm each one |
notify | show notices in AyCode, at most six a minute |
projects:read | see your projects and their folders |
network | connect to the internet (blocked on the Mac without it) |
The API
| SDK call | Permission |
|---|---|
aycode.app.info() | always |
aycode.settings() | always |
aycode.storage.get / set / delete / keys | always (4 MB per module) |
aycode.brain.search / note / related / memory | brain:read |
aycode.brain.proposeNote({ path, text, reason }) | brain:propose |
aycode.notify(text) | notify |
aycode.projects.list() | projects:read |
Errors come with a code (forbidden, off, unavailable …) and a readable message. Writing in another language? Use the protocol directly: POST /v1/call with the module’s key; AyCode hands the address and the key to the program as environment variables.
Sharing
- Private: just for you, may be unsigned.
- Public: for everyone, must be signed with your publisher key. Every version with the same key, or AyCode refuses the update.
- Licensed: for buyers with a licence key you issue with the same key. AyCode checks it offline.
A module is packed into one .aymodule file, opened under Modules → Install module.