Skip to content
Skills Library
Programming · Building & coding

atom-lite-extensions

/atom-lite-extensions

Build, load, and debug Atom-lite extensions (Pi-compatible). Use when creating an extension, registering tools/commands/providers, handling events, adding UI widgets, or troubleshooting extension loading. Covers the ExtensionAPI surface, trust, discovery, tiers, and examples.

Repository
atom-lite ↗
Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
9
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build, load, and debug Atom-lite extensions (Pi-compatible). Use when creating an extension, registering tools/commands/providers, handling events, adding UI widgets, or troubleshooting extension loading. Covers the ExtensionAPI surface, trust, discovery, tiers, and examples.

Original author description

Build, load, and debug Atom-lite extensions (Pi-compatible). Use when creating an extension, registering tools/commands/providers, handling events, adding UI widgets, or troubleshooting extension loading. Covers the ExtensionAPI surface, trust, discovery, tiers, and examples.

How it works

  1. Minimal extension
  2. Discovery
  3. Module shape
  4. Tools
  5. Commands
  6. Events
  7. UI
  8. Session entries
  9. Providers & models
  10. Exec & logging
Original SKILL.md headings · 256 lines, 865 words
SKILL.md preview
---
name: atom-lite-extensions
description: "Build, load, and debug Atom-lite extensions (Pi-compatible). Use when creating an extension, registering tools/commands/providers, handling events, adding UI widgets, or troubleshooting extension loading. Covers the ExtensionAPI surface, trust, discovery, tiers, and examples."
license: MIT
---

# Atom-lite Extensions

Atom-lite hosts **unmodified Pi coding-agent extensions in-process**. An
extension is a TypeScript/JavaScript module that exports a default (or
`activate`) function receiving an `ExtensionAPI` (`pi`). It registers tools,
commands, providers, models, widgets, and event handlers into Atom-lite's own
runtime.

Reference docs:

