claude-code-forge

claude-code-forge

CLI tool to initialize Claude Code workspace with templates.

Installation

npm install -g claude-code-forge

Or use directly with npx:

npx claude-code-forge

Usage

# Basic usage - interactive mode
npx claude-code-forge

# Specify target directory
npx claude-code-forge ./my-project

# With explicit repo
npx claude-code-forge --repo github.com/myorg/template

# Force SSH auth
npx claude-code-forge --ssh

# Use token auth
npx claude-code-forge --token ghp_xxxx

# Preview changes without making them
npx claude-code-forge --dry-run

# Overwrite without prompts
npx claude-code-forge --force

# Skip specific folders
npx claude-code-forge --skip-docs --skip-plans

Environment Variables

CLAUDE_FORGE_REPO=github.com/myorg/template
CLAUDE_FORGE_TOKEN=ghp_xxxx

CLI Options

Option	Description
[target-dir]	Target directory (default: .)
--repo <url>	Template repository URL
--ssh	Use SSH authentication
--token <pat>	Use GitHub Personal Access Token
--force	Overwrite existing files without prompts
--dry-run	Preview changes only
--skip-docs	Skip docs/ folder
--skip-plans	Skip plans/ folder
-h, --help	Display help
-V, --version	Display version

Configuration

The tool saves configuration to ~/.claudeforgerc:

{
  "repo": "github.com/myorg/template",
  "auth": "ssh"
}

Configuration Priority

Repository URL:

• --repo flag
• CLAUDE_FORGE_REPO env
• ~/.claudeforgerc
• Interactive prompt

Authentication:

• --ssh flag
• --token flag
• CLAUDE_FORGE_TOKEN env
• Auto-detect SSH key
• ~/.claudeforgerc
• Interactive prompt

What Gets Copied

• .claude/ - Workflows, skills, commands, agents
• docs/ - Project documentation
• plans/ - Implementation plans
• CLAUDE.md - Claude Code instructions

Conflict Handling

When existing files are detected:

• Overwrite all - Replace existing files
• Merge - Keep existing, add only new files
• Skip - Don't copy conflicting files
• Cancel - Abort operation

Use --force to overwrite without prompts.

Troubleshooting

SSH Authentication Failed

# Check if SSH key exists
ls ~/.ssh/id_*

# Test GitHub SSH access
ssh -T [e-mail]

Token Authentication Failed

Ensure your PAT has repo scope for private repositories.

Network Error

Check your internet connection and try again.

Development

# Clone
git clone https://github.com/nicholashopee/claude-code-forge
cd claude-code-forge

# Install dependencies
npm install

# Link for local testing
npm link

# Test
claude-code-forge --help

License

MIT