cl-preset 0.5.2

A package for managing Claude Code configuration presets and strategies

cl-preset

A Python package for managing Claude Code configuration presets and strategies.

Overview

cl-preset allows you to package your Claude Code strategies and install them with different scopes (global, user, or project). This makes it easy to share and distribute custom configurations across projects and teams.

Features

• Package Management: Create, install, and uninstall preset packages
• Multiple Scopes: Install presets globally, per-user, or per-project
• CLI Interface: Simple command-line interface for all operations
• Rich Output: Beautiful terminal output with formatted tables
• Validation: Built-in metadata validation for preset packages
• Git Strategy Management: Built-in git workflow strategies with validation

Installation

pip install cl-preset

Or using uv:

uv pip install cl-preset

Quick Start

Interactive Mode (Recommended)

The easiest way to get started is the interactive mode:

cl-preset

This will launch an interactive selector that guides you through:

1. Welcome Screen - Beautiful introduction to cl-preset
2. Strategy Selection - Browse and select from available strategies (presets and git strategies)
3. Scope Selection - Choose installation scope (global, user, or project)
4. Installation - Automatic installation with progress feedback

Available strategies include:

• web-development-strategy - Preset for web development with FastAPI and React
• dual-repo-git-strategy - Dev/Release repository separation workflow
• github-flow-git-strategy - Simple branch-based workflow
• git-flow-git-strategy - Feature/release/hotfix branching model

Create a New Preset

# Initialize a new preset scaffold
cl-preset init my-strategy

# This creates a directory structure:
# my-strategy/
#   ├── agents/       # Agent definitions
#   ├── skills/       # Skill definitions
#   ├── commands/     # Command definitions
#   └── examples/     # Usage examples

Install a Preset

# Install from a local directory
cl-preset install ./my-strategy --name my-strategy --description "My custom strategy"

# Install with specific scope
cl-preset install ./my-strategy --name my-strategy --description "My custom strategy" --scope global

List Installed Presets

# List all installed presets
cl-preset list

# List presets by scope
cl-preset list --scope user
cl-preset list --scope project
cl-preset list --scope global

# Output as JSON
cl-preset list --json

Get Preset Information

cl-preset info my-strategy

Uninstall a Preset

cl-preset uninstall my-strategy

# Uninstall from specific scope
cl-preset uninstall my-strategy --scope user

Command Reference

init

Initialize a new preset scaffold.

cl-preset init NAME [OPTIONS]

Options:

• --output, -o: Output path for preset metadata (default: ./preset.json)

install

Install a preset from a source directory.

cl-preset install SOURCE_PATH [OPTIONS]

Options:

• --name, -n: Unique name for the preset (required)
• --version, -v: Version (default: 1.0.0)
• --description, -d: Description of the preset (required)
• --author, -a: Author name
• --type, -t: Type of preset (agent|skill|command|strategy)
• --scope, -s: Installation scope (global|user|project)

list

List installed presets.

cl-preset list [OPTIONS]

Options:

• --scope, -s: Filter by scope
• --json: Output as JSON

info

Show detailed information about an installed preset.

cl-preset info NAME

uninstall

Uninstall a preset by name.

cl-preset uninstall NAME [OPTIONS]

Options:

• --scope, -s: Filter by scope

Git Strategy Management

cl-preset includes built-in git workflow strategies that you can apply to your projects. These strategies define branching patterns, merge rules, and branch protection configurations.

Available Strategies

dual-repo

Dev/Release repository separation workflow.

• Dev repository: Active development, feature branches, experimental work
• Release repository: Production-ready code, stable releases, published documentation
• Promotion workflow: Create release branch, review, merge to release repository

github-flow

Simple branch-based workflow.

• Feature branches from main
• Pull requests for review
• Direct merge to main after approval
• No release/develop branches

git-flow

Feature/release/hotfix branching model.

• master: Production-ready code
• develop: Integration branch for features
• feature/: Feature development branches
• release/: Release preparation branches
• hotfix/: Emergency fixes for production

Git Commands

git list

List available git strategies.

cl-preset git list
cl-preset git list --no-builtin  # Only custom strategies

git info

Show detailed information about a git strategy.

cl-preset git info dual-repo
cl-preset git info github-flow

git export

Export a git strategy to a YAML file.

cl-preset git export dual-repo
cl-preset git export dual-repo -o ./my-strategy.yaml

git apply

Apply a git strategy to the current project.

# Apply a strategy
cl-preset git apply github-flow

# Dry run to see what would be configured
cl-preset git apply github-flow --dry-run

This creates a .moai/config/sections/git-strategy.yaml file with the strategy configuration.

git validate

Validate current git setup against a strategy.

cl-preset git validate github-flow

This checks:

• Current branch matches strategy expectations
• Required branches exist (main, develop, etc.)
• Required remotes are configured
• Repository state matches the strategy

Creating Custom Strategies

You can create custom git strategies by exporting a built-in strategy and modifying it:

# Export a built-in strategy as a starting point
cl-preset git export github-flow -o ./my-custom-strategy.yaml

# Edit the YAML file to customize
# Then use it as a reference for your project

Strategy configuration format:

name: my-custom-strategy
strategy_type: custom
description: "A custom git workflow"

main_branch: main
develop_branch: develop

branch_patterns:
  feature: "feature/*"
  bugfix: "bugfix/*"
  release: "release/*"
  hotfix: "hotfix/*"

merge_rules:
  require_pr: true
  require_approval: true
  allow_squash: true
  allow_merge_commit: false
  allow_rebase: false

protection_rules:
  main:
    enabled: true
    require_status_checks: true
    required_check_names: ["ci", "tests"]
    allow_force_pushes: false
    allow_deletions: false

Git Strategy Integration with MoAI

When you apply a git strategy using cl-preset git apply, it:

1. Creates .moai/config/sections/git-strategy.yaml
2. Configures branch naming patterns
3. Sets up merge rule recommendations
4. Defines branch protection rules

This integrates with MoAI's git workflow commands and ensures consistent branching patterns across your team.

Scopes

Presets can be installed at three different scopes:

Scope	Path	Description
global	/usr/local/share/cl-preset/{name}	Available to all users on the system
user	~/.claude/presets/{name}	Available only to the current user (default)
project	.claude/presets/{name}	Available only in the current project

Preset Structure

A valid preset directory contains:

my-preset/
├── agents/           # Agent definition files
├── skills/           # Skill definition files
├── commands/         # Command definition files
├── examples/         # Usage examples
└── preset.json       # Preset metadata (generated during install)

Metadata

Each preset has metadata defined in preset.json:

{
  "name": "my-preset",
  "version": "1.0.0",
  "description": "My custom Claude Code strategy",
  "author": "Your Name",
  "license": "MIT",
  "preset_type": "strategy",
  "tags": ["web", "api", "fastapi"]
}

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yarang/cl-preset
cd cl-preset

# Install with dev dependencies
uv sync --dev

Run Tests

uv run pytest

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type check
uv run mypy src/

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Author

William Jung - @yarang

Links

• GitHub Repository
• Issue Tracker