# How Claude-to-Gemini CLI Conversion Handles Namespaced Commands: A Complete Technical Guide

> Learn how Claude-to-Gemini CLI conversion handles namespaced commands by transforming colon-delimited names into filesystem paths and creating subdirectories. Master command conversion with this technical guide.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: deep-dive
- Published: 2026-02-16

---

**The Claude-to-Gemini CLI conversion pipeline transforms colon-delimited command names into filesystem hierarchies by parsing namespaces, generating slash-separated path keys, and automatically creating subdirectories during the bundle write phase.**

The EveryInc/compound-engineering-plugin repository provides a robust conversion utility that bridges Claude Desktop's command structure with Google's Gemini CLI format. Understanding how this Claude-to-Gemini CLI conversion handles namespaced commands is essential for developers migrating complex plugin architectures while preserving hierarchical command organization.

## Understanding Namespaced Commands in Claude-to-Gemini CLI Conversion

Claude Desktop plugins use colon-delimited namespaces (e.g., `workflows:plan`) to organize commands hierarchically. The Gemini CLI, however, expects a flat filesystem structure where directories represent namespaces. The conversion utility resolves this mismatch by transforming colons into path separators during the conversion process.

## Step-by-Step Namespace Parsing and Path Resolution

### Parsing the Colon-Delimited Namespace

When the converter encounters a namespaced command, it invokes `resolveCommandPath` in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-gemini.ts) (lines 36-38). This helper splits the command name on the `:` character and normalizes each segment:

```typescript
// From src/converters/claude-to-gemini.ts
const segments = commandName.split(':').map(s => s.trim().toLowerCase());
// Example: "workflows:plan" becomes ["workflows", "plan"]

```

### Generating the Path Key

The segmented array is then joined with `/` to produce a **path key**. The `uniqueName` call (lines 61-66) registers this key for deduplication, but the key itself becomes the command's logical identifier:

```typescript
// Path key generation
const pathKey = segments.join('/'); // "workflows/plan"
const uniqueId = uniqueName(pathKey, existingNames); // Handles collisions

```

## Converting Namespaced Commands to Gemini Bundle Entries

The converter returns a `GeminiCommand` object where the `name` field contains the slash-separated path key. The rest of the command metadata (description, prompt, permissions) is rendered to TOML format via the `toToml` function (lines 75-77):

```typescript
// GeminiCommand structure
{
  name: "workflows/plan",
  content: toToml({
    description: command.description,
    prompt: command.prompt,
    // ... other fields
  })
}

```

## Filesystem Layout for Namespaced Commands

When writing the bundle to disk, `writeGeminiBundle` in [`src/targets/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/gemini.ts) (lines 21-25) constructs file paths using `path.join`. Because `command.name` may contain slashes, the filesystem automatically creates the necessary subdirectories:

```typescript
// From src/targets/gemini.ts
await writeText(
  path.join(paths.commandsDir, `${command.name}.toml`), 
  command.content + "\n"
);
// Results in: .gemini/commands/workflows/plan.toml

```

This approach ensures that a command originally named `workflows:plan` in Claude becomes [`workflows/plan.toml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/workflows/plan.toml) in the Gemini CLI structure, preserving the hierarchical relationship through the filesystem.

## Practical Examples of Claude-to-Gemini Namespaced Command Conversion

### Programmatic Conversion

```typescript
import { convertClaudeToGemini } from "./src/converters/claude-to-gemini";
import type { GeminiBundle } from "./src/types/gemini";

const bundle: GeminiBundle = convertClaudeToGemini(myClaudePlugin, {
  agentMode: "subagent",
  inferTemperature: false,
  permissions: "none",
});

// Access the converted command
const planCommand = bundle.commands.find(c => c.name === "workflows/plan");
console.log(planCommand?.name); // "workflows/plan"

```

### Resulting Command Structure

```json
{
  "name": "workflows/plan",
  "content": "description = \"Planning command\"\nprompt = \"\"\"\nPlan the work.\n\"\"\""
}

```

### CLI Usage

```bash

# Convert a Claude plugin to Gemini format

opencode convert --from claude --to gemini path/to/claude-plugin

# Generated structure includes:

#   .gemini/commands/workflows/plan.toml

```

## Summary

- **Namespace parsing**: The `resolveCommandPath` function in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-gemini.ts) splits Claude's colon-delimited names on `:` and normalizes each segment.
- **Path key generation**: Segments are joined with `/` to create a path key (e.g., `workflows/plan`) that serves as the unique command identifier.
- **Filesystem mapping**: The `writeGeminiBundle` function in [`src/targets/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/gemini.ts) uses `path.join` to automatically create subdirectories from slash-separated names, producing a TOML file per command in the appropriate namespace folder.
- **Result**: Namespaced Claude commands are faithfully preserved in Gemini's filesystem-based command structure without naming collisions.

## Frequently Asked Questions

### How does the conversion handle multiple colons in a command name?

The `resolveCommandPath` function splits on every colon, creating nested namespaces. A command named `dev:workflows:plan` becomes `dev/workflows/plan`, resulting in a three-level directory structure when written to disk. Each segment is normalized (trimmed and lowercased) to ensure valid filesystem paths.

### What prevents naming collisions between namespaced commands?

The converter uses a `uniqueName` helper that tracks existing path keys during the conversion process. If two commands would resolve to the same path key (e.g., `workflows:plan` and `workflows-plan` without proper namespacing), the function appends a numeric suffix to ensure uniqueness in the generated Gemini bundle.

### Can I customize the output directory depth for converted commands?

The directory structure is determined by the command names themselves and cannot be arbitrarily flattened without modifying the source code. However, you can control the base output directory through the `paths.commandsDir` parameter passed to `writeGeminiBundle`. The relative path structure (derived from colons) is preserved to maintain command organization.

### Does the Gemini CLI recognize subdirectories as command namespaces automatically?

Yes, the Gemini CLI scans the `.gemini/commands` directory recursively. When the converter creates subdirectories like [`workflows/plan.toml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/workflows/plan.toml), the Gemini CLI interprets this as a namespaced command accessible via `gemini workflows plan`. The filesystem hierarchy directly maps to the command invocation syntax without additional configuration.