Warning
This project is under active development. Expect breaking changes, bugs, and incomplete features. Migrations between versions are not guaranteed. Use at your own risk.
brew install bguidolim/tap/managed-claude-stack# this is a real tech pack as example
# more info about tech packs: https://github.com/bguidolim/mcs?tab=readme-ov-file#-whats-in-a-tech-pack
mcs pack add bguidolim/mcs-continuous-learningcd ~/Developer/my-project
mcs syncmcs doctorThat's it. Your MCP servers, plugins, hooks, skills, commands, agents, settings, and templates are all in place.
📋 Prerequisites
- macOS 13+ (Apple Silicon or Intel)
- Xcode Command Line Tools
xcode-select --install
- Claude Code CLI (
claude) - Homebrew
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.
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.
Without mcs |
With mcs |
|---|---|
| Install MCP servers one by one | mcs pack add + mcs sync |
Hand-edit settings.json per project |
Managed settings composition |
| Copy hooks between projects manually | Auto-installed per-project from packs |
| Configuration drifts silently | mcs doctor --fix detects and repairs |
| Rebuild from memory on new machines | Fully reproducible in minutes |
| No way to share your setup | Push a pack, anyone can mcs pack add it |
Packs are modular — mix and match what you need instead of one monolith:
| Pack | Description | Highlights |
|---|---|---|
| mcs-core-pack | Foundational settings, plugins, git workflows, and code navigation | Serena (LSP), plan mode, /commit, PR review agents, session-start git status |
| mcs-continuous-learning | Persistent memory and knowledge management across sessions | Ollama embeddings, semantic search via docs-mcp-server, auto-extracted learnings |
| mcs-ios-pack | Xcode integration, simulator management, and Apple documentation | XcodeBuildMCP, Sosumi docs, auto-detected project config, simulator hooks |
💡 Use these as a starting point — fork one to build your own, or combine all three with
mcs pack addfor a complete setup.
Tech Packs mcs sync Your Project
(Git repos) -----> (engine) -----> (configured)
|
.---------.
| |
v v
Per-Project Global
artifacts artifacts
- Select which packs to apply (interactive multi-select or
--all) - Resolve prompts (auto-detect project files, ask for config values)
- Install artifacts to the right locations (skills, hooks, commands, agents, settings, MCP servers)
- Track everything for convergence — re-running
mcs syncadds 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.
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.
📖 Full guide: Creating Tech Packs · Schema reference: techpack-schema.md
- 🧑💻 Solo Developer — New Mac? One
mcs pack add+mcs syncand 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 — Ship a tech pack with your repo. Contributors run
mcs syncand get the right MCP servers, skills, and conventions automatically. - 🧪 Experimentation — Try a different set of MCP servers, swap packs, roll back.
mcsconverges cleanly — deselected packs are fully removed, no leftovers.
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
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.
| Document | Description |
|---|---|
| 📖 CLI Reference | Complete command reference (sync, pack, doctor, export, cleanup) |
| 📖 Creating Tech Packs | Step-by-step guide to building your first pack |
| 📋 Tech Pack Schema | Complete techpack.yaml field reference |
| 🏗️ Architecture | Internal design, sync flow, safety guarantees, and extension points |
| 🔧 Troubleshooting | Common issues and fixes |
swift build # Build
swift test # Run tests
swift build -c release --arch arm64 --arch x86_64 # Universal binarySee Architecture for project structure and design decisions.
Tech pack ideas and engine improvements are welcome!
- Fork the repo
- Create a feature branch
- Run
swift test - Open a PR
For building new packs, start with Creating Tech Packs.
If mcs saves you time, consider sponsoring the project.
MIT License · Made with ❤️ by Bruno Guidolim