claude-code-compatibility

Overview

Factory.ai Droid provides built-in import functionality for Claude Code configurations. This document details the compatibility between the two platforms for slash commands, custom agents, skills, and MCP servers.

Bottom Line: High compatibility with explicit import support. Most Claude Code configurations transfer with minimal adjustments.

Compatibility Summary

1. Custom Slash Commands

File Location Mapping

YAML Frontmatter Comparison

Argument Handling Differences

Example - Claude Code:

---
description: Review a PR
argument-hint: <pr-number>
allowed-tools: Bash(git:*)
---
Review PR #$1 focusing on:
!git diff origin/main...HEAD

Equivalent - Factory Droid:

---
description: Review a PR
argument-hint: <pr-number>
---
Review PR #$ARGUMENTS focusing on code quality.

For Bash integration in Factory, create an executable script:

#!/bin/bash
git diff origin/main...HEAD
echo "Review PR #$1"

Import Process

1. Open Factory CLI
2. Type /commands
3. Press I to launch import flow
4. Select Claude commands from .claude/commands/ or ~/.claude/commands/
5. Commands copy to ~/.factory/commands/

Press R in /commands to reload without restarting.

2. Custom Agents → Custom Droids

File Location Mapping

YAML Frontmatter Comparison

Tool Mapping

When importing Claude Code agents, Factory maps tools:

Valid Factory Tools:

• Read-only: Read, LS, Grep, Glob
• Edit: Create, Edit, MultiEdit, ApplyPatch
• Execute: Execute
• Web: WebSearch, FetchUrl
• MCP: Dynamically populated from servers

Import Process

1. Open Factory CLI
2. Type /droids
3. Press I to launch import flow
4. CLI scans:
   • <repo>/.claude/agents/ (project)
   • ~/.claude/agents/ (personal)
5. Select agents to import
6. Factory maps metadata:
   • Agent name → Droid name
   • Description + instructions → Droid description + prompt
   • Model references → Factory equivalents
7. Files written to ~/.factory/droids/

Validation Warnings

The DroidValidator surfaces:

• Errors: Invalid names, unknown models, invalid tools
• Warnings: Missing descriptions, duplicate names, unmapped tools

Agents marked “(already exists)” are pre-deselected.

Example Conversion

Claude Code Agent (.claude/agents/security-reviewer.md):

---
name: security-reviewer
description: Reviews code for security vulnerabilities
model: sonnet
tools:
  - Read
  - Grep
  - Write
---
You are a security expert. Review code for:
1. OWASP Top 10 vulnerabilities
2. Injection attacks
3. Authentication issues

Factory Droid (.factory/droids/security-reviewer.md):

---
name: security-reviewer
description: Reviews code for security vulnerabilities
model: claude-sonnet-4-5-20250929
tools:
  - Read
  - Grep
  - Edit
  - Create
---
You are a security expert. Review code for:
1. OWASP Top 10 vulnerabilities
2. Injection attacks
3. Authentication issues

Note: Write → Edit + Create, model specified explicitly.

3. Skills

Conceptual Alignment

Both platforms use skills as auto-discovered, reusable capabilities:

File Structure

Migration

No automatic import. Manual migration:

1. Copy skill directory structure
2. Ensure SKILL.md has name and description frontmatter
3. Update any tool references

Factory Skill Structure:

.factory/skills/
└── code-review/
    ├── SKILL.md
    └── checklist.md  # Optional supporting files

SKILL.md Format:

---
name: code-review
description: Comprehensive code review following team standards
---
# Code Review Workflow

1. Check for security vulnerabilities
2. Verify test coverage
3. Review naming conventions
...

4. Project Context Files

AGENTS.md Standard

Factory has joined the AGENTS.md collaboration with OpenAI to standardize AI agent project context.

Recommendation: Use AGENTS.md going forward. Factory supports CLAUDE.md for backward compatibility.

Content Compatibility

Both files serve the same purpose:

• Project-specific instructions
• Build/test commands
• Style guidelines
• Security considerations

Content from CLAUDE.md transfers directly to AGENTS.md.

5. MCP Server Compatibility

Factory Droid has native MCP support identical to Claude Code:

MCP servers configured for Claude Code work with Factory Droid.

6. Authentication & Subscription Options

Key Question: Can you use your Claude Code subscription (Pro/Max) with Factory Droid?

Direct Answer

