Package Exports

zcf
zcf/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (zcf) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ZCF - Zero-Config Claude-Code Flow

中文 | English

Zero-config, one-click setup for Claude Code with bilingual support, intelligent agent system and personalized AI assistant

Rendering

🚀 Quick Start

npx zcf          # Open interactive menu and choose operations based on your needs

Menu options include:

1 Full initialization (equivalent to zcf i)
2 Import workflows (equivalent to zcf u)
3-6 Configuration management (API, MCP, Model, AI personality, etc.)
More features...

Or, use direct commands:

🆕 First time using Claude Code

npx zcf i        # Execute full initialization directly: Install Claude Code + Import workflows + Configure API + Set up MCP services
# or
npx zcf → select 1  # Execute full initialization via menu

🔄 Already have Claude Code installed

npx zcf u        # Update workflows only: Quick add AI workflows and command system
# or
npx zcf → select 2  # Execute workflow update via menu

🎯 BMad Workflow (New Feature)

BMad (Business-Minded Agile Development) is an enterprise-grade workflow system that provides:

Complete team of specialized AI agents (PO, PM, Architect, Dev, QA, etc.)
Structured development process with quality gates
Automatic documentation generation
Support for both greenfield and brownfield projects

After installation, use /bmad-init to initialize the BMad workflow in your project.

Note:

Since v2.0, zcf opens the interactive menu by default, providing a visual operation interface

You can choose operations through the menu or use commands directly for quick execution

zcf i = full initialization, zcf u = update workflows only

Setup Process

Full initialization (npx zcf) will automatically:

✅ Detect and install Claude Code
✅ Select AI output language (new feature)
✅ Configure API keys
✅ Select and configure MCP services
✅ Set up all necessary configuration files

Usage

After configuration:

For first-time project use, strongly recommend running /init to generate CLAUDE.md for better AI understanding of project architecture
<task description> - Execute directly without workflow, following SOLID, KISS, DRY, and YAGNI principles, suitable for small tasks like bug fixes
/feat <task description> - Start new feature development, divided into plan and UI phases
/workflow <task description> - Execute complete development workflow, not automated, starts with multiple solution options, asks for user feedback at each step, allows plan modifications, maximum control

PS:

Both feat and workflow have their advantages, try both to compare

Generated documents are located by default at .claude/xxx.md in project root, you can add .claude/ to your project's .gitignore

✨ ZCF Tool Features

🌏 Multi-language Support

Script interaction language: Controls installation prompts language
Configuration file language: Determines which configuration set to install (zh-CN/en)
AI output language: Choose the language for AI responses (supports Chinese, English, and custom languages)
AI personality: Support multiple preset personalities (Professional, Catgirl, Friendly, Mentor) or custom

🔧 Smart Installation

Auto-detects Claude Code installation status
Uses npm for automatic installation (ensures compatibility)
Cross-platform support (Windows/macOS/Linux/Termux)
Automatic MCP service configuration
Smart configuration merging and partial modification support (v2.0 new)
Enhanced command detection mechanism (v2.1 new)
Dangerous operation confirmation mechanism (v2.3 new)

📦 Complete Configuration

CLAUDE.md system instructions
settings.json configuration file
commands custom commands
agents AI agent configurations

🔐 API Configuration

Supports two authentication methods:
- Auth Token: For tokens obtained via OAuth or browser login
- API Key: For API keys from Anthropic Console
Custom API URL support
Support for manual configuration later
Partial modification: Update only needed configuration items (v2.0 new)

💾 Configuration Management

Smart backup of existing configurations (all backups saved in ~/.claude/backup/)
Configuration merge option (v2.0 enhanced: supports deep merge)
Safe overwrite mechanism
Automatic backup before MCP configuration changes
Default model configuration (v2.0 new)
AI memory management (v2.0 new)
ZCF cache cleanup (v2.0 new)

📖 Usage Instructions

$ npx zcf

 ZCF - Zero-Config Claude-Code Flow v2.3.0

? Select ZCF display language / 选择ZCF显示语言:
  ❯ 简体中文
    English

