# How Claude Command Namespacing Converts to Directory Structures in the Compound Engineering Plugin

> Learn how Claude command namespacing converts to directory structures. Discover how colon-separated commands create safe nested subdirectories for your Node.js projects with the Compound Engineering Plugin.

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

---

**Claude command namespacing converts to directory structures by splitting colon-separated command names into path segments, normalizing each segment for filesystem safety, and joining them with forward slashes so that Node.js path utilities automatically create nested subdirectories during the Gemini bundle conversion process.**

The EveryInc/compound-engineering-plugin bridges Claude Desktop plugins with Gemini bundles, handling the transformation of Claude's colon-based command namespacing into hierarchical directory structures. Understanding how **Claude command namespacing** maps to filesystem paths is essential for debugging conversion issues and organizing large command sets logically.

## Understanding Claude Command Namespacing

Claude Desktop plugins support **namespaced commands** using colon notation (e.g., `workflows:plan`). This convention allows developers to group related commands under logical categories, preventing name collisions and improving discoverability. When the compound-engineering-plugin converts these commands for Gemini compatibility, it preserves this hierarchy by translating colons into directory separators.

## The Conversion Pipeline: From Colons to Directories

The transformation from Claude command namespacing to directory structures occurs in three distinct phases within the converter logic.

### Step 1: Parsing Namespace Segments

The process begins in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-gemini.ts) where the `resolveCommandPath` function splits the command name on colons and normalizes each segment:

```typescript
function resolveCommandPath(name: string): string[] {
  return name.split(":").map((segment) => normalizeName(segment))
}

```

This function takes a name like `workflows:plan` and returns an array `["workflows", "plan"]` after applying filesystem-safe normalization to each segment【link src/converters/claude-to-gemini.ts#L62-L66】.

### Step 2: Building the Filesystem Path

The converter then joins these segments with forward slashes to create a path key:

```typescript
const commandPath = resolveCommandPath(command.name)
const pathKey = commandPath.join("/")
uniqueName(pathKey, usedNames) // tracks deduplication

```

The `pathKey` variable now contains the slash-separated path (e.g., `"workflows/plan"`), which serves as the unique identifier for the command file【link src/converters/claude-to-gemini.ts#L62-L66】.

### Step 3: Writing to Nested Directories

Finally, the [`src/targets/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/gemini.ts) writer uses Node.js path utilities to create the nested structure:

```typescript
await writeText(path.join(paths.commandsDir, `${command.name}.toml`), command.content + "\n")

```

Because `command.name` contains the forward slashes from the previous step (e.g., `"workflows/plan"`), `path.join` automatically creates the `workflows` subdirectory before writing [`plan.toml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/plan.toml)【link src/targets/gemini.ts#L21-L25】.

## Code Example: Converting a Namespaced Command

Consider a Claude plugin command defined as:

```json
{
  "name": "workflows:plan",
  "description": "Create a plan for the workflow",
  "body": "Generate a comprehensive plan..."
}

```

After conversion by the compound-engineering-plugin, this becomes the following filesystem structure:

```

.gemini/
 └─ commands/
     └─ workflows/
         └─ plan.toml

```

The TOML file contains:

```toml
description = "Create a plan for the workflow"
prompt = """Generate a comprehensive plan..."""

```

## Why Directory-Based Namespacing Matters

This conversion strategy provides three critical benefits for Gemini bundle compatibility:

* **Logical grouping** – Namespaces become physical folders, making large command sets navigable in file explorers and version control systems.
* **Compatibility with Gemini CLI** – The Gemini CLI expects commands under `commands/` with optional sub-folders that map to command groups, matching the converted structure exactly.
* **Deterministic deduplication** – The `uniqueName` helper tracks the full path key (e.g., `"workflows/plan"`), ensuring that two commands with identical names in different namespaces cannot clash during conversion.

## Summary

* Claude command namespacing uses colons (`:`) to separate logical segments (e.g., `category:command`).
* The converter in [`src/converters/claude-to-gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-gemini.ts) splits these names on colons and normalizes each segment via `resolveCommandPath`.
* Segments are joined with forward slashes to create a filesystem path like `category/command`.
* The writer in [`src/targets/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/gemini.ts) uses `path.join` with these slash-separated names, causing Node.js to automatically create nested subdirectories.
* The resulting directory structure mirrors the original namespace hierarchy, ensuring Gemini CLI compatibility and logical command organization.

## Frequently Asked Questions

### What delimiter does Claude use for command namespacing?

Claude Desktop plugins use the **colon (`:`)** as the namespace delimiter. For example, a command named `workflows:plan` indicates that "workflows" is the namespace and "plan" is the specific command within that group.

### How does the plugin prevent naming conflicts between namespaced commands?

The plugin uses a `uniqueName` helper function that tracks the full **path key** (e.g., `"workflows/plan"`) rather than just the final command name. This ensures that two commands like `workflows:plan` and `templates:plan` are treated as distinct entries because their full path keys differ, preventing filesystem collisions during the conversion process.

### Can namespaces be nested deeper than one level?

Yes, the conversion logic supports **arbitrary nesting depths**. A command named `team:workflows:plan` would be split into three segments (`["team", "workflows", "plan"]`), resulting in a directory structure of [`.gemini/commands/team/workflows/plan.toml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.gemini/commands/team/workflows/plan.toml). The `resolveCommandPath` function handles any number of colon-separated segments.

### What file extension is used for converted command files?

The plugin writes converted commands as **TOML files** (`.toml` extension). During the write phase in [`src/targets/gemini.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/gemini.ts), the code explicitly appends `.toml` to the command name (e.g., `${command.name}.toml`), resulting in files like [`plan.toml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/plan.toml) within their respective namespace directories.