Not directly, but there are workarounds:

Option 1: BYOK with Anthropic API Key (Recommended)

Factory’s free tier supports “Bring Your Own Key” (BYOK) - use your Anthropic API key directly:

Configuration (~/.factory/config.json):

{
  "custom_models": [
    {
      "model_display_name": "Claude Sonnet 4.5",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://api.anthropic.com",
      "api_key": "sk-ant-api03-YOUR_KEY_HERE",
      "provider": "anthropic"
    },
    {
      "model_display_name": "Claude Opus 4",
      "model": "claude-opus-4-20250514",
      "base_url": "https://api.anthropic.com",
      "api_key": "sk-ant-api03-YOUR_KEY_HERE",
      "provider": "anthropic"
    }
  ]
}

Required Fields:

• model: Model identifier (e.g., claude-sonnet-4-5-20250929)
• base_url: API endpoint (https://api.anthropic.com)
• api_key: Your Anthropic API key (cannot be empty)
• provider: Must be anthropic, openai, or generic-chat-completion-api

Optional Fields:

• model_display_name: Human-readable name in /model selector
• max_tokens: Maximum output tokens
• supports_images: Boolean for image input support
• extra_args: Provider-specific parameters (temperature, top_p)
• extra_headers: Custom HTTP headers

Usage:

# Switch models in Factory CLI
/model
# Select your custom Claude model from the list

Key Benefits:

• API keys remain local (never uploaded to Factory)
• Factory automatically uses prompt caching when available
• Full benchmarked performance with official Anthropic API

Option 2: CLIProxyAPI for Subscription Users

If you have Claude Code Max subscription and want to avoid API costs, use CLIProxyAPI:

How it works:

Factory CLI → CLIProxyAPI (localhost:8317) → Anthropic API

The proxy intercepts requests, strips dummy API keys, and substitutes valid OAuth tokens from your Claude subscription.

Setup:

# 1. Install CLIProxyAPI (requires Go 1.24+)
git clone <cli-proxy-api-repo>
cd cli-proxy-api && go build

# 2. Authenticate with Claude subscription
./cli-proxy-api --claude-login
# Opens browser for OAuth authentication

# 3. Start proxy
./cli-proxy-api
# Listens on localhost:8317

Factory Configuration:

{
  "custom_models": [
    {
      "model_display_name": "Claude Sonnet (Subscription)",
      "model": "claude-sonnet-4-20250514",
      "base_url": "http://localhost:8317",
      "api_key": "dummy-key-ignored-by-proxy",
      "provider": "anthropic"
    }
  ]
}

Known Limitations:

• /compress command may not work with custom models
• Requires local proxy running during sessions
• Subject to Claude subscription rate limits

Option 3: Factory Paid Plans

Factory’s paid plans include their own token allocations:

Paid plans include access to Claude, GPT-5, and other models without separate API keys.

Cost Comparison

Migration Checklist

Quick Migration (5 minutes)

1. Import slash commands: /commands → I
2. Import agents: /droids → I
3. Review tool mapping warnings
4. Test imported configurations

Full Migration

1. Import slash commands
2. Import custom agents
3. Review and fix tool mapping issues
4. Manually migrate skills
5. Convert CLAUDE.md to AGENTS.md (optional)
6. Verify MCP server configurations
7. Test all workflows

Known Limitations

Not Transferable

1. Positional arguments in Markdown commands - Factory only supports $ARGUMENTS in Markdown; use scripts for $1, $2
2. allowed-tools frontmatter - Reserved for future use in Factory
3. NotebookEdit tool - No Factory equivalent
4. disable-model-invocation - Not available in Factory

Requires Manual Adjustment

1. Bash integration - Convert !command to shebang scripts
2. Write tool - Split to Edit + Create
3. Task subagents - Different mechanism (native droids)
4. Model references - May need explicit model IDs

Performance Comparison

From Terminal-Bench (2025):

Factory Droid extracts more capability from the same models.

Resources

Factory Documentation:

• Custom Droids
• Custom Slash Commands
• Skills
• AGENTS.md Announcement

Claude Code Documentation:

• Custom Slash Commands
• Sub-Agents

Comparison Articles:

• Factory.ai Guide
• Breaking Free from AI Lock-In

Authentication & BYOK:

• BYOK Overview
• Factory Pricing
• CLIProxyAPI for Subscriptions

Last updated: 2025-11-28