Extension

Introduction

Tuanjie AI Extension is a powerful extension system that lets you extend the functionality of Codely CLI and share these capabilities with others. Through Extensions, you can package prompts, MCP servers, custom commands, themes, hooks, subagents, and agent skills into an easy-to-install format that can be shared with the community.

What Is an Extension?

An Extension is a feature extension package for Codely CLI that can package multiple functional components together for easy installation and distribution.

Core features:

• Modular: Can package multiple functional components together
• Configurable: Supports settings and dependency management
• Version control: Supports version management and updates

What Can Extensions Do?

Extensions provide multiple ways to customize Codely CLI:

Feature	Description	Use Case	Trigger Method
MCP Servers	Standard way to expose new tools and data sources to models	When you need the model to perform new operations, such as fetching data from internal APIs, querying databases, or controlling local applications	Model
Custom Commands	Shortcuts like /my-cmd that execute predefined prompts or shell commands	For repetitive tasks or saving commonly used complex prompts, ideal for automation	User
Context Files (codely.md)	Markdown files containing instructions that are loaded into model context at the start of each session	Define the "personality" of the extension, set coding standards, or provide key knowledge the model should know	CLI provides to model
Agent Skills	Specialized sets of instructions and workflows that are only activated when needed	For complex, occasionally executed tasks (like "create PR" or "security audit"), so they don't clutter the main context window when not in use	Model
Hooks	Intercept and customize CLI behavior at specific lifecycle events (before/after tool calls)	When you want to automatically execute actions based on what the model is doing, such as validating tool parameters, logging activity, or modifying the model's input/output	CLI
Custom Themes	A set of color definitions to personalize the CLI interface	To give extensions a unique visual identity, or provide professional high-contrast or themed color schemes	User (through /theme)

Advantages of Extensions

• Easy installation: One-click installation of multiple functional components
• Centralized management: All extension functionality is centrally managed
• Community sharing: Easy to share with teams and community
• Version control: Supports version management and updates

Using Extensions via GUI

Opening Extension Management

1. Open Command Input Box

   • Find the command input area at the bottom of the main interface

2. Enter Extension Management Command

   • Type / to open the command menu
   • Select "Manage extension" option

3. Manage Extensions

   • You can select extensions we provide for direct use
   • You can also create your own extension

4. Use Extensions

   • After creation, your newly created extension can be directly invoked via @

Using Extensions via CLI

Managing Extensions

You can verify installed Extensions and their status using interactive commands:

/extensions list

You can also manage Extensions using command groups in the terminal:

codely extensions list

Installing Extensions

Install an Extension by providing a GitHub repository URL:

codely extensions install https://github.com/your-username/your-extension

Other Management Commands

Uninstall an Extension:

codely extensions uninstall <extension-name>

Update an Extension:

codely extensions update <extension-name>

View Extension information:

codely extensions info <extension-name>

After installing an Extension, restart the Codely CLI session to start using the new features.

How to Create an Extension

Prerequisites

Before you begin, make sure:

1. Codely CLI is installed
2. You have basic understanding of Node.js

Step 1: Create a New Extension

The easiest way to get started is to use the built-in template. We'll use the mcp-server example as a base.

Run the following command to create a new directory named my-first-extension with template files:

codely extensions new my-first-extension mcp-server

This will create a directory with the following structure:

my-first-extension/
├── example.js
├── gemini-extension.json
└── package.json

Step 2: Understand Extension Files

Your Extension contains several key files that define its behavior.

gemini-extension.json

The manifest file tells Codely CLI how to load and use your Extension.

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

• name: Unique name of the Extension
• version: Extension version
• mcpServers: Defines Model Context Protocol (MCP) servers used to add new tools
• command, args, cwd: Specify how to start the server. The ${extensionPath} variable will be replaced with the absolute path of the Extension directory

example.js

This file contains the source code for the MCP server. It uses @modelcontextprotocol/sdk to define tools.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

// Register a new tool named 'fetch_posts'
server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches a list of posts from a public API.',
    inputSchema: z.object({}).shape,
  },
  async () => {
    const apiResponse = await fetch(
      'https://jsonplaceholder.typicode.com/posts',
    );
    const posts = await apiResponse.json();
    const response = { posts: posts.slice(0, 5) };
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response),
        },
      ],
    };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

package.json

Standard configuration file for Node.js projects, defining dependencies and scripts for the Extension.

Step 3: Add Extension Settings

Some Extensions need configuration, such as API keys or user preferences. Let's add a setting for an API key.

