multiagent-core 4.6.0

Foundation framework with intelligent directory management for multi-agent development

MultiAgent Core

Production-ready multi-agent development framework with intelligent automation

Quick Start

# Install from PyPI
pip install multiagent-core

# Initialize a new project
multiagent init my-project
cd my-project

# Check installation
multiagent status

What does multiagent init create?

In your project directory:

• ✅ .gitignore - Comprehensive gitignore covering all languages and frameworks
• ✅ .mcp.json - Claude Code MCP server configuration
• ✅ .vscode/mcp.json - VS Code Copilot MCP server configuration
• ✅ .git/hooks/pre-push - Secret scanning hook (prevents $2,800 API key leaks!)
• ✅ .git/hooks/post-commit - Workflow guidance and auto-build coordination
• ✅ .github/ISSUE_TEMPLATE/ - Bug, feature, task, hotfix templates (optional)

Globally (in ~/.multiagent/):

• ✅ config/mcp-servers-registry.json - MCP server definitions and metadata
• ✅ logs/init-{project}-{timestamp}.log - Detailed initialization logs
• ✅ profile.json - Your developer profile and preferences
• ✅ templates/ - Framework templates (agents, commands, workflows)

What's NOT created:

• ❌ NO .multiagent/ directory in your project (framework lives globally)
• ❌ NO GitHub workflows (handled by version management system)
• ❌ NO project-level components registry (only global ~/.multiagent.json)

📖 Full checklist: docs/INIT-CHECKLIST.md

What is MultiAgent Core?

A comprehensive framework that transforms any project into a coordinated multi-agent development environment. Provides:

• 🤖 Agent Coordination - Claude, Copilot, Qwen, Gemini, Codex working in parallel via git worktrees
• 🔌 MCP Integration - Model Context Protocol servers with on-demand loading (43-48% more context)
• 📋 Automated Workflows - Slash commands for testing, deployment, PR reviews, and documentation
• 🔧 Smart Project Detection - Auto-detects tech stack and generates optimal configurations
• 🔒 Security First - Built-in secret scanning, compliance checks, and safe deletion protocols
• 📊 Comprehensive Testing - Unified testing strategy with intelligent project detection
• 🚀 Production-Ready AI Infrastructure - Cost tracking, monitoring, caching, reliability patterns, GDPR compliance

📐 Scales from Simple to Complex

The framework works for any project size:

Type	Setup Time	Use Case
Landing Page	10 min	Portfolio, single-page sites
Website	30 min	Marketing sites, blogs
Web App	2-4 hrs	SaaS, dashboards
AI App	6-8 hrs	AI-powered platforms
SaaS	Days	Enterprise systems

Same commands, different depth. Start with a landing page, grow to AI SaaS.

# Landing page
/core:project-setup 001 --type=landing-page
# ✅ Live in 10 minutes

# Later: Upgrade to web app
/core:upgrade-to web-app
# ✅ Adds backend + database, keeps everything else

📖 Details: docs/architecture/04-operations-reference.md#project-type-system

🎯 AI SaaS Production Readiness

For AI-powered applications, the framework provides production-grade infrastructure out of the box:

AI Infrastructure

• Cost Tracking: Monitor AI costs across OpenAI, Anthropic, Gemini
• Model Orchestration: Automatic fallbacks, rate limiting, circuit breakers
• Prompt Management: Versioned prompts with A/B testing
• Token Optimization: Context window management and caching

Observability

• Prometheus + Grafana: Full monitoring stack with AI-specific metrics
• Distributed Tracing: OpenTelemetry/Jaeger integration
• Alert Rules: 30+ production alerts (costs, latency, errors)
• SLI/SLO Tracking: Production readiness validation

Performance

• Multi-Layer Caching: L1 (in-memory) → L2 (Redis) → L3 (DB)
• Rate Limiting: Per-endpoint, per-user, per-IP with token bucket
• Queue Management: Celery/Bull for async processing
• Auto-Scaling: HPA configurations with custom metrics

Reliability

• Circuit Breakers: Prevent cascading failures
• Retry Logic: Exponential backoff with jitter
• Health Checks: Kubernetes-compatible liveness/readiness probes
• Graceful Degradation: Bulkhead patterns and fallback chains

Compliance

• GDPR Tools: Complete API for access, erasure, portability, rectification
• PII Detection: Automatic scanning and anonymization
• Audit Logging: Immutable compliance trail
• Consent Management: Granular consent tracking with withdrawal support

Impact: Reduces time to production from 10-12 weeks to 2-3 weeks for AI SaaS applications.

📖 Full Details: AI_INFRASTRUCTURE_BUILD_SUMMARY.md

Core Commands

