clew

Declarative Claude Code configuration management - like Brewfile for Homebrew, but for Claude Code plugins and marketplaces.

The Problem

When syncing Claude Code config across workstations with yadm (or similar):

• installed_plugins.json references paths that don't exist on other machines
• Plugin cache directories aren't synced, so plugins appear "installed" but won't load
• You're syncing state rather than intent

The Solution

Declare your desired configuration in a Clewfile, sync that across machines, run clew sync.

# ~/.config/claude/Clewfile
# yaml-language-server: $schema=https://raw.githubusercontent.com/adamancini/clew/main/schema/clewfile.schema.json
---
version: 1

marketplaces:
  claude-plugins-official:
    source: github
    repo: anthropics/claude-plugins-official

plugins:
  - context7@claude-plugins-official
  - superpowers@superpowers-marketplace
  - name: linear@claude-plugins-official
    enabled: false

Installation

go install github.com/adamancini/clew@latest

Or download a release binary:

curl -L https://github.com/adamancini/clew/releases/latest/download/clew-$(uname -s)-$(uname -m) \
  -o ~/.local/bin/clew && chmod +x ~/.local/bin/clew

Once installed, you can keep clew up to date with clew version --update.

Auto-Update

Clew can update itself to the latest version:

# Check for updates
clew version --check

# Install the latest version
clew version --update

The update process:

1. Checks GitHub releases for the latest version
2. Downloads the appropriate binary for your platform
3. Verifies the download with SHA256 checksums
4. Creates a backup of your current binary
5. Replaces the binary atomically
6. Verifies the new binary works
7. Automatically rolls back if anything fails

Supported platforms: macOS (Intel/Apple Silicon), Linux (amd64/arm64)

Environment variables:

• GITHUB_TOKEN - Optional, prevents API rate limiting

Security:

• All downloads use HTTPS
• SHA256 checksums always verified
• Automatic rollback on verification failure
• Backup created before any changes

Quick Start

# Export your current Claude Code setup to a Clewfile
clew export > ~/.claude/Clewfile.yaml

# Sync another machine to match your Clewfile
clew sync

# Check what would change before syncing
clew diff

Usage

# Export current state to Clewfile
clew export > ~/.claude/Clewfile.yaml

# Sync system to match Clewfile
clew sync

# Show what would change (dry-run)
clew diff

# Check status
clew status

# Check for clew updates
clew version --check

# Update clew to latest version
clew version --update

Commands

Command	Description
clew sync	Reconcile system to match Clewfile (with auto-backup)
clew diff	Dry-run preview of changes
clew export	Export current state to Clewfile format
clew status	Show current configuration status
clew backup	Backup and restore configuration
clew version	Version information and auto-update
clew completion	Shell completion (bash/zsh/fish)

Create a Clewfile

Option 1: Export from existing setup (recommended)

clew export > ~/.claude/Clewfile.yaml

Option 2: Write manually

version: 1

marketplaces:
  claude-plugins-official:
    source: github
    repo: anthropics/claude-plugins-official

plugins:
  - context7@claude-plugins-official
  - episodic-memory@claude-plugins-official

Interactive Mode

Use --interactive or -i to review and approve each change individually:

# Interactive sync - approve each change before applying
clew sync --interactive
clew sync -i

# Interactive diff - preview changes with prompts (dry-run)
clew diff --interactive

Interactive mode prompts for each marketplace and plugin change:

$ clew sync --interactive

Marketplaces:
  + private-marketplace (will add)
    -> Add private-marketplace from github:you/plugins? [y/n/a/q] y

Plugins:
  + pr-review-toolkit@claude-plugins-official (will add)
    -> Add pr-review-toolkit@claude-plugins-official? [y/n/a/q] y

  - linear@claude-plugins-official (will disable)
    -> Disable linear@claude-plugins-official? [y/n/a/q] n
    - Skipped

Summary:
  Will apply: 2 changes
  Skipped: 1

Proceed with sync? [y/n] y

Installed: 2

Prompt options:

