Plugin and migration

agb ships as a native agy plugin named antigravity-booster, installed under ~/.gemini/config/plugins/. It depends on a second plugin, adlc-antigravity (npm package @adlc/antigravity), which carries the ADLC doctrine skills, the prosecutor agent and the rails-guard hook. This page covers how both are located, verified and installed, and how agb migrate moves an older npm-global install onto the plugin.

The design is specified in .adlc/specs/native-plugin-installation.md; the earlier draft lives at docs/specs/native-plugin-installation.md.

Finding the booster plugin rootCopy Anchor Link

resolvePluginRoot walks up from its own file until it finds a plugin.json whose name is antigravity-booster (or starts with antigravity-booster-). PLUGIN_ROOT is honored only if it resolves to that same directory, so tooling such as direnv cannot point agb at different assets. If no root is found it throws, because a missing root means a broken installation (lib/plugin-paths.mjs).

Bundled modeCopy Anchor Link

The plugin runs esbuild bundles (see Build and bundle) built with --define:__AGB_BUNDLED__=true. Source runs (npm test, local development) see the identifier as undefined. The switch is a single constant (lib/adlc-bridge.mjs):

export const IS_BUNDLED = typeof __AGB_BUNDLED__ !== 'undefined' && __AGB_BUNDLED__ === true;

When it is true, developer overrides are ignored, so a repository's .envrc cannot redirect a user's install:

The MCP server has its own copy of the same check to choose between the bundled dist/agb.mjs and bin/agb.mjs (mcp/server.mjs). Every bundled-mode guard on an environment variable is listed in Environment variables.

Resolving the companion plugin source (unbundled)Copy Anchor Link

In source runs, resolvePluginPath picks the adlc-antigravity source directory in this order (lib/bootstrap.mjs):

1. ADLC_ANTIGRAVITY_PLUGIN_PATH, if set.
2. @adlc/antigravity in node_modules, found with require.resolve('@adlc/antigravity/package.json') (the package has no main/exports, so the package.json subpath is what resolves).
3. The sibling checkout ../adlc/plugins/adlc-antigravity.

Vendored tarball pinningCopy Anchor Link

The plugin must work from a git-URL install with no npm install, so the repository commits the pristine npm release tarball of @adlc/antigravity at vendor/cache/adlc-antigravity-<version>.tgz. Its version and SHA-512 are constants (lib/plugin-paths.mjs). The pin is checked three ways:

• At install time: installPluginTarball refuses a tarball whose SHA-512 does not match (vendored-adlc-antigravity-tampered), validates the archive's entries, extracts it into a temp directory and installs it with agy plugin install (lib/plugin-paths.mjs). The integrity value cannot be overridden by a caller.
• In CI: the plugin-integrity job runs npm pack @adlc/antigravity@<version> and fails unless the committed tarball is byte-identical (.github/workflows/ci.yml). The version comes from package.json devDependencies, so the lockfile integrity must agree as well.
• After install: the staged plugin's directory tree digest must match the pinned digest for its version (below).

Bootstrap and doctor decision tableCopy Anchor Link

agb bootstrap and agb doctor share one evaluation of ~/.gemini/config/plugins/adlc-antigravity, evaluateStagedAdlcPlugin, applied in order (lib/doctor.mjs):

Bootstrap installs only from the vendored tarball, never rewrites files inside a staged plugin, and re-evaluates afterwards: the install counts only if it lands on a row where doctor exits 0 (lib/bootstrap.mjs). --force-reinstall always reinstalls.

agb migrateCopy Anchor Link

agb migrate moves an npm-global or checkout install onto the native plugin, and agb migrate --rollback restores the state from before the first migration. All state lives under ~/.gemini/antigravity-cli/plugin_data/antigravity-booster/ (lib/migrate.mjs):

LockCopy Anchor Link

The migration lock is separate from the repository run lock in lib/lock.mjs. It is an atomic mkdir. A holder is reclaimed only when it is positively dead (the PID is gone, or was recycled, detected by comparing process start times). A live or unverifiable holder is never stolen, and reclaiming never removes a lock directory whose token changed since it was inspected (lib/migration-lock.mjs). agb migrate --break-lock removes a stuck lock after a [y/N] prompt, or without one with --force.

StatesCopy Anchor Link

Each forward step writes the state file only after it finishes (lib/migrate.mjs, L348, L366), so a crash resumes from the last completed state.

All migrate entry points return an exit code (0 or 1) and do not throw.