Introduction
Extending the Gemini CLI allows you to integrate custom tools and workflows directly into your agent's environment. This guide covers the lifecycle of creating, validating, and using custom extensions.
Scaffolding a New Extension
To start, use the gemini extensions new command. This utility generates a production-ready boilerplate, setting up the necessary directory structure, configuration files, and build scripts.
Extension Structure
A typical extension consists of:
- package.json: Manages dependencies and metadata.
- src/index.ts: The main entry point where tools are defined and exported.
- gemini.config.json: Configuration specific to how the CLI loads the extension.
Creating Tools
Tools are the functional units of your extension. You define them by exporting functions that adhere to the Tool interface, which includes a name, description, and an input schema (typically using Zod) so the agent knows how to call them correctly.
Validation
Before using your extension, run gemini extensions validate. This command performs a static analysis of your project, checking for common errors, missing metadata, and invalid tool schemas.
Linking for Development
To test your extension locally without publishing it, use the linking feature. This usually involves running npm link in your extension directory and then connecting it to your main CLI instance.