Select function:
  -------- Claude Code --------
  1. Full initialization - Install Claude Code + Import workflow + Configure API + Configure MCP services
  2. Import workflow - Import/update workflow-related files only
  3. Configure API - Configure API URL and authentication
  4. Configure MCP - Configure MCP services (includes Windows fix)
  5. Configure default model - Set default model (opus/sonnet)
  6. Configure Claude global memory - Configure AI output language and personality
  7. Import recommended environment variables and permissions - Import privacy protection environment variables and system permissions

  ------------ ZCF ------------
  0. Select display language / 更改显示语言 - Change ZCF interface language
  -. Clear preference cache - Clear preference language and other caches
  q. Exit

Enter your choice: _

Full Initialization Flow (Select 1 or use `zcf i`)

? Select Claude Code configuration language:
  ❯ 简体中文 (zh-CN) - Chinese (easier for Chinese users to customize)
    English (en) - English (recommended, lower token consumption)

? Select AI output language:
  AI will respond to you in this language
  ❯ 简体中文
    English
    Custom
    (Supports Japanese, French, German, and more)

? Select AI personality:
  ❯ Professional Assistant(Default)
    Catgirl Assistant
    Friendly Assistant
    Mentor Mode
    Custom

? Claude Code not found. Install automatically? (Y/n)

✔ Claude Code installed successfully

? Select API authentication method
  ❯ Use Auth Token (OAuth authentication)
    For tokens obtained via OAuth or browser login
    Use API Key (Key authentication)
    For API keys from Anthropic Console
    Skip (configure manually later)

? Enter API URL: https://api.anthropic.com
? Enter Auth Token or API Key: xxx

? Existing config detected. How to proceed?
  ❯ Backup and overwrite all
    Update workflow-related md files only with backup
    Merge config
    Skip

✔ All config files backed up to ~/.claude/backup/xxx
✔ Config files copied to ~/.claude

? Select workflows to install (space to select, enter to confirm)
  ❯ ◉ Six Steps Workflow (workflow) - Complete 6-phase development process
    ◉ Feature Planning and UX Design (feat + planner + ui-ux-designer) - Structured feature development
    ◉ BMAD-Method Extension Installer - Enterprise agile development workflow

✔ Installing workflows...
  ✔ Installed command: zcf/workflow.md
  ✔ Installed command: zcf/feat.md
  ✔ Installed agent: zcf/plan/planner.md
  ✔ Installed agent: zcf/plan/ui-ux-designer.md
  ✔ Installed command: zcf/bmad-init.md
✔ Workflow installation successful

✔ API configured

? Configure MCP services? (Y/n)

? Select MCP services to install (space to select, enter to confirm)
  ❯ ◯ Install all
    ◯ Context7 Documentation Query - Query latest library docs and code examples
    ◯ DeepWiki - Query GitHub repository docs and examples
    ◯ Playwright Browser Control - Direct browser automation control
    ◯ Exa AI Search - Web search using Exa AI

