Extension Types & Anatomy

Gemini CLI extensions come in three forms: tool extensions (provide new tools the model can call), context extensions (inject additional GEMINI.md-style instructions and project context), and composite extensions (bundle both tools and context into a single package). The extension manifest — gemini-extension.json — declares which type the extension is, what capabilities it provides, and what permissions it requires. Understanding the manifest is understanding the extension system.

Tool extensions are the most common. They wrap an MCP server into an installable package — instead of manually configuring mcpServers in settings.json, you run gemini extensions install and the extension handles registration, startup, and teardown. Context extensions are less common but equally powerful. They inject specialized knowledge into every session — a context extension for a framework like Rails might inject architecture patterns, naming conventions, and common pitfalls that the model should know about.

Composite extensions bundle everything. Google's Firebase extension is a composite: it provides MCP tools (deploy, query Firestore, manage auth) and context (Firebase architecture conventions, security rules best practices). The packaging is transparent — the manifest lists tools and context separately, and Gemini CLI loads each component through its own subsystem. You can install a composite extension and use includeTools to filter which tools are active.

1. Inspect existing extensions Run gemini extensions list and examine the manifest of each installed extension. Note which are tool, context, or composite types. Study how they declare capabilities.
2. Read the manifest schema The gemini-extension.json schema defines name, version, type, tools (for tool extensions), context (for context extensions), permissions, and dependencies. Study the schema before building — it constrains your design.
3. Map your use case to a type Before building, decide: are you providing tools, knowledge, or both? This decision affects your manifest structure, packaging, and how users will configure your extension.