Extension System

Build and share extensions to extend Gemini CLI's functionality. Create tools, commands, themes, and integrations for the community.

Extension Types

Different types of extensions you can create

Tool Extensions

Add new tools and capabilities

Examples:

  • Database connectors
  • API integrations
  • File processors
  • Data analyzers

Command Extensions

Add new CLI commands

Examples:

  • Project generators
  • Deployment scripts
  • Testing utilities
  • Code formatters

Theme Extensions

Customize the CLI appearance

Examples:

  • Color schemes
  • Output formats
  • Progress indicators
  • Custom prompts

Integration Extensions

Connect with external services

Examples:

  • GitHub integration
  • Slack notifications
  • Email alerts
  • Cloud storage

Extension Structure

How to organize your extension files

Directory Structure

my-extension/
├── package.json          # Extension metadata
├── index.js              # Main entry point
├── tools/                # Custom tools
│   ├── my-tool.js
│   └── another-tool.js
├── commands/             # Custom commands
│   └── my-command.js
├── themes/               # Custom themes
│   └── my-theme.json
├── README.md             # Documentation
└── tests/                # Test files
    └── extension.test.js

Package.json Configuration

{
  "name": "gemini-cli-my-extension",
  "version": "1.0.0",
  "description": "My awesome Gemini CLI extension",
  "main": "index.js",
  "keywords": ["gemini-cli", "extension", "tools"],
  "author": "Your Name",
  "license": "MIT",
  "gemini-cli": {
    "version": "^2.0.0",
    "type": "extension",
    "tools": ["./tools/my-tool.js"],
    "commands": ["./commands/my-command.js"],
    "themes": ["./themes/my-theme.json"]
  },
  "dependencies": {
    "@google/generative-ai-cli": "^2.0.0"
  }
}

Creating Extensions

Step-by-step guide to building your first extension

1

Initialize Extension

Create a new directory and initialize your extension with the CLI generator.

mkdir my-extension
cd my-extension
gemini extension init
2

Implement Features

Add your tools, commands, or other features to the extension.

// tools/my-tool.js
export const myTool = {
  name: 'my_custom_tool',
  description: 'Does something useful',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input data' }
    },
    required: ['input']
  },
  execute: async ({ input }) => {
    return `Processed: ${input}`;
  }
};
3

Test Extension

Test your extension locally before publishing.

# Install locally for testing
npm link

# Load extension in Gemini CLI
gemini extension load ./my-extension

# Test your tools
gemini ask "Use my custom tool" --tools my_custom_tool
4

Publish Extension

Publish your extension to npm for others to use.

# Build and test
npm run build
npm test

# Publish to npm
npm publish

# Install from npm
npm install -g gemini-cli-my-extension

Extension Management

Commands for managing extensions

Installation Commands

gemini extension install <name>

Install an extension from npm

gemini extension load <path>

Load a local extension

gemini extension uninstall <name>

Remove an extension

Management Commands

gemini extension list

List installed extensions

gemini extension info <name>

Show extension details

gemini extension search <query>

Search for extensions

Best Practices

Guidelines for creating quality extensions

Development

  • Follow semantic versioning
  • Include comprehensive tests
  • Write clear documentation
  • Handle errors gracefully

Publishing

  • Use descriptive package names
  • Include relevant keywords
  • Provide usage examples
  • Maintain backward compatibility

Related Resources

Learn more about extension development

Tool DevelopmentPlugin APIContributing Guide