? Enter Exa API Key (get from https://dashboard.exa.ai/api-keys)

✔ MCP services configured

🎉 Setup complete! Use 'claude' command to start.

Command Line Options

Commands Quick Reference

Command	Alias	Description
`zcf`	-	Show interactive menu (v2.0 default command)
`zcf init`	`zcf i`	Initialize Claude Code configuration
`zcf update`	`zcf u`	Update workflow-related md files with backup

Common Options

# Specify configuration language
npx zcf --config-lang zh-CN
npx zcf -c zh-CN            # Using short option

# Force overwrite existing configuration
npx zcf --force
npx zcf -f                 # Using short option

# Update workflow-related md files with backup (preserve API and MCP configs)
npx zcf u                  # Using update command
npx zcf update             # Full command

# Show help information
npx zcf --help
npx zcf -h

# Show version
npx zcf --version
npx zcf -v

Usage Examples

# Show interactive menu (default)
npx zcf

# First-time installation, complete initialization
npx zcf i
npx zcf init              # Full command

# Update workflow-related md files with backup, keep API and MCP configs
npx zcf u
npx zcf update            # Full command

# Force reinitialize with Chinese config
npx zcf i --config-lang zh-CN --force
npx zcf i -c zh-CN -f      # Using short options

# Update to English prompts (lower token consumption)
npx zcf u --config-lang en
npx zcf u -c en            # Using short option

📁 Project Structure

zcf/
├── README.md              # Documentation
├── package.json           # npm package configuration
├── bin/
│   └── zcf.mjs           # CLI entry point
├── src/                  # Source code
│   ├── cli.ts           # CLI main logic
│   ├── commands/        # Command implementations
│   ├── utils/           # Utility functions
│   └── constants.ts     # Constant definitions
├── templates/            # Configuration templates
│   ├── CLAUDE.md        # Project level config (v2.0 new)
│   ├── settings.json    # Base configuration (with privacy env vars)
│   ├── en/              # English version
│   │   ├── rules.md     # Core principles (formerly CLAUDE.md)
│   │   ├── personality.md # AI personality (v2.0 new)
│   │   ├── mcp.md       # MCP services guide (v2.0 new)
│   │   ├── agents/      # AI agents
│   │   └── commands/    # Command definitions
│   └── zh-CN/           # Chinese version
│       └── ... (same structure)
└── dist/                # Build output

✨ Core Features (v2.0 Enhanced)

🤖 Professional Agents

Task Planner: Breaks down complex tasks into executable steps
UI/UX Designer: Provides professional interface design guidance
AI Personality: Support multiple preset personalities and custom (v2.0 new)
BMad Team (New): Complete agile development team including:
- Product Owner (PO): Requirements elicitation and prioritization
- Project Manager (PM): Planning and coordination
- System Architect: Technical design and architecture
- Developer: Implementation and coding
- QA Engineer: Testing and quality assurance
- Scrum Master (SM): Process facilitation
- Business Analyst: Requirements analysis
- UX Expert: User experience design

⚡ Command System

Feature Development (/feat): Structured new feature development
Workflow (/workflow): Complete six-phase development workflow
BMad Workflow (/bmad-init): Initialize BMad workflow for enterprise development
- Supports both greenfield (new projects) and brownfield (existing projects)
- Provides comprehensive templates for PRDs, architecture docs, and user stories
- Integrated quality gates and checklist system

🔧 Smart Configuration

API key management (supports partial modification)
Fine-grained permission control
Multiple Claude model support (configurable default model)
Interactive menu system (v2.0 new)
AI memory management (v2.0 new)

🎯 Development Workflow

Six-Phase Workflow

[Mode: Research] - Understand requirements
[Mode: Ideate] - Design solutions
[Mode: Plan] - Create detailed plan
[Mode: Execute] - Implement development
[Mode: Optimize] - Improve quality
[Mode: Review] - Final assessment

🛠️ Development

# Clone the project
git clone https://github.com/UfoMiao/zcf.git
cd zcf

# Install dependencies (using pnpm)
pnpm install

# Build project
pnpm build

# Local testing
node bin/zcf.mjs

💡 Best Practices

Task Breakdown: Keep tasks independent and testable
Code Quality: Follow SOLID, KISS, DRY, and YAGNI principles
Documentation Management: The plan will be stored in the .claude/plan/ directory at the project root

🔧 Troubleshooting

If you encounter issues:

Re-run npx zcf to reconfigure
Check configuration files in ~/.claude/ directory
Ensure Claude Code is properly installed
If paths contain spaces, ZCF will automatically handle quote wrapping
Use ripgrep (rg) preferentially for file searching for better performance

Cross-Platform Support

Windows Platform

ZCF fully supports Windows platform:

Auto-detection: Automatically uses compatible cmd /c npx format on Windows systems
Config repair: Existing incorrect configurations are automatically fixed during updates
Zero-config: Windows users don't need any extra steps, same experience as macOS/Linux

If you encounter MCP connection issues on Windows, running npx zcf will automatically fix the configuration format.

Termux Support (v2.1 new)

ZCF now supports running in Android Termux environment:

Auto-adaptation: Automatically detects Termux environment and uses compatible configuration
Enhanced detection: Intelligently identifies available commands, ensuring normal operation in restricted environments
Full functionality: Enjoy the same complete features in Termux as on desktop systems

Security Features (v2.3 new)

Dangerous Operation Confirmation Mechanism

To protect user data security, the following operations require explicit confirmation:

File System: Delete files/directories, bulk modifications, move system files
Code Commits: git commit, git push, git reset --hard
System Config: Modify environment variables, system settings, permissions
Data Operations: Database deletions, schema changes, bulk updates
Network Requests: Send sensitive data, call production APIs
Package Management: Global install/uninstall, update core dependencies

🙏 Acknowledgments

Some prompts in this project are inspired by the following excellent works:

Thanks to these community contributors for sharing!

📄 License

MIT License

If this project helps you, please give me a ⭐️ Star!

zcf