AI Command Converter

Bi-directional converter between Claude Code and Gemini CLI command formats. This library enables seamless sharing of AI commands between different CLI tools, fostering a more connected AI assistant ecosystem.

Features

• 🔄 Bi-directional conversion between Claude Code (.md) and Gemini CLI (.toml) formats
• 🎯 Smart parameter mapping with type conversion and validation
• ⚡ CLI tool for batch conversions
• 📦 Programmatic API for integration into other tools
• 🔍 Compatibility checking with detailed warnings
• 📝 Format preservation maintains metadata and structure where possible

Installation

npm install -g ai-command-converter

Or use in your project:

npm install ai-command-converter

Quick Sync Setup

To automatically sync your Claude Code and Gemini CLI commands:

# One-time bi-directional sync
npx ai-command-sync sync

# Watch for changes and auto-sync
npx ai-command-sync watch

# Sync in one direction only
npx ai-command-sync sync --direction claude-to-gemini

Quick Start

CLI Usage

Convert a single file:

ai-command-converter convert blog-writer.md --output blog-writer.toml

Convert an entire directory:

ai-command-converter convert ./claude-commands --output ./gemini-commands --format toml

Programmatic Usage

import { ClaudeCodeCommand, GeminiCommand, Converter } from 'ai-command-converter';

// Parse a Claude Code command
const claudeCmd = await ClaudeCodeCommand.fromFile('./commands/blog-writer.md');

// Convert to Gemini format
const geminiCmd = await Converter.toGemini(claudeCmd);

// Save the converted command
await geminiCmd.saveToFile('~/.gemini/commands/blog-writer.toml');

// Or go the other direction
const geminiCmd = await GeminiCommand.fromFile('./blog.toml');
const claudeCmd = await Converter.toClaudeCode(geminiCmd);

Command Sync

Keep your Claude Code and Gemini CLI commands automatically synchronized:

Basic Sync

# Sync all commands between ~/.claude/commands and ~/.gemini/commands
npx ai-command-sync sync

# Dry run to see what would change
npx ai-command-sync sync --dry-run

# Verbose output
npx ai-command-sync sync --verbose

Watch Mode

Automatically sync changes as they happen:

# Watch for changes every 5 seconds (default)
npx ai-command-sync watch

# Custom check interval
npx ai-command-sync watch --interval 10

Advanced Options

# Custom directories
npx ai-command-sync sync \
  --claude-dir ~/my-claude-commands \
  --gemini-dir ~/my-gemini-commands

# One-way sync
npx ai-command-sync sync --direction claude-to-gemini
npx ai-command-sync sync --direction gemini-to-claude

# Conflict resolution strategies
npx ai-command-sync sync --conflict newest  # Use newest file (default)
npx ai-command-sync sync --conflict skip    # Skip conflicts
npx ai-command-sync sync --conflict prompt  # Interactive prompt

Organization Support

The sync tool preserves organization structure:

• Claude: ~/.claude/commands/github-import.md
• Gemini: ~/.gemini/commands/anthropic/github-import.toml

Commands are matched by name, supporting both flat and organized structures.

Format Examples

Key Differences

• Claude Code: Uses {{parameter}} placeholders for each parameter
• Gemini CLI: Uses {{args}} for all arguments, which the AI parses based on the prompt instructions

Claude Code Format (.md)

---
title: "Generate Blog Post"
description: "Creates a blog post on any topic"
params:
  - name: topic
    type: string
    required: true
    description: "The blog topic"
  - name: tone
    type: enum
    options: [neutral, playful, formal]
    default: neutral
---

# Instructions

Write a comprehensive blog post about {{topic}} in a {{tone}} tone...

Gemini CLI Format (.toml)

description = "Creates a blog post on any topic"

prompt = """
Parse the provided arguments: {{args}}

Expected parameters:
- topic: The blog topic [required]
- tone: Writing tone (default: neutral) [optional]

Write a comprehensive blog post about the specified topic in the requested tone...
"""

API Reference

Core Classes

ClaudeCodeCommand

• static fromFile(path) - Parse a .md file
• static fromString(content) - Parse markdown content
• toObject() - Get command as plain object
• validate() - Validate command structure

GeminiCommand

• static fromFile(path) - Parse a .toml file
• static fromString(content) - Parse TOML content
• toObject() - Get command as plain object
• validate() - Validate command structure

Converter

• static async toGemini(claudeCommand, options) - Convert to Gemini format
• static async toClaudeCode(geminiCommand, options) - Convert to Claude format
• static validate(command, targetFormat) - Check compatibility

Conversion Options

const options = {
  // Preserve organization structure in output path
  preserveNamespace: true,
  
  // Include source metadata in converted files
  includeSourceMetadata: true,
  
  // Validation strictness
  strict: false,
  
  // Custom parameter mapping (advanced use)
  parameterMapping: {
    'topic': 'subject'
  }
};

const geminiCmd = await Converter.toGemini(claudeCmd, options);

Compatibility

Supported Features

Feature	Claude → Gemini	Gemini → Claude
Basic metadata	✅	✅
String parameters	✅	✅
Enum parameters	⚠️ Converted to string	✅ Inferred from usage
Optional params	✅	✅
Default values	✅	⚠️ Parsed from usage
Multi-line content	✅	✅
MCP requirements	⚠️ Added as comment	❌ Not supported

Limitations

• Gemini → Claude: Parameter types must be inferred from usage documentation
• Claude → Gemini: Complex parameter types are simplified to strings
• Both directions: Some metadata may be lost in conversion

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE for details.

Credits

Created by Commands.com to foster interoperability in the AI CLI ecosystem.