Build Extensions

The Manifest

manifest.js declares what your extension needs and what it provides. The loader reads it before calling any code. Unmet needs = extension skipped.

needs.services

The loader scopes core to only what you declare. hooks and modes are always available. Everything else must be listed or it's undefined.

needs.models

Core models: Node, User, Note, Contribution, LlmConnection, Chat.

optional

Same structure as needs. If missing, your extension still loads. Optional services get no-op stubs. Optional extensions just aren't there.

optional: {
  services: ["energy"],        // gets no-op stub if energy extension not loaded
  extensions: ["billing"],     // loaded after if present, ignored if not
}

provides

provides: {
  routes: "./routes.js",       // Express router mounted at /api/v1
  tools: true,                 // init() returns tools array
  modes: true,                 // init() registers modes
  jobs: "./jobs.js",           // Background job module
  orchestrator: false,         // Or path to orchestrator pipeline
  hooks: {
    fires: ["my-ext:afterProcess"],
    listens: ["afterNote", "enrichContext"],
  },
  cli: [
    { command: "my-cmd", description: "Does a thing", method: "POST", endpoint: "/my-ext/do" },
  ],
  env: [
    { key: "MY_EXT_API_KEY", required: true, description: "API key for external service" },
  ],
}

Storing Data

Extension data lives in the metadata Map on nodes and users. Each extension gets its own namespace. 512KB per namespace per node. Writes are atomic MongoDB $set operations.

import { getExtMeta, setExtMeta } from "../../seed/tree/extensionMetadata.js";
import { getUserMeta, setUserMeta } from "../../seed/tree/userMetadata.js";

// Node metadata
const data = getExtMeta(node, "my-ext");        // { key: "value" } or {}
await setExtMeta(node, "my-ext", { key: "value" }); // atomic $set

// User metadata
const prefs = getUserMeta(user, "my-ext");
setUserMeta(user, "my-ext", { theme: "dark" });
await user.save();

setExtMeta is async. Always await it. Spatial scoping blocks writes from extensions that are blocked at the node's position.

AI Modes

A mode defines how the AI thinks at a position. System prompt + tool list. The kernel injects [Position] before your prompt automatically. You never need to include rootId or currentNodeId.

// modes/coach.js
export default {
  name: "tree:my-coach",
  emoji: "🏋️",
  label: "Coach",
  bigMode: "tree",
  toolNames: ["get-tree", "get-node", "create-new-node"],
  buildSystemPrompt({ username, rootId }) {
    return `You are ${username}'s personal coach.
Your job is to help them organize and track their goals.`;
  },
};

// In init():
core.modes.registerMode("tree:my-coach", coachMode, "my-ext");

CLI Commands

Declare in the manifest. The CLI discovers them from /api/v1/protocol. Each command maps to an HTTP method + endpoint.

provides: {
  cli: [
    {
      command: "my-cmd [message...]",
      description: "Do something with a message",
      method: "POST",
      endpoint: "/root/:rootId/my-ext",
      bodyMap: { message: 0 },  // maps first arg to body.message
    },
    {
      command: "my-list",
      description: "List things",
      method: "GET",
      endpoint: "/user/:userId/my-ext",
    },
  ],
}

Required fields: command, description, method, endpoint. The CLI replaces :rootId, :userId, :nodeId with the current context.

Background Jobs

Return a jobs object with start(). Use .unref() on timers for graceful shutdown. Read intervals from land config.

// jobs.js
import { getLandConfigValue } from "../../seed/landConfig.js";

export function start() {
  const interval = Number(getLandConfigValue("myExtInterval")) || 3600000;
  const timer = setInterval(async () => {
    // do periodic work
  }, interval);
  if (timer.unref) timer.unref();
}

// In init():
const jobs = await import("./jobs.js");
return { jobs };

Schema Migrations

When your metadata format changes, write a migration. The loader runs pending migrations at boot based on schemaVersion in your manifest.

// manifest.js
{ schemaVersion: 2, ... }

// migrations.js
export default {
  2: async () => {
    // Migrate from v1 to v2
    const nodes = await Node.find({ "metadata.my-ext": { $exists: true } });
    for (const node of nodes) {
      const old = getExtMeta(node, "my-ext");
      await setExtMeta(node, "my-ext", { ...old, newField: old.oldField });
    }
  },
};

Common Patterns

enrichContext (inject into AI prompts)

core.hooks.register("enrichContext", async ({ context, node }) => {
  const data = getExtMeta(node, "my-ext");
  if (data.summary) {
    context.myExt = "[My Extension] " + data.summary;
  }
}, "my-ext");

Optional energy wiring

// manifest: optional: { services: ["energy"] }
let energy = null;
export function setEnergyService(svc) { energy = svc; }

// In init():
if (core.energy) setEnergyService(core.energy);

// When needed:
if (energy) await energy.useEnergy({ userId, action: "my-action" });

HTML rendering integration

import { getExtension } from "../loader.js";

// Check if HTML rendering is available
if (!getExtension("html-rendering")) {
  return sendOk(res, jsonData);
}

// Render HTML
const html = getExtension("html-rendering").exports;
res.send(html.renderMyPage({ data }));

The full extension format specification lives in land/extensions/EXTENSION_FORMAT.md in the repo. This page covers what you need to get started. The spec covers everything.