ccpm 0.3.17

Claude Code Package Manager - A Git-based package manager for Claude agents
Documentation

CCPM - Claude Code Package Manager

⚠️ Beta Software: This project is in active development and may contain breaking changes. Use with caution in production environments.

A Git-based package manager for Claude Code resources that enables reproducible installations using lockfile-based dependency management, similar to Cargo.

Features

  • 📦 Lockfile-based dependency management - Reproducible installations like Cargo/npm with staleness detection
  • 🌐 Git-based distribution - Install from any Git repository (GitHub, GitLab, Bitbucket)
  • 🚀 No central registry - Fully decentralized approach
  • 🔒 Lockfile staleness detection - Automatic detection of outdated or inconsistent lockfiles
  • 🔧 Six resource types - Agents, Snippets, Commands, Scripts, Hooks, MCP Servers
  • 🎯 Pattern-based dependencies - Use glob patterns (agents/*.md, **/*.md) for batch installation
  • 🖥️ Cross-platform - Windows, macOS, and Linux support with enhanced path handling
  • 📁 Local and remote sources - Support for both Git repositories and local filesystem paths

Quick Start

Install CCPM

Using installer script (Recommended):

# Unix/Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/aig787/ccpm/releases/latest/download/ccpm-installer.sh | sh

# Windows PowerShell
irm https://github.com/aig787/ccpm/releases/latest/download/ccpm-installer.ps1 | iex

Using Cargo:

cargo install ccpm                                    # From crates.io
cargo binstall ccpm                                   # Pre-built binaries (faster)
cargo install --git https://github.com/aig787/ccpm.git  # Latest development

For more installation options, see the Installation Guide.

Create a Project

# Initialize a new CCPM project
ccpm init

# Or manually create ccpm.toml:

[sources]
community = "https://github.com/aig787/ccpm-community.git"

[agents]
example-agent = { source = "community", path = "agents/example.md", version = "v1.0.0" }

[snippets]
react-utils = { source = "community", path = "snippets/react/*.md", version = "^1.0.0" }

Install Dependencies

# Install all dependencies and generate lockfile
ccpm install

# Use exact lockfile versions (for CI/CD)
ccpm install --frozen

# Force installation when lockfile is stale
ccpm install --force

# Regenerate lockfile from scratch
ccpm install --regenerate

# Control parallelism (default: max(10, 2 × CPU cores))
ccpm install --max-parallel 8

# Bypass cache for fresh installation
ccpm install --no-cache

Adding Dependencies

# Add a Git source repository
ccpm add source community https://github.com/aig787/ccpm-community.git

# Add dependencies from Git sources
ccpm add dep agent community:agents/rust-expert.md@v1.0.0
ccpm add dep snippet community:snippets/react.md --name react-utils

# Add local file dependencies
ccpm add dep agent ./local-agents/helper.md --name my-helper
ccpm add dep script ../shared/scripts/build.sh

# Add pattern dependencies (bulk installation)
ccpm add dep agent "community:agents/ai/*.md@v1.0.0" --name ai-agents

See the Command Reference for all supported dependency formats.

Core Commands

Command Description
ccpm init Initialize a new project
ccpm install Install dependencies from ccpm.toml with parallel processing
ccpm update Update dependencies within version constraints
ccpm outdated Check for available updates to installed dependencies
ccpm upgrade Self-update CCPM to the latest version
ccpm list List installed resources
ccpm validate Validate manifest and dependencies
ccpm add Add sources or dependencies
ccpm remove Remove sources or dependencies
ccpm config Manage global configuration
ccpm cache Manage the Git cache

Run ccpm --help for full command reference.

Resource Types

CCPM manages six types of resources:

  • Agents - AI assistant configurations (.claude/agents/)
  • Snippets - Reusable code templates (.claude/ccpm/snippets/)
  • Commands - Claude Code slash commands (.claude/commands/)
  • Scripts - Executable automation files (.claude/ccpm/scripts/)
  • Hooks - Event-based automation (merged into .claude/settings.local.json)
  • MCP Servers - Model Context Protocol servers (merged into .mcp.json)

Documentation

Example Project

# ccpm.toml
[sources]
community = "https://github.com/aig787/ccpm-community.git"
local = "./local-resources"

[agents]
# Single file
rust-expert = { source = "community", path = "agents/rust-expert.md", version = "v1.0.0" }

# Pattern matching - install multiple files
ai-agents = { source = "community", path = "agents/ai/*.md", version = "^1.0.0" }

[snippets]
react-hooks = { source = "community", path = "snippets/react-hooks.md", version = "~1.2.0" }

[scripts]
build = { source = "local", path = "scripts/build.sh" }

[hooks]
pre-commit = { source = "community", path = "hooks/pre-commit.json", version = "v1.0.0" }

[mcp-servers]
filesystem = { source = "community", path = "mcp/filesystem.json", version = "latest" }

Performance Architecture

CCPM v0.3.2+ features a high-performance SHA-based architecture:

Centralized Version Resolution

  • VersionResolver: Batch resolution of all dependency versions to commit SHAs
  • Minimal Git Operations: Single fetch per repository per command
  • Upfront Resolution: All versions resolved before any worktree operations

SHA-Based Worktree Deduplication

  • Commit-Level Caching: Worktrees keyed by commit SHA, not version reference
  • Maximum Reuse: Multiple tags/branches pointing to same commit share one worktree
  • Parallel Safety: Independent worktrees enable conflict-free concurrent operations

Versioning

CCPM uses Git-based versioning at the repository level with enhanced constraint support:

  • Git tags (recommended): version = "v1.0.0" or version = "^1.0.0"
  • Semver constraints: ^1.0, ~2.1, >=1.0.0, <2.0.0
  • Branches: branch = "main" (mutable, updates on each install)
  • Commits: rev = "abc123def" (immutable, exact commit)
  • Local paths: No versioning, uses current files

See the Versioning Guide for details.

Security

CCPM separates credentials from project configuration:

  • ✅ Project manifest (ccpm.toml) - Safe to commit
  • ❌ Global config (~/.ccpm/config.toml) - Contains secrets, never commit
# Add private source with authentication (global config only)
ccpm config add-source private "https://oauth2:TOKEN@github.com/org/private.git"

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Project Status

CCPM is actively developed with comprehensive test coverage and automated releases:

  • ✅ All core commands implemented
  • ✅ Cross-platform support (Windows, macOS, Linux)
  • ✅ Comprehensive test suite (70%+ coverage)
  • ✅ Specialized Rust development agents (standard/advanced tiers)
  • ✅ Automated semantic releases with conventional commits
  • ✅ Cross-platform binary builds for all releases
  • ✅ Publishing to crates.io (automated via semantic-release)

Automated Releases

CCPM uses semantic-release for automated versioning and publishing:

  • Conventional Commits: Version bumps based on commit messages (feat: → minor, fix: → patch)
  • Cross-Platform Binaries: Automatic builds for Linux, macOS, and Windows
  • Automated Publishing: Releases to both GitHub and crates.io
  • Changelog Generation: Automatic changelog from commit history

License

MIT License - see LICENSE.md for details.

Support

Built with Rust 🦀 for reliability and performance