Lifecycle & Packaging

An extension's lifecycle has four phases: install, activate, operate, and teardown. Install downloads the package and registers it in Gemini CLI's extension registry. Activate starts any MCP servers the extension provides and loads context into the session. Operate is the steady state — tools are available, context is active. Teardown stops MCP servers and releases resources when the session ends or the extension is removed. Understanding this lifecycle matters because bugs at each phase produce different symptoms.

Packaging follows npm conventions with Gemini-specific additions. The package contains the gemini-extension.json manifest, any MCP server code (typically a Node.js script), context files (markdown), and optional configuration templates. The manifest's activate and deactivate hooks let you run setup and cleanup scripts — useful for extensions that need to compile code, check dependencies, or validate credentials before the MCP server starts.

{
  "name": "my-extension",
  "version": "1.0.0",
  "type": "tool",
  "description": "Custom tools for internal API integration",
  "tools": {
    "server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_BASE_URL": "${MY_API_URL}"
      }
    }
  },
  "permissions": [
    "network:api.internal.com"
  ],
  "hooks": {
    "postInstall": "npm install",
    "preActivate": "node validate-credentials.js"
  }
}