- [docs/extensions.md](https://github.com/beast-ofcourse/atom-lite/blob/master/docs/extensions.md) — discovery, trust, compatibility tiers, diagnostics.
- [docs/adr/0011-pi-extensions-in-process.md](https://github.com/beast-ofcourse/atom-lite/blob/master/docs/adr/0011-pi-extensions-in-process.md) — architecture.
- [src/extensions/types.ts](https://github.com/beast-ofcourse/atom-lite/blob/master/src/extensions/types.ts) — full `ExtensionAPI` + registries.
- [src/extensions/api.ts](https://github.com/beast-ofcourse/atom-lite/blob/master/src/extensions/api.ts) — runtime implementation.
- [tests/extensions/](https://github.com/beast-ofcourse/atom-lite/tree/master/tests/extensions) — conformance fixtures.
- Run `/extensions` and `/extensions doctor` inside atom-lite for live diagnostics.

## Minimal extension

```ts
// my-ext.ts
export default function (pi: any) {
  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Return a greeting for a name.",
    parameters: {
      type: "object",
      properties: { name: { type: "string" } },
      required: ["name"],
    },
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }] };
    },
  });

  pi.registerCommand({
    name: "hello",
    description: "Say hello",
    async run(ctx, args) {
      pi.notify(`hello ${args}`, "info");
    },
  });

  pi.on("tool_call", async (event) => {
    // observe every tool call
    pi.log(`tool_call: ${event?.name}`);
  });
}
```

Load it:

```bash
atom-lite -e ./my-ext.ts
# or place under .agents/skills? no — extensions live in extension dirs, see Discovery
```

## Discovery

Extensions are discovered from:

- CLI paths: `-e` / `--extension PATH`.
- Atom-lite user/project extension directories.
- Pi discovery locations and `settings.json` / `package.json` `pi.extensions` manifests.

Project-local extensions are **skipped until the project is trusted**. Interactive
sessions prompt for approval; non-interactive runs skip untrusted ones. Trust
decisions are stored in user config. Check trust with `pi.isProjectTrusted()`.

## Module shape

Both forms are accepted (migration-friendly):

```ts
export default function (pi) {
  /* ... */
}
export async function activate(pi) {
  /* ... */
}
```

Pi host modules are aliased to Atom-lite's own copies, so use Pi-style imports:

```ts
import { Type } from "@sinclair/typebox"; // or "typebox"
import { Text } from "@earendil-works/pi-tui"; // or "pi-tui"
```

Legacy `@mariozechner/*` specifiers also resolve. TypeScript loads without a
build step (via `jiti`).

## Tools

```ts
pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What the LLM sees.",
  parameters: {/* JSON Schema / TypeBox */},
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // stream partial output:
    onUpdate?.({ content: [{ type: "text", text: "partial..." }] });
    return {
      content: [{ type: "text", text: "final result" }],
      details: { foo: 1 },
    };
  },
  // optional custom rendering (Tier 2):
  renderCall: (args, theme, context) => new Text(`call ${args}`),
  renderResult: (result, options, theme, context) =>
    new Text(result.content[0]?.text ?? ""),
});
pi.unregisterTool("my_tool");
pi.setActiveTools(["my_tool"]);
```

## Commands

```ts
pi.registerCommand({
  name: "mycmd",
  description: "Do something",
  argumentHint: "[arg]",
  async run(args, ctx) {
    pi.appendEntry("mycmd_ran", { args });
    const ok = await pi.confirm("Title", "Proceed?");
    const name = await pi.input("Name", "placeholder");
    const choice = await pi.select("Pick", ["a", "b"]);
  },
});
pi.unregisterCommand("mycmd");
```

Commands become `/mycmd` in the palette and support autocomplete.

## Events

```ts
const off = pi.on("assistant_delta", async (event, ctx) => {
  /* ... */
});
pi.off("assistant_delta", handler);
```

Common events: `tool_call`, `tool_result`, `assistant_delta`, `assistant_text`,
`thinking_delta`, `agent_start`, `agent_end`, `turn_start`, `turn_end`,
`context_usage`, `model_switched`, `session_start`. Tier 3 events
(session tree, forks) fail loudly.

## UI

```ts
pi.ui.notify("hello", "info");          // info | warning | error
pi.setStatus("myext", "status text");   // undefined clears
pi.registerWidget("aboveInput", { id: "my-widget", location: "aboveInput", render: (width) => ["line1"] });
pi.setWidget("key", ["line"], { placement: "aboveEditor" });
pi.setFooter((tui, theme, data) => /* component */);
pi.setHeader((tui, theme) => /* component */);
pi.setTitle("my title");
pi.setWorkingMessage("thinking...");
pi.setWorkingVisible(true);
pi.setWorkingIndicator({ frames: ["⠋","⠙"], intervalMs: 80 });
pi.setHiddenThinkingLabel("reasoning");
pi.getToolsExpanded(); pi.setToolsExpanded(true);
```

Dialogs: `pi.select`, `pi.confirm`, `pi.input` (shown above).

## Session entries

```ts
pi.appendEntry("custom_type", { foo: 1 });
const entries = pi.getSessionEntries({ type: "custom_type" });
pi.getSessionManager(); // read model
pi.getSession(); // { id }
pi.getWorkspace();
```

## Providers & models

```ts
pi.registerProvider({
  name: "myprovider",
  // OpenAI-compatible mapping; OAuth/streamSimple are reduced-compat
});
pi.registerModel({ id: "mymodel", provider: "myprovider", ... });
pi.unregisterProvider("myprovider");
```

## Exec & logging

```ts
const res = await pi.exec("git", ["status"], { cwd: pi.getWorkspace() });
pi.log("debug message");
```

## Shortcuts, flags, autocomplete

```ts
pi.registerShortcut("ctrl+shift+x", {
  description: "do thing",
  handler: async (ctx) => {},
});
pi.registerFlag("myflag", { type: "boolean", default: false });
const v = pi.getFlag("myflag");
pi.addAutocompleteProvider((tui, theme) => ({/* ... */}));
```

## Renderers (Tier 2)

```ts
pi.registerToolRenderer((toolName, next) => ({ renderCall, renderResult }));
pi.registerMessageRenderer("custom_type", (message, options, theme) => /* Component */);
pi.registerEntryRenderer("custom_type", (entry, theme) => /* Component */);
pi.registerMarkdownTransformer((markdown) => markdown);
```

## Compatibility tiers

- **Tier 1 (works today):** discovery, trust, TS loading, tools, commands, events,
  session entries/read model, status/notify/dialogs/widgets/overlays, exec,
  provider/model registration (OpenAI-compatible).
- **Tier 2 (staged):** renderers, markdown transformers, shortcuts, flags,
  autocomplete, custom footer/header/title, working indicator, thinking label.
- **Tier 3 (deferred, fail loudly):** session tree/forks, codemode, MCP server
  registration, OAuth providers, virtualModel, RPC mode, custom editors.

Reduced-compat features (OAuth, `streamSimple`, classifiers, image generation,
`refreshModels`) emit warnings rather than failing.

## Diagnostics

Inside atom-lite:

- `/extensions` — list discovered extensions + load status.
- `/extensions doctor` — per-extension tools/commands/errors.

## Tips

- Keep extensions dependency-free or bundle deps; host aliases cover Pi modules.
- Use `pi.appendEntry` for persisted state instead of module globals.
- Trust project extensions before they load (`pi.isProjectTrusted()`).
- Reload with `/reload` (or restart) after edits; module caching is disabled.
- Test against `tests/extensions/` conformance fixtures.

## Links

- Docs: [docs/extensions.md](https://github.com/beast-ofcourse/atom-lite/blob/master/docs/extensions.md)
- ADR: [docs/adr/0011-pi-extensions-in-process.md](https://github.com/beast-ofcourse/atom-lite/blob/master/docs/adr/0011-pi-extensions-in-process.md)
- Types: [src/extensions/types.ts](https://github.com/beast-ofcourse/atom-lite/blob/master/src/extensions/types.ts)
- Runtime: [src/extensions/](https://github.com/beast-ofcourse/atom-lite/tree/master/src/extensions)
- Pi extension API reference (installed): `~/.pi/agent/install/releases/1.4.0/node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts`

Versions

RepositoryScoreLicence
This page · beast-ofcourse/atom-lite100MIT
beast-ofcourse/atom-lite100MIT

Database snapshot: 13.11.2026 · package version e03cd12e3952 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95extension-creator
    Create AiderDesk extensions by setting up extension files, defining metadata, implementing Extension interface methods, and updating documentation. Use when building a new extension, creating extension commands, tools, or event handlers.
  • 100scaffold-extension
    Create a new extension package inside an existing framework's extensions/ directory. Use when authoring an expansion (extension) for AIWG.
  • 100build-chrome-extension
    Use if building or debugging a Chrome MV3 extension — manifest v3, service_worker, content_scripts.
  • 100create-extension
    Generate and implement extensions for Accounted: scaffold files, configure manifests, write event handlers, API routes, services, workspace UIs, settings panels, and testing. Use when creating new extensions, adding surfaces to existing extensions, or understanding the extension…
  • 100content-sdk-app-router-atom-create
    Writes a Content SDK atom (beta.atoms): atom vs component, field schemas and enum tokens, renderer, catalog and registry keys, container slots, lock lifecycle, mock-MMS proof. Use when adding or changing an atom. Not wiring atoms into an app.
  • 100app-extensions
    Generates app extension infrastructure for Share Extensions, Action Extensions, Keyboard Extensions, and Safari Web Extensions with data sharing via App Groups. Use when user wants to add a share extension, action extension, keyboard extension, Safari web extension, or any app extension type.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.