mcs

Your Claude Code environment — packaged, portable, and reproducible.

🚀 Quick Start

1. Install

brew install mcs-cli/tap/mcs

2. Add tech packs

Browse available packs at techpacks.mcs-cli.dev, then add them:

mcs pack add owner/pack-name

3. Sync a project

cd ~/Developer/my-project
mcs sync

4. Verify everything

mcs doctor

That's it. Your MCP servers, plugins, hooks, skills, commands, agents, settings, and templates are all in place.

The Problem

You've spent hours getting Claude Code just right — MCP servers, plugins, hooks, skills, custom commands, fine-tuned settings. Then:

• 🖥️ New machine? Start over from scratch.
• 👥 Onboarding a teammate? "Just follow this 47-step wiki page."
• 📂 Different projects? Copy-paste configs, hope nothing drifts.
• 🔄 Something broke? Good luck figuring out what changed.

The Solution

mcs is a configuration engine for Claude Code — like Ansible for your AI development environment. Package everything into shareable tech packs (Git repos with a techpack.yaml manifest), then sync them across any project, any machine, in seconds.

🔍 Explore Tech Packs

Packs are modular — mix and match what you need instead of one monolith. Browse the full catalog, search by category, and find install commands:

techpacks.mcs-cli.dev

💡 Can't find what you need? Build your own — see Creating Tech Packs.

⚙️ How It Works

 Tech Packs          mcs sync          Your Project
 (Git repos)  -----> (engine)  -----> (configured)
                        |
                   .---------.
                   |         |
                   v         v
              Per-Project  Global
              artifacts    artifacts

1. Select which packs to apply (interactive multi-select or --all)
2. Resolve prompts (auto-detect project files, ask for config values)
3. Install artifacts to the right locations (skills, hooks, commands, agents, settings, MCP servers)
4. Track everything for convergence — re-running mcs sync adds what's missing, removes what's deselected, and updates what changed

Use mcs sync --global for global-scope components (Homebrew packages, plugins, global MCP servers). See Architecture for artifact locations and the full sync flow.

📦 What's in a Tech Pack?

A tech pack is a Git repo with a techpack.yaml manifest. It can bundle MCP servers, plugins, hooks, skills, commands, agents, settings, templates, and doctor checks — anything mcs can install, verify, and uninstall.

Use mcs pack validate to check your pack for structural errors and best practices before sharing.

📖 Full guide: Creating Tech Packs · Schema reference: techpack-schema.md

🎯 Use Cases

• 🧑‍💻 Solo Developer — New Mac? One mcs pack add + mcs sync and your entire Claude Code environment is back. No wiki, no notes, no memory required.
• 👥 Teams — Create a team pack with your org's MCP servers, approved plugins, and coding standards. Every developer gets the same setup with mcs sync --all.
• 🌐 Open Source — Use mcs export to create a tech pack from your repo's config. Contributors run mcs sync and get the right MCP servers, skills, and conventions automatically.
• 🧪 Experimentation — Try a different set of MCP servers, swap packs, roll back. mcs converges cleanly — deselected packs are fully removed, no leftovers.

🛡️ Safety & Trust

mcs is designed to be non-destructive and transparent. Timestamped backups before modifying user content, --dry-run to preview changes, section markers to preserve your edits in CLAUDE.local.md, and SHA-256 trust verification for pack scripts. Lockfiles (mcs.lock.yaml) pin pack versions for reproducible environments.

📖 Full details: Architecture > Safety & Trust

🔍 Verifying Your Setup with Poirot

After mcs sync, want to confirm everything landed correctly? Poirot is a native macOS companion that gives you a visual overview of your Claude Code configuration — MCP servers, settings, sessions, and more — all in one place.

The perfect complement to mcs: configure your environment with mcs, then use Poirot to see exactly what's installed and running.

📚 Documentation

🛠️ Development

swift build                                            # Build
swift test                                             # Run tests
swift build -c release --arch arm64 --arch x86_64      # Universal binary

See Architecture for project structure and design decisions.

🤝 Contributing

Tech pack ideas and engine improvements are welcome!

1. Fork the repo
2. Create a feature branch
3. Run swift test
4. Open a PR

For building new packs, start with Creating Tech Packs.