Publishing extensions

An extension is a folder with an index.ts. To share one, push the folder to GitHub or publish it to npm. The apps install from both. zidane extension scaffolds a new extension, runs its tests, checks and packs it, and publishes it to npm.

A minimal flow#

zidane extension create deploy-board --ui --tui
cd deploy-board
zidane extension test
zidane extension pack
zidane extension publish --dry-run
zidane extension publish --access public

create writes a working extension with a test. pack checks it the way an install would. publish runs the same checks, then npm publish.

zidane extension#

A name must start with a lowercase letter, then lowercase letters, digits and single dashes: it becomes the extension's id. The apps' Settings also create extensions, and open a session with the zidane-extension skill active so the agent knows the API (create from the apps).

What pack checks#

The copy follows files in package.json (paths, folders, * patterns and ! exclusions). It never copies node_modules, .git, .pack, lock files or tests. Without a package.json, pack writes one.

publish also refuses a package with no package.json, private: true, no name or version, or a version that differs from the definition's. Its exit code is npm's.

package.json#

The scaffold writes:

{
  "name": "deploy-board",
  "version": "0.1.0",
  "description": "A zidane extension.",
  "type": "module",
  "keywords": ["zidane", "zidane-extension"],
  "main": "./index.ts",
  "files": ["index.ts", "ui.tsx", "tui.tsx", "README.md"],
  "scripts": {
    "test": "zidane extension test",
    "pack": "zidane extension pack",
    "publish:extension": "zidane extension publish"
  },
  "peerDependencies": { "zidane": ">=X.Y.0" }
}

X.Y is the major and minor version of the zidane that wrote the scaffold, so that zidane and every later one load it. zidane extension pack writes the same range when the folder has no package.json.

Ship the TypeScript sources. The apps compile them when they load the extension: no build step.

Keep zidane in peerDependencies, never in dependencies: each app hands the extension its own copy. Packages the extension needs go in dependencies. The install puts them in the extension's own node_modules.

The zidane field#

Add a zidane field so the extension browsers in Settings can list it with a name, a line of text and an icon. The browsers read this field and never run your code, so without it a row shows only the folder name.

{
  "zidane": {
    "displayName": "Deploy board",
    "description": "Shows the deploys of this project.",
    "icon": { "gui": "i-ph-rocket" }
  }
}

Keep these values the same as the definition's. Once the extension loads, the apps show what the definition says. An extension.json file with the same keys works too.

The zidane version range#

peerDependencies.zidane says which zidane the extension is made for. The apps read it before they load the module:

The range takes npm syntax: >=10.0.0, ^10.2, ~10.1.0, 10.x, >=10 <12, ||. Raise the floor when you start using a newer API.

Install#

Both apps install extensions from Settings: Settings › Extensions & Plugins in the terminal app, Settings › Extensions in the desktop app (install).

The install then:

1. Fetches the source into a temporary folder: a shallow git clone, or the tarball when git is missing, or the npm tarball.
2. Installs dependencies with the first of bun, npm, pnpm or yarn on the PATH. Install scripts never run.
3. Imports the extension and validates it. An extension that does not validate, or one for a newer zidane, installs nothing.
4. Copies it to <scope>/extensions/<id>/, named after its id, and writes .install.json with the source and the commit for updates.

The scope is you (~/.zidane/extensions/) or this project (<project>/.zidane/extensions/, loaded only with project trust). Installing over an existing extension is all or nothing: a failure puts the old one back.

A repository with one extension holds index.ts at its root. A repository with several holds extensions/<name>/index.ts each, like the zidane repository's own native extensions.

Private repositories#

An extension can live in a private GitHub repository. Only people with access to the repository can list it and install it.

• List. The browser reads the repository with your GitHub login: gh auth login, or GITHUB_TOKEN. Without a login, GitHub answers that the repository does not exist, so the browser says that it may be private.
• Install. The install clones with git, and git does not read GITHUB_TOKEN. Run gh auth login and then gh auth setup-git, or add an SSH key to your GitHub account. Without git, only a public repository installs.

On a server, these steps apply to the server's user, not to you.

Declare extensions in a config file#

An extensions array in a zidane config file declares extensions and their settings. The user file is ~/.zidane/config.json. The project file is <project>/.zidane/config.json.

{
  "extensions": [
    { "source": "owner/repo" },
    { "source": "github:owner/repo@v1.2.0:extensions/goal", "settings": { "model": "opus" } },
    { "source": "owner/collection name", "enabled": false },
    { "source": "@scope/pkg@1.0.0" },
    { "source": "./tools/my-extension" }
  ]
}

A bad entry is dropped with an error. An unknown field, key or value is dropped with a warning. When two entries name the same source, the first one counts.

When the apps apply it#

The app that runs your extensions applies the file: the daemon, or the terminal and desktop apps when they run without it. It does this in the background, so the app starts at its usual speed. It applies the file again each time you save it.

• A new remote entry is installed into ~/.zidane/extensions (<project>/.zidane/extensions for the project file) and loads. A removed entry is uninstalled, if the lock says the config file installed it.
• A local path loads in place. Removing the entry unloads it and leaves the folder alone.
• enabled: false keeps the extension installed and loads it turned off.
• The project file applies only when "Load project extensions" is on: installing runs the extension's code.
• An entry that fails shows in Settings › Extensions with the reason, under its source. Without a network, an entry already installed keeps its version and its lock entry.

The apps do not update a locked entry by themselves: change its version or ref in source to move it.

The lock file#

extensions.lock.json sits next to each config file, so a project can commit its own. It records what each entry resolved to:

{
  "lockfileVersion": 1,
  "extensions": {
    "github:owner/repo:extensions/goal": {
      "source": "github:owner/repo@v1.2.0:extensions/goal",
      "id": "goal",
      "resolved": "github:owner/repo@v1.2.0",
      "commit": "4f1c2d9",
      "integrity": "sha256-…",
      "installedAt": "2026-10-20T09:12:00.000Z"
    }
  }
}

An entry's key is its source without the version, so changing a version updates the same entry. A locked entry installs its pinned version until its source changes. integrity hashes the installed files.

Project trust#

Extensions in a project folder (<project>/.zidane/extensions/, <project>/.agents/extensions/) run code from the repository you opened. They stay off until you turn on "Load project extensions" in Settings › Agent, or set ZIDANE_TRUST_PROJECT_EXTENSIONS=1. Until then each one shows in Settings with the reason. Extensions in your home folder always load.

An extension asks for no permissions. Once loaded, it can do what your user can do. Install only what you would run yourself.

Where the apps look#

The apps load extensions/<id>/index.ts (or .tsx, .mjs, .js) from <project>/.agents/, <project>/.zidane/, ~/.agents/ and ~/.zidane/, in that order. The first folder for an id wins. ZIDANE_EXTENSION_DIRS adds more folders. The folder name must equal the definition's id.

An optional extension.json, or a zidane field in package.json, may give apiVersion, name, displayName, description and icon (the zidane field). The apps read it before the module: an apiVersion other than 1 there refuses the extension without running it.

Pitfalls#

• A version in package.json that differs from the definition's blocks publish. Bump both.
• zidane in dependencies installs a second copy that the apps ignore, and slows every install. Use peerDependencies.
• A dependency that needs an install script does not get it. Ship prebuilt files, or pick a package without one.
• A folder named differently from the id is refused at load. pack warns about it, the install names the folder for you.
• Do not leave .ts files the extension writes at run time in its folder: the apps reload the extension when its sources change. Write data under ctx.storage.path.
• Without a peerDependencies.zidane range, a user on an older zidane gets an extension that fails at load instead of a clear message.