Agxos template apps — docs.glixo.dev

Agxos apps — template (no-code)

A template app is an Agxos app contribution where you write zero rendering code. You declare template: "chat" | "note" | "list" | "terminal" in contributes.agxos.apps[], and the host renders it with one shared component; you only supply metadata (id, name, size, icon/accent) and, optionally, a set of named agent actions the coding agent can invoke against the running app.

This is one type with four interchangeable template values — covered together because the manifest shape, the code you write (none), and the host consumption path are identical across all four.

What it is + when to use it

Use a template app when you want a small persistent UI surface (a running log, a scratch note, a chat-style transcript, or a terminal-like scrollback) driven entirely by agent/session events, and you don't need custom layout or interactivity beyond that. Reach for template: "app" instead (a separate, coded type) only when the four generic layouts can't express what you need.

note — a single text blob the agent can replace or append to. Good for running summaries, incident logs, scratch state.
list — discrete rows appended over time. Good for event feeds, task lists.
chat — a bubble conversation with a typed "reply" animation for outgoing messages. Good for a persona/assistant-style surface.
terminal — monospace scrollback. Good for log tailing / command-output style feeds.

The manifest fragment (real sample)

From glixo-community-modules/examples/agxos/apps/incident-notes/glixo.module.json (template: "note", with two agent actions):

{
  "id": "glixo.samples.agxos-incident-notes",
  "name": "Agxos Incident Notes",
  "version": "0.1.0",
  "protocolVersion": "0",
  "runtime": { "kind": "node", "version": "20" },
  "entry": { "command": "echo", "args": ["client-bundled-in-app"] },
  "capabilities": ["glixo.agxos.apps.register"],
  "requires": [
    "ui",
    "capability.glixo.agxos.apps.register",
    "capability.glixo.agxos.windows.control",
    "capability.glixo.agxos.notifications.create"
  ],
  "contributes": {
    "actions": [
      {
        "id": "glixo.samples.agxos-incident-notes.open",
        "slot": "agxos.toolbar",
        "title": "Incident Notes",
        "icon": "document-text-outline",
        "command": "glixo.agxos.windowAction",
        "priority": 40,
        "input": {
          "appId": "incident.notes",
          "command": "show",
          "notify": {
            "title": "Incident Notes ready",
            "body": "The extension app is open in Agxos.",
            "kind": "success"
          }
        }
      }
    ],
    "agxos": {
      "apps": [
        {
          "id": "incident.notes",
          "name": "Incident Notes",
          "icon": "IN",
          "accent": "#0A84FF",
          "template": "note",
          "width": 560,
          "height": 420,
          "actions": [
            { "id": "write", "description": "Replace the visible incident note." },
            { "id": "add", "description": "Append a line to the incident note." }
          ]
        }
      ]
    }
  }
}

Notes on the fields, confirmed against the schema (glixo-platform/catalog/schema/glixo.module.schema.json:368-406) and SDK type AgxosAppDefinition (glixo-sdk/packages/nodejs/src/agxosAppSpec.ts:73-99):

contributes.agxos.apps[].id/name/template are required; template is one of "chat" | "note" | "terminal" | "list" | "app" — a template app just means anything other than "app" (which alone requires entry).
actions[] items require only id (pattern ^[a-z0-9_]{1,40}$); description is optional but is how the agent knows what the action does.
The contribution needs ui and capability.glixo.agxos.apps.register in requires (03-module-manifest.md:63).
The toolbar actions[] entry with command: "glixo.agxos.windowAction" is a separate, optional convenience — it opens/hides the app window and (if capability.glixo.agxos.notifications.create is granted) fires a toast; its input.appId must reference an id declared in contributes.agxos.apps (03-module-manifest.md:69).

The code you write

None — that's the point of a template app. The incident-notes sample's src/incident-notes-app/index.js is not app UI code at all; it only exists to make the packaged artifact non-empty:

console.log('Agxos Incident Notes is a declarative client Extension sample.');
console.log('The host renders the app from contributes.agxos.apps; this artifact only proves install packaging.');

(glixo-community-modules/examples/agxos/apps/incident-notes/src/incident-notes-app/index.js)

The only "code" you author is the actions[] list of verb ids/descriptions in the manifest. Your agent (or another extension) drives the app at runtime via the code_os_use_app(app, action, args) tool (the app-id parameter is named app; see the real intent envelope at glixo-code/sources/agxos/AgxosIframeHost.tsx:476), which the host turns into an intent on that app's per-window bus. Action-verb → behavior mapping is generic and shared across all templates (glixo-os/src/apps/GenericTemplatedApp.tsx:21-22):

const APPEND_VERBS = ['receive', 'add', 'append', 'log', 'run', 'message', 'post', 'notify', 'write_line', 'event'];
const TYPED_VERBS = ['reply', 'send', 'type', 'say', 'respond', 'answer'];

For template: "note": verbs write/set (or any TYPED_VERBS) replace the note text; anything else appends a line (GenericTemplatedApp.tsx:59-66). So the incident-notes sample's declared write action id maps naturally to the replace path and add to the append path — the mapping is by the verb's name/shape, not a hardcoded table per app.

How the host consumes it

glixo-code/sources/extensions/store.ts:333-341 (getInstalledAgxosApps) walks every installed extension's manifest.contributes?.agxos?.apps; each entry is then rendered by the shared GenericTemplatedApp component keyed on its template (glixo-os/src/apps/GenericTemplatedApp.tsx:37), which only accepts ['chat', 'note', 'terminal', 'list'] and falls back to 'chat' for anything else (glixo-os/src/os/apps.tsx:332,343).

Sample to study

glixo-extensions-docs/samples/apps/agxos-template-app/ is the self-contained teaching sample. glixo-community-modules/examples/agxos/apps/incident-notes/ is a second declarative example and is intentionally excluded from the marketplace. No production catalog entry is presented as an authoring tutorial.