How the Converter CLI Handles Tool Name Mapping for Factory Droid

The converter CLI translates Claude Code plugin tool identifiers into Factory Droid-compatible tool names using a static mapping table and agent-level content detection implemented in src/converters/claude-to-droid.ts.

The EveryInc/compound-engineering-plugin repository provides a specialized converter CLI that bridges Claude Code plugins with the Factory Droid runtime. Understanding how this converter CLI handles tool name mapping for Factory Droid is essential for developers migrating agents between these ecosystems, as it ensures that tool capabilities are automatically translated without manual intervention.

The Two-Stage Tool Name Mapping Process

The conversion logic operates through a deterministic two-stage pipeline that first defines the relationships between tool naming conventions, then detects which tools are actually required by specific agents.

Stage 1: Static Name-to-Name Translation

At the core of the converter lies the CLAUDE_TO_DROID_TOOLS constant, defined at [src/converters/claude-to-droid.ts#L8-L24]. This static record maps every supported Claude tool identifier to its Factory Droid equivalent.

For example, the mapping translates read to Read, write to Create, and webfetch to FetchUrl. This ensures that when the CLI encounters a Claude tool reference, it can immediately resolve the correct Droid runtime name without ambiguity.

Stage 2: Agent-Level Tool Detection

While the static table defines possible translations, the mapAgentTools function at [src/converters/claude-to-droid.ts#L101-L113] determines which tools are actually required for a specific agent. This function scans the agent's name, description, and body fields for any mentions of Claude tool keywords.

When a keyword is detected, the corresponding Droid tool name from the static mapping is added to a set of required tools. This approach allows the converter to infer tool dependencies from natural language descriptions and implementation code without requiring explicit tool declarations in the source plugin.

Core Implementation Details

The conversion logic relies on precise string matching and validation to ensure accurate tool mapping.

The static mapping table covers the complete spectrum of Claude Code capabilities:

// src/converters/claude-to-droid.ts
const CLAUDE_TO_DROID_TOOLS: Record<string, string> = {
  read: "Read",
  write: "Create",
  edit: "Edit",
  multiedit: "Edit",
  bash: "Execute",
  grep: "Grep",
  glob: "Glob",
  list: "LS",
  ls: "LS",
  webfetch: "FetchUrl",
  websearch: "WebSearch",
  task: "Task",
  todowrite: "TodoWrite",
  todoread: "TodoWrite",
  question: "AskUser",
}

The agent detection logic concatenates the agent's metadata into a single lowercase string for case-insensitive matching:

// src/converters/claude-to-droid.ts
function mapAgentTools(agent: ClaudeAgent): string[] | undefined {
  const bodyLower = `${agent.name} ${agent.description ?? ""} ${agent.body}`.toLowerCase()
  const mentionedTools = new Set<string>()
  for (const [claudeTool, droidTool] of Object.entries(CLAUDE_TO_DROID_TOOLS)) {
    if (bodyLower.includes(claudeTool)) {
      mentionedTools.add(droidTool)
    }
  }
  if (mentionedTools.size === 0) return undefined
  return [...mentionedTools].filter(t => VALID_DROID_TOOLS.has(t)).sort()
}

Validation and Safety Checks

To prevent the emission of unsupported tool names, the converter validates all detected tools against the VALID_DROID_TOOLS set defined at [src/converters/claude-to-droid.ts#L26-L40]. This whitelist ensures that only tools recognized by the Factory Droid runtime are included in the final agent configuration.

If a Claude tool maps to a Droid tool not present in the validation set, it is filtered out during the final array construction in mapAgentTools. This defensive programming approach maintains compatibility and prevents runtime errors in the Factory Droid environment.

Integration with the CLI Pipeline

The tool mapping functionality integrates into the broader conversion pipeline through the convertClaudeToDroid function, which orchestrates the transformation of entire Claude plugins into Factory Droid format.

The Droid target is registered in [src/targets/index.ts], wiring the conversion logic into the CLI's command-line interface. This allows users to invoke the converter via standard CLI commands, automatically triggering the tool name mapping process for every agent in the source plugin.

Comprehensive test coverage in [tests/droid-converter.test.ts] validates the correct mapping of tools, ensuring that changes to the static tables or detection logic do not break the conversion pipeline.

Summary

• The converter CLI uses a static mapping table (CLAUDE_TO_DROID_TOOLS) to translate Claude tool identifiers into Factory Droid tool names.
• Agent-level detection scans agent metadata for tool keywords using mapAgentTools, automatically inferring required capabilities.
• Validation against VALID_DROID_TOOLS ensures only supported Droid tools are emitted in the final agent configuration.
• The implementation resides in [src/converters/claude-to-droid.ts] and integrates with the CLI through [src/targets/index.ts].

Frequently Asked Questions

What is the purpose of the CLAUDE_TO_DROID_TOOLS mapping table?

The CLAUDE_TO_DROID_TOOLS table serves as the authoritative dictionary that maps Claude Code tool identifiers (like read, write, or bash) to their Factory Droid equivalents (such as Read, Create, or Execute). This static definition ensures consistent translation across all conversion operations without requiring runtime inference of semantic equivalents.

How does the converter detect which tools an agent needs?

The converter employs the mapAgentTools function to perform content analysis on each agent. It concatenates the agent's name, description, and body into a single lowercase string, then searches for occurrences of any Claude tool keywords. When a match is found, the corresponding Droid tool is added to the agent's required tools list, enabling automatic capability detection from natural language descriptions.

What prevents invalid or unsupported tools from being included in the output?

All detected tools pass through a validation filter using the VALID_DROID_TOOLS set before being written to the final agent configuration. This whitelist approach ensures that only tools recognized by the Factory Droid runtime are emitted. If a mapping exists in CLAUDE_TO_DROID_TOOLS but the target tool is not in the validation set, it is silently filtered out during the array construction in mapAgentTools.

Where can I find the test suite that validates this tool mapping logic?

The conversion logic and tool mapping accuracy are verified by the test suite located at [tests/droid-converter.test.ts]. These tests validate that the static mapping tables correctly translate tool names and that the agent detection logic accurately identifies required capabilities from various agent configurations, ensuring the reliability of the converter CLI across different plugin structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}