1. Open gemini-extension.json

2. Add a settings array to the configuration:

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "The API key for the service.",
      "envVar": "MY_SERVICE_API_KEY",
      "sensitive": true
    }
  ],
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

When a user installs this Extension, Codely CLI will prompt them to enter the "API Key". This value will be securely stored in the system keychain (because sensitive is true) and injected into the MCP server process as the MY_SERVICE_API_KEY environment variable.

Step 4: Link Your Extension

Link your Extension to your Codely CLI installation for local development.

1. Install dependencies:

cd my-first-extension
npm install

2. Link the Extension:

codely extensions link .

The link command creates a symbolic link from the Codely CLI Extension directory to your development directory. Changes you make will be reflected immediately.

3. Restart the Codely CLI session to use the new fetch_posts tool. Test by asking to "fetch posts".

Step 5: Add Custom Commands

Custom commands create shortcuts for complex prompts.

1. Create a commands directory and a subdirectory for the command group

macOS/Linux:

mkdir -p commands/fs

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "commands\fs"

2. Create the file commands/fs/grep-code.toml:

prompt = """
Summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""

This command /fs:grep-code accepts an argument, runs the grep shell command, and pipes the results to the prompt for summarization.

3. After saving the file, restart Codely CLI. Run /fs:grep-code "some pattern" to use your new command.

Step 6: Add Custom GEMINI.md

Provide persistent context to the model by adding a GEMINI.md file to the Extension. This is useful for setting behavior or providing important tool information.

1. Create a file named GEMINI.md in the root of the Extension directory:

# My First Extension Instructions

You are an expert developer assistant. When the user asks you to fetch
posts, use the `fetch_posts` tool. Be concise in your responses.

2. Update your gemini-extension.json to load this file:

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "contextFileName": "GEMINI.md",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

3. Restart Codely CLI. Now, in every session where the Extension is active, the model will have context from the GEMINI.md file.

Step 7: (Optional) Add Agent Skills

Agent Skills package expertise and workflows. Skills are only activated when needed, thus saving context tokens.

1. Create a skills directory and a subdirectory for the skill

macOS/Linux:

mkdir -p skills/security-audit

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "skills\security-audit"

2. Create the skills/security-audit/SKILL.md file:

---
name: security-audit
description:
  Expertise in auditing code for security vulnerabilities. Use when the user
  asks to "check for security issues" or "audit" their changes.
---

# Security Auditor

You are an expert security researcher. When auditing code:

1. Look for common vulnerabilities (OWASP Top 10).
2. Check for hardcoded secrets or API keys.
3. Suggest remediation steps for any findings.

3. Codely CLI will automatically discover skills packaged with your Extension. When the model recognizes related tasks, it will activate these skills.

Step 8: Publish Your Extension

When your Extension is ready, you can share it with others through Git repositories or GitHub Releases. For detailed instructions, refer to the Extension Publishing Guide and learn how to list your Extension in the Gallery.

Common Questions

Q: How do I view installed Extensions?

A: Use the /extensions list or codely extensions list command to view all installed Extensions and their status.

Q: What's the difference between Extensions and custom commands?

A: Extensions are a packaging system that can contain multiple functional components (such as MCP servers, custom commands, skills, etc.), while custom commands are just one type of functionality within Extensions.

Q: How do I update Extensions?

A: Use the codely extensions update <extension-name> command to update the specified Extension to the latest version.

Q: Where are Extension settings stored?

A: Extension settings are stored in the system keychain to ensure the security of sensitive information. For non-sensitive settings, they are stored in configuration files.

Best Practices

Developing Extensions

1. Use Templates: Start with official templates to ensure correct structure
2. Local Testing: Use codely extensions link . for local development testing
3. Version Management: Follow semantic versioning conventions
4. Clear Documentation: Write clear documentation and usage examples for your Extension

Sharing Extensions

1. Open Source Release: Publish your Extension through a GitHub repository
2. Clear Description: Clearly explain the functionality and purpose of the Extension in the README
3. Rich Examples: Provide detailed usage examples and demonstrations
4. Maintenance Updates: Promptly fix bugs and add new features

Security Considerations

1. Sensitive Data: Use sensitive: true to mark sensitive settings
2. Code Review: Ensure the security of MCP server code
3. Permission Control: Set appropriate permissions for custom commands
4. Dependency Check: Regularly check and update dependencies

---

Document Version: 2.0 Last Updated: March 25, 2026