multiagent init              # Initialize framework in project
multiagent status            # Show component installation status
multiagent detect            # Detect project tech stack
multiagent doctor            # Health check and diagnostics
multiagent env-init          # Generate smart environment config
multiagent upgrade           # Update all components

# Template Management
multiagent templates list    # List available template variants
multiagent templates swap    # Swap active template (e.g., docker → podman)
multiagent templates add     # Add custom template variant
multiagent templates active  # Show currently active templates

What multiagent init does:

• Installs global framework to ~/.multiagent/
• Sets up MCP server registry in ~/.multiagent/config/ with update protection
• Migrates existing registry from ~/.claude/ (if found)
• Creates project configs (.mcp.json, .vscode/mcp.json)
• Registers project for automatic template updates
• Initializes git repository (optional)
• Sets up GitHub integration (optional)

📖 Full details: docs/architecture/03-system-setup.md#installation--initialization

Slash Commands

Powerful automation via Claude Code slash commands:

🤖 AI Infrastructure

• /ai-infrastructure:init - Initialize AI cost tracking & orchestration
• /ai-infrastructure:cost-report - Generate AI cost analysis
• /ai-infrastructure:model-health - Check AI provider health

📊 Observability

• /observability:start - Deploy monitoring stack (Prometheus, Grafana, Jaeger)
• /observability:mid - Monitor metrics collection
• /observability:end - Validate production readiness

⚡ Performance

• /performance:init - Initialize caching, rate limiting, queues
• /performance:analyze - Analyze bottlenecks (N+1, slow queries)
• /performance:cache-strategy - Design multi-layer caching

🛡️ Reliability

• /reliability:init - Initialize circuit breakers & resilience
• /reliability:analyze - Identify single points of failure
• /reliability:circuit-breaker - Add circuit breakers to services

🔒 Compliance

• /compliance:init - Initialize PII detection & audit logging
• /compliance:scan-pii - Scan for exposed PII
• /compliance:gdpr-tools - Implement GDPR tools (DSAR, deletion, portability)

🧪 Testing

• /testing:test - Unified testing with intelligent routing
• /testing:test-generate - Generate test structure from tasks
• /testing:test-prod - Production readiness validation

🚀 Deployment

• /deployment:deploy-prepare - Orchestrate deployment prep
• /deployment:deploy-validate - Validate deployment config
• /deployment:deploy-run - Execute local deployment
• /deployment:deploy - Deploy to cloud platforms
• /deployment:prod-ready - Comprehensive production scan

🔄 Iteration

• /iterate:tasks - Apply task layering for parallel work
• /iterate:sync - Sync entire spec ecosystem
• /iterate:adjust - Live development adjustments

👁️ Supervision

• /supervisor:start - Pre-work agent verification
• /supervisor:mid - Progress monitoring
• /supervisor:end - Pre-PR completion checks

🔀 Git Automation

• /git:worktree-create - Create isolated worktree for parallel development
• /git:worktree-cleanup - Remove worktree and cleanup branches
• /git:commit-smart - Generate standardized commit messages
• /git:branch-cleanup - Cleanup merged and stale branches

📝 Documentation

• /docs:init, /docs:update, /docs:validate

🐙 GitHub Integration

• /github:create-issue - Create issues with templates
• /github:pr-review - Analyze PR feedback
• /github:discussions - Manage discussions

📓 Development Notes

• /note - Quick capture observations, bugs, TODOs, questions
• /note:list - List and filter notes by type, priority, file
• /note:close - Close/resolve notes with reason
• /note:import - Import GitHub Issues as local notes (future)

🔌 MCP Server Management

• /mcp:setup - Interactive wizard for API key configuration
• /mcp:list - Show all available MCP servers
• /mcp:add <server> - Add server to current project
• /mcp:remove <server> - Remove server from project
• /mcp:status - Show project's MCP configuration
• /mcp:clear - Remove all servers (maximize context)

🔧 Framework Build System

MultiAgent Core IS the framework for building Claude Code components.

• /framework-agent - Build new agents from templates
• /framework-slash-command - Build new slash commands
• /framework-skill - Build new skills
• /framework-plugin - Build new plugins

All templates and build tools are in .claude/ within this repository.

MCP Integration

Model Context Protocol (MCP) servers extend Claude Code with custom tools and integrations.

MultiAgent Core uses a two-tier MCP system to maximize context window:

1. Global Registry (~/.claude/mcp-servers-registry.json) - Available servers catalog
2. Per-Project Config (.mcp.json, .vscode/mcp.json) - Load only what's needed

Quick Start

# One-time setup: Add API keys to shell config
/mcp:config edit

# View available servers
/mcp:list

# Add servers to your project
/mcp:add github memory

# Check project status
/mcp:status

Available MCP Servers

Standard Servers:

• github - GitHub API integration
• postman - API testing & collections
• memory - Persistent conversation memory
• playwright - Browser automation
• filesystem - File/directory operations
• supabase - Supabase backend operations