• y - Yes, approve this change
• n - No, skip this change
• a - All, approve all remaining changes
• q - Quit, abort interactive mode

Non-TTY fallback: When not running in a terminal (e.g., in scripts or CI), interactive mode automatically falls back to non-interactive mode with a warning.

Output Modes

By default, sync shows verbose output with commands and descriptions:

$ clew sync

Add: Installing plugin context7
> claude plugin install context7@claude-plugins-official
* Success

Enable: Enabling plugin linear
> claude plugin enable linear@claude-plugins-official
* Success

Summary:
  Installed: 1
  Updated: 1
  Failed: 0

Use --short for concise one-line-per-item output:

$ clew sync --short

* context7 (plugin add)
* linear (plugin enable)

Summary: 1 installed, 1 updated

The short format is ideal for scripts and CI pipelines where you want minimal output.

Backup and Restore

clew can backup your Claude Code configuration before making changes, allowing easy rollback if something goes wrong.

# Create a backup
clew backup create
clew backup create --note "Before plugin update"

# List all backups
clew backup list
clew backup list -o json

# Restore from a backup
clew backup restore <id>
clew backup restore latest

# Delete a specific backup
clew backup delete <id>

# Remove old backups (keep last N)
clew backup prune --keep=10

Auto-Backup on Sync

By default, clew sync creates a backup before making changes:

# Default behavior - backup created automatically
clew sync

# Explicitly request backup
clew sync --backup

# Skip backup creation
clew sync --no-backup

Backup Storage

Backups are stored in ~/.cache/clew/backups/ as JSON files named with timestamps (e.g., 2024-01-08-143022.json).

Each backup contains:

• Timestamp and optional note
• clew version that created the backup
• Complete state: marketplaces and plugins

Flags

-o, --output <format>       # Output: text (default), json, yaml
-i, --interactive           # Interactive mode (sync/diff only)
--config <path>             # Explicit Clewfile path
--strict                    # Exit non-zero on any failure (sync only)
--short                     # One-line per item output (sync only)
--verbose                   # Detailed output
--quiet                     # Errors only

Shell Completion

clew supports shell completion for bash, zsh, and fish.

Installation

Bash:

# Linux (system-wide)
clew completion bash | sudo tee /etc/bash_completion.d/clew > /dev/null

# macOS (Homebrew)
clew completion bash > $(brew --prefix)/etc/bash_completion.d/clew

# Load in current session
source <(clew completion bash)

Zsh:

# Oh My Zsh
mkdir -p ~/.oh-my-zsh/completions
clew completion zsh > ~/.oh-my-zsh/completions/_clew

# Standard zsh (add to fpath)
clew completion zsh > /usr/local/share/zsh/site-functions/_clew

# Load in current session
source <(clew completion zsh)

Fish:

clew completion fish > ~/.config/fish/completions/clew.fish

After installation, restart your shell or source the completion script.

Clewfile Location

clew searches (first found wins):

1. --config flag or CLEWFILE env var
2. $XDG_CONFIG_HOME/claude/Clewfile[.yaml|.toml|.json]
3. ~/.claude/Clewfile[.yaml|.toml|.json]
4. ~/.Clewfile[.yaml|.toml|.json]

Supports YAML, TOML, and JSON formats (auto-detected by extension).

IDE Support

clew includes a JSON Schema for Clewfile validation and auto-completion:

YAML files - Add schema reference at the top:

# yaml-language-server: $schema=https://raw.githubusercontent.com/adamancini/clew/main/schema/clewfile.schema.json
---
version: 1

JSON files - Add $schema property:

{
  "$schema": "https://raw.githubusercontent.com/adamancini/clew/main/schema/clewfile.schema.json",
  "version": 1
}

See schema/README.md for IDE setup details and examples.

Documentation

See docs/design.md for full architecture and specification.

Contributing

All pull requests to main require a version bump. Before creating a PR:

1. Update version in .claude-plugin/plugin.json
2. Add entry to CHANGELOG.md with new version and changes
3. Ensure version is greater than latest git tag

See .github/WORKFLOWS.md for detailed workflow documentation.

License

MIT