ohmyzsh-ai-cli-plugins: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains a collection of Oh My Zsh plugins that provide intelligent auto-completion for AI CLI tools:

• claude - Anthropic Claude Code CLI completion
• codex - OpenAI Codex CLI completion
• gemini - Google Gemini CLI completion

Each plugin is self-contained in its own directory with a single .plugin.zsh file.

Language Guidelines

IMPORTANT: All written content in this repository must be in English, including:

• Code comments
• Documentation files (README, CLAUDE.md, etc.)
• Commit messages
• Pull request descriptions
• Issue reports
• Code variable names and function names

EXCEPTION: When communicating with the repository owner in conversation/chat, use Chinese (中文).

This ensures the codebase remains accessible to the international open-source community while maintaining effective communication with the primary maintainer.

Core Architecture

Plugin Structure Pattern

All plugins follow a consistent Zsh completion architecture:

1. Main completion function (_<tool_name>) - Entry point that handles:

   • Global options via _arguments
   • Top-level command dispatching via state machine
   • Delegates to subcommand-specific completion functions

2. Subcommand completion functions (_<tool_name>_<subcommand>) - Nested handlers for:

   • Multi-level command hierarchies (e.g., claude mcp add, gemini extensions install)
   • Context-aware parameter completion
   • Dynamic completion (e.g., listing configured MCP servers)

3. Registration and aliases - At file end:

   • compdef directives to register completion functions
   • Command aliases for convenience

Key Patterns

State machine pattern for command routing:

_arguments -C \
    '1: :->command' \
    '*::arg:->args'

case $state in
    command)
        _describe -t commands 'commands' commands
        ;;
    args)
        case $line[1] in
            subcommand)
                _tool_subcommand
                ;;
        esac
        ;;
esac