Custom Servers (with local/remote variants):

• signalhire - Talent search API
• airtable - Database operations
• twilio - SMS/voice communications
• calendly - Appointment scheduling

Context Window Optimization

Problem: Auto-loading all MCP servers = ~96,000 tokens wasted Solution: Load servers on-demand = 43-48% more context available

# ❌ Bad: Global auto-load (wastes tokens everywhere)
~/.claude/settings.json with all servers

# ✅ Good: Per-project as needed
cd project-a && /mcp:add github memory
cd project-b && /mcp:add postman
cd project-c                              # No servers = max context

API Key Management

API keys are stored in ~/.bashrc (single source of truth) and hardcoded into project configs:

# View configured keys
/mcp:check

# Add/update keys
/mcp:config edit
# Or manually: nano ~/.bashrc
# Add: export POSTMAN_API_KEY="your-key"
source ~/.bashrc

Security:

• Keys stored in ~/.bashrc (not committed to git)
• Project configs (.mcp.json, .vscode/mcp.json) are gitignored
• /mcp:add reads from environment and hardcodes values (no ${VAR} placeholders)

Adding Custom Servers to Registry

Use the /mcp:registry command to add custom servers:

# Add a new server to the registry
/mcp:registry add your-server local npx

# Follow prompts for:
# - Package name: @your-org/your-mcp-server
# - Environment variables: YOUR_API_KEY
# - Description: Your server description

Then add API keys and use your server:

# Add API key
/mcp:config edit
# Add: export YOUR_API_KEY="your-key"
source ~/.bashrc

# Add to project
/mcp:add your-server

Or manually edit ~/.claude/mcp-servers-registry.json (see complete guide for format)

📚 Documentation:

• Quick Start: docs/MCP_QUICK_START.md
• Complete Guide: ~/.claude/MCP_COMPLETE_GUIDE.md (run /docs mcp to load)

Project Structure

After multiagent init:

your-project/
├── .multiagent/              # Core automation system
│   ├── agents/              # Agent coordination infrastructure
│   ├── ai-infrastructure/   # AI cost tracking & orchestration
│   ├── backend/             # Backend development guidance
│   ├── compliance/          # GDPR, CCPA, HIPAA compliance tools
│   ├── core/                # Agent workflows & templates
│   ├── deployment/          # Deployment automation
│   ├── documentation/       # Documentation generation
│   ├── experiment/          # Safe experimentation workflows
│   ├── frontend/            # Frontend development guidance
│   ├── github/              # GitHub integration & PR review
│   ├── iterate/             # Task layering & spec sync
│   ├── mcp/                 # MCP server management
│   ├── observability/       # Monitoring & metrics
│   ├── performance/         # Performance optimization
│   ├── reliability/         # Circuit breakers & resilience
│   ├── security/            # Security scanning & compliance
│   ├── supervisor/          # Agent monitoring
│   ├── testing/             # Test generation & execution
│   └── version-management/  # Semantic versioning
├── .claude/                  # Claude Code configuration
│   ├── agents/              # Framework builder agents (5 agents)
│   ├── commands/            # Framework slash commands (4 commands)
│   ├── skills/              # Build assistant skill with templates
│   │   └── build-assistant/ # Complete build system
│   │       ├── templates/   # Agent, command, skill, plugin templates
│   │       └── scripts/     # Validation scripts
│   └── hooks/               # Git hooks & automation
├── .github/workflows/        # CI/CD automation
└── specs/                   # Feature specifications & tasks

Framework Build System

MultiAgent Core is the framework for building Claude Code components. All build tools, templates, and agents live inside this repository in .claude/:

What You Can Build

1. Agents - Specialized AI agents with specific capabilities
2. Slash Commands - Custom automation commands
3. Skills - Reusable skill modules with prompts
4. Plugins - Complete plugin bundles with agents, commands, and skills

Build Commands

# Build a new agent
/framework-agent my-agent "AI agent for testing APIs" "Read, Write, Bash"

# Build a new slash command
/framework-slash-command testing api-test "Run API tests with validation"

# Build a new skill
/framework-skill my-skill "Skill for code analysis"

# Build a complete plugin
/framework-plugin my-plugin "Plugin for project automation"

Templates Location

All templates are in .claude/skills/build-assistant/templates/:

• agents/agent.md.template - Agent template with examples
• commands/command.md.template - Slash command template
• skills/SKILL.md.template - Skill template
• plugins/plugin.json.template - Plugin manifest template

Framework Documentation

Framework guides are in docs/framework/:

• 01-claude-code-slash-commands.md - Slash command guide
• 02-claude-code-skills.md - Skills guide
• 03-claude-code-plugins.md - Plugins guide
• 04-skills-vs-commands.md - When to use each

