Aether Extension Package Format and package.json Fields

An Aether extension package is a directory (or zip archive) containing a package.json that declares which entry files power which tiers. Aether reads this manifest at load time to discover entry points for the Pi agent layer, the Script Mod runtime, and the native DEX loader. Only the fields relevant to the tiers you use are required — unused tier fields are simply absent.

Full package.json example

The example below activates all three tiers from a single package:

package.json

{
  "name": "my-aether-mod",
  "version": "1.0.0",
  "pi": {
    "extensions": ["./agent.ts"]
  },
  "aether": {
    "api": {
      "min": 2,
      "max": 2
    },
    "extensions": ["./android.ts"],
    "native": {
      "api": {
        "min": 1,
        "max": 1
      },
      "classpath": ["./native/mod.dex"],
      "libraryPath": ["./native/lib"],
      "entrypoints": ["com.example.aether.MyNativeMod"]
    }
  }
}

Fields reference

string

An npm-style package name that identifies your extension. Use lowercase letters, numbers, and hyphens (for example, my-aether-mod or @myorg/chat-enhancer). Aether uses this name in the Extensions list and when generating stable extension IDs; if omitted, it falls back to the package directory name.

string

A semver version string (for example, 1.0.0). Increment this value when you publish updates so Aether and package managers can track changes.

string[]

Array of paths to Pi extension entry files, relative to the package root. Each file is loaded by the Pi Coding Agent runtime. Export a factory function as default to register Pi commands, tools, and hooks. Omit this field if your extension does not target the Pi agent layer.

string[]

Array of paths to Aether Script Mod entry files, relative to the package root. Each file is loaded by the Aether Script Mod runtime (API v2). Export your factory as activateAether or aether to register surfaces, components, pages, actions, and event handlers. The runtime also accepts a default export for entries explicitly listed here (useful for packages that target only this tier). These files reload without restarting the app when an extension reload is triggered. Omit this field if your extension does not use the Script Mod API.

number | object

Script API compatibility. Use the exact integer 2, or an object such as { "min": 2, "max": 2, "allowNewer": false }. Missing declarations remain compatible for legacy packages. An incompatible or malformed declaration rejects the reload and keeps the previous working Script runtime active.

number | object

Native API compatibility. The current Native API version is 1. Use an exact integer or the same min, max, and optional allowNewer range format as aether.api.

string[]

Array of paths to .dex, .apk, or jar/zip files that contain a compiled classes.dex, relative to the package root. Aether passes these paths to DexClassLoader at process startup. A plain JVM .class jar is not sufficient — run Android D8/R8 on your compiled output first. Omit the entire aether.native object if your extension does not include a Native Mod.

string[]

Array of paths to directories containing .so native libraries, relative to the package root. Aether adds these directories to the native library search path when loading the DEX classpath. Only required if your Native Mod uses JNI libraries.

string[]

Array of fully-qualified Kotlin class names that implement AetherNativeMod. Aether instantiates each class via the DEX classloader and calls onLoad(context) during process startup. Requires aether.native.classpath to contain the compiled classes.

Script-only vs native-only packages

Script-only packages omit the aether.native object entirely. This is the most common extension format and can reload without restarting Aether:

package.json

{
  "name": "my-script-mod",
  "version": "1.0.0",
  "aether": {
    "api": 2,
    "extensions": ["./index.ts"]
  }
}

Native-only zip packages can omit both the pi field and the extensions field under aether. Include only aether.native:

package.json

{
  "name": "my-native-mod",
  "version": "1.0.0",
  "aether": {
    "native": {
      "api": 1,
      "classpath": ["./build/mod.dex"],
      "entrypoints": ["com.example.aether.MyNativeMod"]
    }
  }
}

Installation location

Imported extension packages live under ~/.aether/extensions inside Aether’s managed Alpine filesystem. When you import a zip via Settings → Extensions → Import extension, Aether stages the package before replacing an existing copy. A bundled node_modules directory is used as-is. Otherwise, packages with runtime dependencies use npm ci --omit=dev when a lockfile is present and npm install --omit=dev when it is not. Dependency or reload failures restore the previous package. Packages installed through Aether’s package management are discovered through the Pi package manager.

Shared Pi + Aether entry point

When you share a single entry file between pi.extensions and aether.extensions, keep the Pi factory as the default export and export the Aether factory as activateAether or aether. The Script Mod runtime looks for activateAether or aether first; it falls back to default only for entries that are explicitly listed in aether.extensions (as opposed to implicitly discovered files).

index.ts

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { defineAetherExtension, ui } from "@baimoqilin/aether-extension-api";

export default function activatePi(pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Pi-compatible command",
    handler: async (_args, ctx) => ctx.ui.notify("Hello from Pi", "info"),
  });
}

export const activateAether = defineAetherExtension((aether) => {
  aether.registerSurface("chat.composer.top", {
    id: "hello",
    render: () => ui.button("Insert prompt", "insert"),
  });
  aether.registerAction("insert", () =>
    aether.state.patch("draft_input", "Explain this repository.")
  );
});

The defineAetherExtension helper provides TypeScript types for the aether argument and is a no-op at runtime — it simply returns the factory function you pass in. Import it from @baimoqilin/aether-extension-api.

Overview

Script Mod API

UI Reference

Native Mods

Pi Extensions

Examples

Aether Extension Package Format and package.json Fields

Full package.json example

Fields reference

Script-only vs native-only packages

Installation location

Shared Pi + Aether entry point

​Full package.json example

​Fields reference

​Script-only vs native-only packages

​Installation location

​Shared Pi + Aether entry point

Full package.json example

Fields reference

Script-only vs native-only packages

Installation location

Shared Pi + Aether entry point