📖 Complete guide: See .claude/README.md

Architecture

multiagent_core/
├── cli.py              # Main CLI with 15+ commands
├── detector.py         # Tech stack detection
├── analyzer.py         # Environment analysis
├── env_generator.py    # Smart .env generation
├── auto_updater.py     # Auto-update system
├── config.py           # Configuration management
└── templates/          # Deployment templates

.claude/                # Framework build system
├── agents/             # 5 builder agents
├── commands/           # 4 framework commands
└── skills/             # Build assistant with templates

Development Workflow

For Contributors:

1. Install in editable mode:

   pip install -e . --force
   

2. Edit source templates in root directories (.multiagent/, .claude/)

   • Build system auto-syncs to multiagent_core/templates/

3. Test changes:

   cd /tmp && multiagent init test-project
   

4. Build & test distribution:

   python -m build
   pip install dist/multiagent_core-*.whl --force
   

Automation Systems

Each subsystem is self-contained with its own README:

System	Path	Purpose
Agents	.multiagent/agents/	Agent coordination infrastructure & git workflows
AI Infrastructure	.multiagent/ai-infrastructure/	AI cost tracking, model orchestration, prompt management
Backend	.multiagent/backend/	Backend development guidance & API patterns
Compliance	.multiagent/compliance/	GDPR, CCPA, HIPAA compliance tools & PII detection
Core	.multiagent/core/	Agent workflows, templates, coordination
CTO	.multiagent/cto/	CTO-level reviews & architectural oversight
Deployment	.multiagent/deployment/	Multi-platform deployment automation
Documentation	.multiagent/documentation/	Documentation generation & validation
Enhancement	.multiagent/enhancement/	Enhancement proposal lifecycle & tracking
Frontend	.multiagent/frontend/	Frontend development guidance & UI patterns
Git	.multiagent/git/	Git automation & worktree management
GitHub	.multiagent/github/	GitHub integration & PR review automation
Idea	.multiagent/idea/	Lightweight brainstorming & idea capture
Implementation	.multiagent/implementation/	Implementation tracking & validation
Iterate	.multiagent/iterate/	Spec synchronization & task layering
MCP	.multiagent/mcp/	MCP server registry & management
Notes	.multiagent/notes/	Local development notes tracking (bugs, TODOs, observations, questions)
Observability	.multiagent/observability/	Monitoring, metrics, alerting (Prometheus, Grafana, ELK)
Performance	.multiagent/performance/	Performance optimization, caching, rate limiting
Refactoring	.multiagent/refactoring/	Code quality improvement, duplicate extraction, pattern modernization
Reliability	.multiagent/reliability/	Circuit breakers, graceful degradation, health checks
Security	.multiagent/security/	Secret scanning, compliance, auditing
Supervisor	.multiagent/supervisor/	Agent monitoring & compliance
Testing	.multiagent/testing/	Intelligent test generation & execution
Version Management	.multiagent/version-management/	Semantic versioning automation

Release & Versioning

• Semantic Versioning via conventional commits
• Automated Releases on push to main
• PyPI Publishing via GitHub Actions
• Version Management - .github/workflows/version-management.yml

Commit format:

feat: Add new command
fix: Resolve deployment issue
docs: Update README
chore: Bump dependencies

Testing

# Run full test suite
python -m pytest

# GitHub Actions tests:
# - Ubuntu, Windows, macOS
# - Python 3.8-3.12
# - pip, pipx, source installs

Documentation

User Documentation

• User Guide: .multiagent/README.md - Complete framework guide (deployed to projects)
• AI Infrastructure Summary: AI_INFRASTRUCTURE_BUILD_SUMMARY.md - 5 production-ready subsystems

Architecture & Standards

• Architecture Overview: docs/architecture/01-architecture-overview.md - Three-tier system architecture, layered orchestration
• Development Guide: docs/architecture/02-development-guide.md - Build standards, dependencies & build order
• Operations Reference: docs/architecture/04-operations-reference.md#subsystem-lifecycle - Subsystem lifecycle including safe deletion

Workflows & Guides

• Build Workflow: docs/workflows/BUILD_WORKFLOW.md - Step-by-step guide for building subsystems
• Template Management: docs/TEMPLATE_MANAGEMENT.md - Template system guide
• Development Guide: DEVELOPMENT.md - Contributor setup

Reports & Analysis

• Build Analysis Reports: docs/reports/build-analysis/ - Subsystem compliance reports
• Report Generation Guide: docs/reports/REPORT_GENERATION_GUIDE.md - All report types documented

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with conventional commits
4. Test with python -m pytest
5. Submit PR with detailed description

License

MIT License - see LICENSE file

---

Install now: pip install multiagent-core

Documentation: .multiagent/README.md

Auto-sync test