🪄 MAGE-X

Write Once, Mage Everywhere: Zero-Boilerplate Build Tooling for Go.

`CI / CD`		`Quality`
`Security`		`Community`

`Project Navigation`

🧩 `What's Inside`	⚡ `Quick Start`	🚀 `Features`	⚙️ `Configuration`
📚 `Documentation`	📐 `SDD`	🧪 `Examples & Tests`	⚡ `Benchmarks`
🛠️ `Code Standards`	🤖 `AI Usage`	🤝 `Contributing`	📝 `License`

🧩 What's Inside

MAGE-X revolutionizes Go build tooling with TRUE zero-boilerplate. Unlike traditional Mage which requires writing wrapper functions, MAGE-X provides all commands instantly through the magex binary.

Truly Zero-Configuration
No magefile.go needed. No imports. No wrappers. Just install magex and all built-in and custom commands work immediately in any Go project.
Drop-in Mage Replacement
magex is a superset of mage with all MAGE-X commands built-in. Your existing magefiles still work, now enhanced with 190+ professional commands.
Cross-Platform Excellence
Full support for Linux, macOS, and Windows with multi-architecture builds, parallel execution, and CPU-aware optimization.
Security-First Architecture
Input validation, secure command execution, and minimal dependencies. Built for environments where security matters.
Graceful Ctrl+C Cancellation
A single Ctrl+C cleanly stops any command — in-flight subprocesses receive SIGINT with a 5s grace window, loops bail on the next iteration, and magex exits with code 130. A second Ctrl+C force-exits as an escape hatch. SIGTERM is honored too (exit 143) so CI runners can cancel jobs cleanly without orphan processes.
Professional Release Tooling
Standardized versioning commands, GitHub integration, GoDocs proxy sync, and release tooling for production deployments.
Smart Documentation System
Hybrid pkgsite/godoc support with auto-detection, port management, and cross-platform browser integration.

🎥 Demo

⚡ Quick Start

Which Path Should I Take?

MAGE-X automatically detects your project structure and just works:

Your Project Structure	What MAGE-X Does
Single Binary `main.go` in root	Builds to `bin/projectname`
Multi-Binary `cmd/*/main.go`	Auto-detects & builds first found
Library No main package	Verifies compilation with `./...`

📖 See the Complete Quick Start Guide for project-specific examples and troubleshooting.

Zero Boilerplate Installation

# Install magex (production branch)
go install github.com/mrz1836/mage-x/cmd/magex@latest

# Auto-update to latest stable release (with proper version info)
magex update:install

# MAGE-X automatically checks for updates in the background
# and notifies you when new versions are available

# Now use it in ANY Go project (no setup!)
# Use either 'magex' or its shorter alias 'mgx'
magex build         # Automatically detects & builds your project
magex test          # Run your tests
magex bench         # Run your benchmarks
magex lint:fix      # Fix any linting issues
magex format:fix    # Format your code

# That's it! No magefile.go needed! 🚀

Quick Project Check

# See what MAGE-X detects in your project:
magex build --dry-run  # Shows what will be built without building

# or use the shorter alias:
mgx build --dry-run    # Same command, shorter to type

Full Command List

magex help          # List all commands & get help
magex -n            # Commands by namespace
magex -search test  # Find specific commands
# Remember: you can use 'magex' or 'mgx' interchangeably

Optional: Add Custom Commands

Only create a magefile.go if you need project-specific commands:

//go:build mage
package main

// Your custom command (works alongside all MAGE-X commands!)
func Deploy() error {
    // Custom deployment logic
    return nil
}

Now you have both:

magex build    # Built-in MAGE-X command
magex deploy   # Your custom command

Hybrid Execution Model

MAGE-X uses a smart hybrid approach that provides the best of both worlds:

Built-in commands execute directly for speed and consistency (magex build, magex test, etc.)
Custom commands in your magefile.go are automatically discovered and delegated to mage
Unified interface - one standardized CLI for all tools

This means:

magex build (or mgx build) always behaves consistently across all projects
Your custom commands work seamlessly without any setup
No plugin compilation or platform-specific issues
Zero configuration required

🚀 Features

Core Excellence

Command Execution: Secure, interface-based command execution with validation
Native Logging: Colored output, progress indicators, and structured logging
Complete Build Toolchain: All essential build, test, lint, and release tasks
Version Management: Automatic version detection and update infrastructure with sub-module support for multi-module repositories

Developer Experience

Release Tooling: Multi-platform asset building with GitHub integration
Configuration Management: Flexible mage.yaml with smart defaults
Command Discovery: Comprehensive CLI with intuitive command structure
Help System: Built-in documentation and usage examples
Graceful Cancellation: Ctrl+C stops every command cleanly (exit 130); second press force-exits; CI-friendly SIGTERM handling (exit 143)

Production Features

Security Scanning: Vulnerability detection with govulncheck integration
Configuration Management: Centralized project configuration and validation
Extensible Architecture: Plugin-ready foundation for custom production needs

⚙️ Configuration

MAGE-X works without any configuration, but you can customize behavior with .mage.yaml or environment variables.

📋 Configuration File (.mage.yaml)

Create .mage.yaml in your project root for custom settings:

project:
  name: my-project
  binary: myapp
  version: v1.0.0
  module: github.com/user/my-project

build:
  output: bin
  trimpath: true
  platforms:
    - linux/amd64
    - darwin/amd64
    - darwin/arm64
    - windows/amd64
  tags:
    - prod
  ldflags:
    - -s -w
    - -X main.version={{.Version}}
    - -X main.commit={{.Commit}}

test:
  parallel: true
  timeout: 10m
  race: false
  cover: true
  covermode: atomic

lint:
  golangci_version: v2.3.1
  timeout: 5m

tools:
  golangci_lint: v2.3.1
  fumpt: latest
  govulncheck: latest

release:
  github:
    owner: mrz
    repo: my-project
  platforms:
    - linux/amd64
    - darwin/amd64
    - darwin/arm64
    - windows/amd64

🌍 Environment Variable Overrides

Override any configuration with environment variables:

# Build configuration
export MAGE_X_BINARY_NAME=myapp
export MAGE_X_BUILD_TAGS=prod,feature1
export GOOS=linux
export GOARCH=amd64

# Test configuration
export MAGE_X_VERBOSE=true
export MAGE_X_TEST_RACE=true
export MAGE_X_TEST_TIMEOUT=15m

# Linting configuration
export MAGE_X_LINT_VERBOSE=true   # Enable verbose linting output
export MAGE_X_LINT_TIMEOUT=10m

# Tool configuration
export MAGE_X_PARALLEL=8

# Benchmark timing with parameters
magex bench time=50ms         # Quick benchmarks
magex bench time=10s          # Full benchmarks
magex bench:cpu time=30s      # CPU profiling
magex bench:save time=5s output=results.txt
magex bench time=2s count=5   # With custom count parameter

# Version management examples with new parameter format
magex version:bump bump=patch              # Bump patch version
magex version:bump bump=minor push         # Bump minor and push
magex version:bump bump=patch branch=master push  # Switch to master, bump, and push
magex git:tag version=1.2.3                # Create git tag
magex git:commit message="fix: bug fix"    # Commit with message

📚 Documentation

For comprehensive documentation, visit the docs directory:

Getting Started - Complete documentation index
Namespace Interface Architecture - Modern interface-based namespace system
API Reference - Complete interface and API documentation
Quick Start - Get up and running in minutes
Configuration Reference - Complete configuration guide

Available Commands

MAGE-X provides 190+ commands organized by functionality. All commands work instantly through the magex CLI.

🎯 Essential Commands

Quick Discovery:

magex help:default       # Beautiful command listing with categories and emojis
magex -l                 # Plain list of all available targets
magex -search test       # Find specific commands

Most Used Commands:

magex                    # Run default build
magex build              # Build for current platform
magex test               # Run complete test suite
magex bench              # Run benchmarks
magex lint:fix           # Auto-fix linting issues
magex format:fix		 # Format code automatically
magex version:bump 	     # Bump version (patch, minor, major)

🏗️ Code Generation

magex generate:default    # Run go generate
magex generate:clean      # Remove generated files

📦 Dependencies & Modules

# Dependency Management
magex deps:update         # Update dependencies (safe - no major version bumps)
magex deps:update allow-major  # Update including major versions (v1→v2, etc)
magex deps:tidy           # Clean up go.mod and go.sum
magex deps:download       # Download all dependencies
magex deps:outdated       # Show outdated dependencies
magex deps:audit          # Audit dependencies for vulnerabilities
magex deps:audit exclude=CVE-2024-38513,CVE-2023-45142  # Exclude specific CVEs from audit

# Multi-Module Update (for monorepos with multiple go.mod files)
magex deps:update all-modules                    # Update all modules in workspace
magex deps:update all-modules dry-run            # Preview modules without updating
magex deps:update all-modules fail-fast          # Stop on first module error
magex deps:update all-modules verbose            # Show detailed update info
magex deps:update all-modules allow-major stable-only verbose fail-fast  # All options

# Module Management
magex mod:update          # Update go.mod file
magex mod:tidy            # Tidy the go.mod file
magex mod:verify          # Verify module checksums
magex mod:download        # Download modules
magex mod:graph           # Visualize dependency graph as tree with relationships
magex mod:why             # Show why specific modules are needed

# Dependency Graph Examples
magex mod:graph                                  # Default tree view with versions
magex mod:graph depth=3                          # Limit depth to 3 levels
magex mod:graph show_versions=false              # Hide version numbers
magex mod:graph format=json                      # JSON output format
magex mod:graph format=dot                       # DOT format for graphviz
magex mod:graph format=mermaid                   # Mermaid diagram format
magex mod:graph filter=github.com depth=2        # Filter + depth combined
magex mod:graph show_versions=false format=tree  # Clean tree view

# Module Dependency Analysis Examples
magex mod:why github.com/stretchr/testify        # Show why testify is needed
magex mod:why github.com/pkg/errors golang.org/x/sync  # Analyze multiple modules

📦 Build & Compilation

magex build:default       # Build for current platform
magex build:all           # Build for all configured platforms
magex build:clean         # Clean build artifacts
magex build:generate      # Generate code before building
magex build:linux         # Build for Linux amd64
magex build:darwin        # Build for macOS (amd64 and arm64)
magex build:windows       # Build for Windows amd64
magex build:install       # Install binary to $GOPATH/bin
magex build:dev           # Build and install development version (forced 'dev' version)
magex build:prebuild      # Pre-build all packages to warm cache
magex build:prebuild parallel=2  # Pre-build with 2 parallel processes
magex build:prebuild p=4         # Pre-build with 4 parallel processes (short form)

# Memory-efficient prebuild strategies (great for CI/CD environments)
magex build:prebuild strategy=incremental batch=10  # Build in batches of 10 packages
magex build:prebuild strategy=mains-first           # Build main packages first, then dependencies
magex build:prebuild strategy=smart                 # Auto-select best strategy based on available memory
magex build:prebuild strategy=full p=8              # Traditional full build with 8 parallel jobs

# Advanced prebuild options
magex build:prebuild strategy=incremental batch=5 delay=100   # 100ms delay between batches
magex build:prebuild strategy=mains-first mains-only=true     # Only build main packages
magex build:prebuild exclude=test verbose=true                # Exclude test packages, verbose output

🧪 Testing & Quality

magex test                     # Run complete test suite with linting
magex test:unit                # Run unit tests only
magex test:short               # Run short tests (excludes integration tests)
magex test:race                # Run tests with race detector
magex test:cover               # Run tests with coverage analysis
magex test:coverrace           # Run tests with both coverage and race detector
magex test:bench               # Run benchmark tests
magex bench                    # Run benchmarks with default timing
magex bench time=50ms          # Run quick benchmarks (50ms duration)
magex bench time=10s count=3   # Run benchmarks with custom time and count
magex test:fuzz                # Run fuzz tests (default: 10s)
magex test:fuzz time=30s       # Run fuzz tests with custom duration
magex test:fuzzShort time=1s   # Run short fuzz tests with custom duration
magex test:integration         # Run integration tests

# JSON Output Support for Test Commands
magex test -json               # Run tests with JSON output for tooling
magex test:unit -json          # Unit tests with JSON output
magex test:race -json          # Race detection with JSON output
magex test:cover -json         # Coverage tests with JSON output
magex test:coverrace -json     # Coverage + race with JSON output
magex test:short -json         # Short tests with JSON output

# Advanced Test Options (all commands support these flags)
magex test -v                  # Verbose output
magex test:cover -count=3      # Run tests 3 times
magex test -failfast           # Stop at first failure
magex test -shuffle=on         # Randomize test execution
magex test -parallel=4         # Set parallel test execution

# Code Quality & Linting
magex format:fix               # Run code formatting
magex lint                     # Run essential linters
magex lint verbose=true        # Run linters with verbose output
magex lint:fix                 # Auto-fix linting issues + apply formatting
magex lint:issues              # Scan for TODOs, FIXMEs, nolint directives, and test skips
magex lint:verbose             # Alternative: dedicated verbose linting command
magex lint:version 		       # Show golangci-lint version
magex test:vet                 # Run go vet static analysis
magex tools:verify             # Show tool version information

🤖 CI Test Output Mode

MAGE-X automatically detects CI environments and produces structured test output with precise file:line locations for failures. This eliminates complex bash/jq parsing in CI workflows.

Automatic Detection (Zero Configuration):

# In GitHub Actions (or any CI with CI=true) - works automatically!
magex test:unit    # Produces GitHub annotations + JSONL output

# Locally - unchanged behavior
magex test:unit    # Standard terminal output

Explicit CI Mode:

magex test:unit ci          # Force CI mode locally (preview CI output)
magex test:unit ci=false    # Disable CI mode in CI environment

All test commands support CI mode:

magex test:unit ci
magex test:race ci
magex test:cover ci
magex test:fuzz ci

Output in CI:

GitHub Annotations: Clickable file:line links in PR sidebar
Step Summary: Markdown table in $GITHUB_STEP_SUMMARY
Structured Output: .mage-x/ci-results.jsonl for automation

Configuration (optional in .mage.yaml):

test:
  ci_mode:
    enabled: auto          # auto (default), on, or off
    format: github         # auto, github, or json
    context_lines: 20      # Lines of code context around failures
    output_path: ".mage-x/ci-results.jsonl"

Environment Variables:

export MAGE_X_CI_MODE=auto      # auto/on/off
export MAGE_X_CI_FORMAT=github  # github/json/auto
export MAGE_X_CI_CONTEXT=20     # Context lines (0-100)

✅ Code Validation & Formatting

# Code Validation
magex vet:default         # Run go vet
magex vet:all             # Run go vet with all checks
magex vet:parallel        # Run go vet in parallel
magex vet:shadow          # Check for variable shadowing
magex vet:strict          # Run strict vet checks

# Code Formatting
magex format:default      # Default formatting (gofmt)
magex format:all          # Format all supported file types
magex format:gofmt        # Run gofmt
magex format:fumpt        # Run gofumpt (stricter formatting)
magex format:imports      # Format imports
magex format:go           # Format Go files
magex format:yaml         # Format YAML files
magex format:json         # Format JSON files
magex format:fix          # Fix formatting issues automatically
magex format:check        # Check if files are properly formatted

📊 Analysis & Metrics

# Lines of Code Analysis (Multi-language support)
magex metrics:loc              # Analyze Go lines of code (default)
magex metrics:loc lang=go      # Explicitly analyze Go files
magex metrics:loc lang=js      # Analyze JavaScript/TypeScript files (.js, .ts, .jsx, .tsx)
magex metrics:loc lang=yaml    # Analyze YAML files (.yaml, .yml)
magex metrics:loc lang=js json # JS metrics with JSON output

# Other Metrics
magex metrics:mage        # Analyze magefiles and targets
magex metrics:coverage    # Generate coverage reports
magex metrics:complexity  # Analyze code complexity

# Performance & Benchmarking
magex bench               # Default benchmark operations
magex bench time=50ms     # Quick benchmarks (50ms runs)
magex bench time=10s      # Comprehensive benchmarks (10s runs)
magex bench count=3       # Run benchmarks 3 times
magex bench:profile       # Profile application performance
magex bench:compare       # Compare benchmark results
magex bench:regression    # Check for performance regressions
magex bench:cpu time=30s  # CPU usage benchmarks with custom duration
magex bench:mem time=2s   # Memory usage benchmarks

📚 Documentation

magex docs               # Generate and serve documentation (generate + serve in one command)
magex docs:generate      # Generate Go package documentation from source code
magex docs:serve         # Serve documentation locally with hybrid pkgsite/godoc support
magex docs:build         # Build enhanced static documentation files with metadata
magex docs:check         # Validate documentation completeness and quality
magex docs:update        # Update GoDocs proxy (trigger pkg.go.dev sync)
magex docs:godocs        # Update GoDocs proxy (alias for docs:update)

🔀 Git & Version Control

# Git Operations
magex git:status                                # Show git repository status
magex git:commit message="fix: commit message"  # Commit changes with message parameter
magex git:tag version=1.2.3                     # Create and push a new tag with version parameter
magex git:tagremove version=1.2.3               # Remove a tag
magex git:tagupdate version=1.2.3               # Force update a tag

# Version Management
magex version:show         # Display current version information
magex version:modules      # List all discovered sub-modules (for multi-module repos)
magex version:check        # Check version information and compare with latest
magex version:update       # Update to latest version
magex version:bump         # Bump version (patch, minor, major)
magex version:changelog    # Generate changelog from git history
magex version:tag          # Create version tag
magex version:compare      # Compare two versions
magex version:validate     # Validate version format

# Version Bump Examples (now using parameters)
magex version:bump                          # Bump patch version (default)
magex version:bump bump=minor               # Bump minor version
magex version:bump bump=major major-confirm # Bump major version with confirmation
magex version:bump bump=minor push          # Bump minor and push to remote

# Branch Parameter Examples (recommended for virtual branch workflows)
magex version:bump bump=patch branch=master push    # Switch to master, bump patch, and push
magex version:bump bump=minor branch=main           # Switch to main branch before bumping
magex version:bump bump=major branch=master major-confirm push  # Major bump on master with push

# Dry-run mode (preview changes without making them)
magex version:bump dry-run                 # Preview patch bump
magex version:bump bump=minor dry-run      # Preview minor bump
magex version:bump bump=major major-confirm push dry-run  # Preview major bump with push
magex version:bump bump=patch branch=master dry-run      # Preview branch switch and bump

# Sub-module Versioning (for multi-module repositories like spv-wallet)
magex version:modules                           # List all discovered sub-modules
magex version:bump module=models bump=patch     # Bump specific sub-module
magex version:bump module=all bump=minor        # Bump all sub-modules together
magex version:bump module=* bump=patch push     # Bump root + all sub-modules
magex version:bump module=models dry-run        # Preview sub-module bump

# Important Notes:
# - Uncommitted changes will block version bump operation (safety check)
# - When using branch parameter, you will ALWAYS return to your original branch after completion
# - Branch switch-back happens even if tag creation or push fails (guaranteed cleanup)
# - If network issues occur during pull, operation stops but still switches back to original branch

🚀 Release Management

# Core Release Operations
magex release              # Create a new release from the latest tag
magex release godocs       # Create a release and update GoDocs proxy
magex release:default      # Create a new release from the latest tag
magex release:test         # Dry-run release without publishing
magex release:snapshot     # Build release artifacts without git tag
magex release:localinstall # Build from latest tag and install locally

# Release Setup & Validation
magex release:init         # Initialize .goreleaser.yml configuration
magex release:check        # Validate .goreleaser.yml configuration
magex release:validate     # Comprehensive release readiness validation
magex release:changelog    # Generate changelog from git history
magex release:clean        # Clean release artifacts and build cache

☁️ AWS Credential Management

Manage AWS credentials with MFA authentication. Requires AWS CLI to be installed.

# Smart login - detects if setup is needed, then performs MFA refresh
magex aws:login                    # Login with default profile
magex aws:login profile=production # Login with specific profile

# Interactive setup - configure credentials and MFA device
magex aws:setup                    # Setup default profile
magex aws:setup profile=staging    # Setup specific profile

# MFA refresh - get temporary session credentials
magex aws:refresh                  # Refresh default profile
magex aws:refresh profile=prod     # Refresh specific profile
magex aws:refresh duration=28800   # Custom session duration (8 hours)

# Status - view credential status
magex aws:status                   # Show all profiles
magex aws:status profile=dev       # Show specific profile

Prerequisites:

AWS CLI must be installed and accessible in your PATH
- macOS: brew install awscli
- Linux (Ubuntu/Debian): sudo apt-get install awscli
- Linux (RHEL/CentOS): sudo yum install aws-cli
- Windows: Download MSI installer
- Official guide: AWS CLI Installation
IAM user with MFA device configured

Workflow:

Run magex aws:setup to configure your Access Key, Secret Key, and MFA device ARN
Run magex aws:login daily to refresh your session credentials with MFA

🔧 Development Tools

magex tools:update        # Update all development tools
magex tools:install       # Install all required development tools
magex tools:verify        # Check if all required tools are available
magex deps:audit          # Run vulnerability check using govulncheck
magex build:install       # Install the project binary
magex build:dev           # Build and install development version (forced 'dev' version)
magex install:stdlib      # Install Go standard library for cross-compilation
magex uninstall           # Remove installed binary

# Spec-Kit CLI Management
magex speckit:install     # Install spec-kit prerequisites (uv, uvx, specify-cli)
magex speckit:check       # Verify spec-kit installation and report version info
magex speckit:upgrade     # Upgrade spec-kit with automatic constitution backup/restore

# BMAD CLI Management
magex bmad:install        # Install BMAD prerequisites (npm, npx, bmad-method)
magex bmad:check          # Verify BMAD installation and report version info
magex bmad:upgrade        # Upgrade BMAD to the latest beta version

# Agent OS CLI Management
magex agentos:install     # Install Agent OS (base + project)
magex agentos:check       # Verify Agent OS installation and report version info
magex agentos:upgrade     # Upgrade Agent OS with user data preservation

💻 Tmux Session Management

# Claude Code Pairing Sessions
magex tmux:start                              # Start Claude Code in current directory
magex tmux:start dir=~/projects/foo           # Start in specific directory
magex tmux:start model=opus                   # Start with specific model (opus/sonnet/haiku)
magex tmux:start dir=~/projects/foo name=my-session model=opus  # All options

# Session Management
magex tmux:list                      # List all active tmux sessions
magex tmux:attach name=my-session    # Attach to existing session
magex tmux:kill name=my-session      # Kill specific session
magex tmux:killall                   # Kill all sessions (with confirmation)
magex tmux:status                    # Show session health and status

# Supported Models
# - opus: claude-opus-4-5
# - sonnet: claude-sonnet-4-5 (default)
# - haiku: claude-haiku-4-5
# - gpt: gpt-4o
# - o1: o1
# - o3: o3-mini
# - gemini: gemini-3-flash

# Session auto-attach: If a session already exists, tmux:start will attach to it

⚙️ Configuration Management

magex configure:init      # Initialize a new mage configuration
magex configure:show      # Display the current configuration
magex configure:update    # Update configuration values interactively
magex configure:export    # Export configuration to file
magex configure:import    # Import configuration from file
magex configure:validate  # Validate configuration integrity
magex configure:schema    # Show configuration schema

# YAML Configuration
magex yaml:init           # Create mage.yaml configuration
magex yaml:validate       # Validate YAML configuration
magex yaml:show           # Show current YAML configuration
magex yaml:template       # Generate YAML templates
magex yaml:format         # Format YAML files
magex yaml:check          # Check YAML syntax
magex yaml:merge          # Merge YAML configurations
magex yaml:convert        # Convert between YAML formats
magex yaml:schema         # Show YAML schema

📖 Help & Updates

# Help System
magex help:default        # Show general help
magex help:commands       # List all available commands
magex help:examples       # Show usage examples
magex help:gettingstarted # Getting started guide
magex help:completions    # Generate shell completions

# Update Management
magex update:check        # Check for updates
magex update:install      # Install the latest update

# Installation Management
magex install:default     # Default installation
magex install:local       # Install locally
magex install:binary      # Install project binary
magex install:tools       # Install development tools
magex install:go          # Install Go
magex install:stdlib      # Install Go standard library
magex install:systemwide  # Install system-wide
magex install:deps        # Install dependencies
magex install:mage        # Install mage
magex install:githooks    # Install git hooks
magex install:ci          # Install CI components
magex install:certs       # Install certificates
magex install:package     # Install package
magex install:all         # Install everything
magex uninstall           # Remove installation

📋 Complete Command List

Run magex -l to see a plain list of all available commands (190+ commands), or use magex help for a beautiful categorized view with descriptions and usage tips.

📚 Documentation System

MAGE-X includes a hybrid documentation system with auto-detection and cross-platform browser integration.

📖 Documentation Features & Capabilities

Smart Tool Detection

Auto-detection: Automatically detects and uses the best available documentation tool
Hybrid Support: Supports both pkgsite (modern) and godoc (classic) with smart fallback
Auto-installation: Automatically installs missing tools when needed
Configuration Control: Override tool selection with docs.tool in .mage.yaml

Multiple Serving Modes

# Documentation serving
magex docs:serve         # Serve documentation locally
magex docs:godocs        # Serve with godoc format
magex docs:api           # API documentation
magex docs:examples      # Example documentation
magex docs:readme        # README documentation

Advanced Features

Port Management: Automatic port detection and conflict resolution
Cross-Platform: Browser auto-opening on macOS, Linux, and Windows
CI/CD Ready: Detects CI environments and disables browser opening
Comprehensive Generation: Documents all packages with categorization
Static Building: Enhanced Markdown with metadata and navigation
Build Artifacts: JSON metadata and organized output structure

🔧 Advanced Namespaces

MAGE-X includes specialized namespaces for power users. These are opt-in to keep the core installation lightweight.

🔧 Advanced Namespace Configuration

Available Specialized Namespaces:

Bench - Performance benchmarking and profiling
Releases - Release creation and asset distribution
Yaml - YAML configuration management and validation

To enable advanced features in your magefile:

//go:build mage

package main

import "github.com/mrz1836/mage-x/pkg/mage"

// Export core namespaces (already included by default)
type (
    Build = mage.Build
    Test  = mage.Test
    // ... other default namespaces
)

// Add advanced namespaces as needed
type (
    Integrations = mage.Integrations
    Bench        = mage.Bench
    Releases     = mage.Releases
)

This approach keeps the default installation lightweight while allowing power users to access advanced features when needed.

Example: Production Operations

// Run benchmarking and performance analysis
func PerformanceTest() error {
    var bench Bench
    return bench.Default()
}

// Run quick benchmarks with custom timing
func QuickBench() error {
    var bench Bench
    return bench.DefaultWithArgs("time=50ms")
}

See the examples directory for more custom magefile implementations.

📐 Spec-Driven Development

Integrated support for AI-driven development methodologies. Choose your style:

	📋 Spec-Kit (Recommended)	🚀 BMAD	🤖 Agent OS
Philosophy	Executable specifications	Agile workflows with AI agents	Structured agentic workflows
Interface	CLI slash commands (`/commands`)	IDE-based agents (`*commands`)	Claude Code commands + agents
Workflow	Specify → Plan → Tasks → Implement	PRD → Tech Spec → Architecture → Sprint	Write Spec → Shape → Plan → Tasks → Implement
Package	Python (`specify-cli`)	npm (`bmad-method`)	Shell scripts (curl install)
Complexity	Simple, streamlined	Full agile methodology	Flexible, profile-based
Best for	Quick start, precise requirements	Large projects, team workflows	Claude Code users, multi-agent workflows

📋 Spec-Kit - Executable Specifications (Recommended)

Spec-Kit transforms specifications into working implementations. Simple, streamlined, and perfect for getting started quickly. All feature specs live in specs/.

Quick Start

# Install spec-kit prerequisites
magex speckit:install

Development Workflow

Follow the spec-kit workflow to create and implement new features:

1. Constitution (One-time setup)

Establish project principles and development guidelines.

/speckit.constitution

2. Specify (Define requirements)

Describe what and why, not the technology. Focus on requirements and user stories.

/speckit.specify

3. Clarify (Optional but recommended)

Address underspecified areas with targeted questions.

/speckit.clarify

4. Plan (Design implementation)

Create technical implementation strategy with your chosen tech stack.

/speckit.plan

5. Tasks (Generate action items)

Generate actionable, dependency-ordered task lists.

/speckit.tasks

6. Analyze (Validate consistency)

Validate cross-artifact consistency before implementation.

/speckit.analyze

7. Implement (Build the feature)

Execute all tasks to build the feature according to the plan.

/speckit.implement

Management Commands

magex speckit:install   # Install spec-kit prerequisites
magex speckit:check     # Check installation and version
magex speckit:upgrade   # Upgrade with automatic backup/restore

Configuration (.mage.yaml):

speckit:
  constitution_path: ".specify/memory/constitution.md"
  backup_dir: ".specify/backups"
  backups_to_keep: 5
  owner_repo: "github/spec-kit"                          # GitHub owner/repo for release lookup
  git_url: "https://github.com/github/spec-kit.git"      # bare git URL of the spec-kit repo
  integration: "claude"                                   # spec-kit integration target (replaces ai_provider)
  # ai_provider: "claude"                                # deprecated; still honored as a fallback

Pro tip: Run /speckit.checklist anytime to generate custom validation criteria.

⚠️ Heads up: The PyPI package literally named specify-cli is not the official spec-kit. Per the upstream README, only install from the GitHub repo. magex speckit:install and speckit:upgrade always install from GitHub at the latest tagged release, and speckit:upgrade self-heals any prior incorrect PyPI install via --force.

⬆️ Upgrading Spec-Kit

Automated Upgrade (Recommended)

magex speckit:upgrade

The upgrade command automatically:

✅ Backs up your constitution to .specify/backups/ with timestamp
✅ Resolves the latest official release via the GitHub API (with gh → authenticated curl → git ls-remote fallback chain)
✅ Reinstalls specify-cli from git+https://github.com/github/spec-kit.git@<tag> with --force (self-heals users on the unofficial PyPI specify-cli package)
✅ Refreshes project files (slash commands, scripts, templates) at the same release tag using the modern --integration flag
✅ Restores your constitution from backup
✅ Tracks version history in .specify/version.txt
✅ Cleans old backups (keeps last 5)
✅ Verifies the upgrade with specify check

How version resolution works: the upgrade resolves the latest tag once and threads it through every install step, so the CLI and project templates always end up on the same release even if a new version ships mid-flow. If all three lookup methods (gh, curl, git ls-remote) fail, the command exits with an error rather than silently installing from the default branch.

Manual Upgrade (Alternative)

If you prefer manual control, follow upstream's official upgrade guide. Replace vX.Y.Z with the latest tag from Releases:

Step 1: Backup Your Constitution

cp .specify/memory/constitution.md ~/constitution.backup.md

Step 2: Upgrade the CLI

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify check

Do not run uv tool install specify-cli without --from — that pulls an unrelated PyPI package, not the official spec-kit. Likewise, uv tool upgrade specify-cli cannot switch sources, so it will keep upgrading whatever was originally installed.

Step 3: Upgrade Project Configuration

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --force --integration claude

The --ai flag is deprecated upstream and will be removed in v0.10.0; use --integration instead.

Step 4: Restore Custom Constitution

If you have custom constitution changes, carefully merge them back from your backup.

🚀 BMAD - AI-Driven Agile Development

BMAD (Build More, Architect Dreams) provides a full agile methodology with AI agents. Best for larger projects or teams wanting structured agile workflows.

Quick Start

# Install BMAD with interactive setup
magex bmad:install

Development Workflow

After installation, work with BMAD agents in your IDE:

1. Initialize (Set up project)

Select your development track (greenfield, brownfield, or legacy).

*workflow-init

2a. Product Brief (Product Requirements)

Create a comprehensive product brief with the PM agent.

*create-product-brief

3a. PRD (Product Requirements)

Create a comprehensive Product Requirements Document with the PM agent.

*prd

3b. UX Design (Optional)

Design user flows and wireframes with the UX agent.

*create-ux-design

4. Architecture (System Design)

Design system architecture with the Architect agent.

*create-architecture

5. Create Epics & Stories (Sprint Planning)

Break work into epics, sprints and prioritize stories.

*create-epics-and-stories

6. Test Design (Test Engineering Architect)

Design test plans and cases with the TEA agent.

*testarch-test-design

7. Check Implementation Readiness (Final validation)

Validate all artifacts before development begins.

*check-implementation-readiness

8. Start Sprint Planning (Development)

Design sprints and get started with development.

*sprint-planning

Check the status of your sprints anytime:

*sprint-status

9. Create Story (Individual tasks) (1 of 3)

Create individual user stories for implementation inside each sprint.

*create-story

10. Implement Stories (Development) (2 of 3)

Implement individual user story.

*dev-story

11. Code Review & Testing (Quality Assurance) (3 of 3)

Review and test completed user story.

*code-review

12. Retrospective (Sprint Review)

Reflect on sprint performance and identify improvements.

*retrospective

Management Commands

magex bmad:install   # Install BMAD prerequisites
magex bmad:check     # Verify installation and version
magex bmad:upgrade   # Upgrade to latest version

Configuration (.mage.yaml):

bmad:
  project_dir: "_bmad"
  version_tag: "@beta"

🤖 Agent OS - Structured Agentic Workflows

Agent OS is a system for spec-driven agentic development that provides structured workflows for AI coding agents. It integrates deeply with Claude Code and supports multi-agent delegation.

Quick Start

# Install Agent OS (base + project)
magex agentos:install

The installer will:

Install the base Agent OS to ~/agent-os (if not already installed)
Run the interactive project installer to set up your project

Development Workflow

After installation, use Claude Code slash commands to work through the Agent OS workflow:

1. Write Spec (Define your feature)

Create a detailed specification for your feature.

/write-spec

2. Shape Spec (Refine requirements)

Shape and refine the specification with targeted questions.

/shape-spec

3. Plan Product (Design implementation)

Create a technical implementation plan.

/plan-product

4. Create Tasks (Generate action items)

Generate dependency-ordered tasks from the plan.

/create-tasks

5. Implement Tasks (Build the feature)

Execute tasks to implement the feature.

/implement-tasks

6. Orchestrate Tasks (Multi-agent coordination)

Coordinate multiple agents for complex implementations.

/orchestrate-tasks

Management Commands

magex agentos:install   # Install Agent OS (base + project)
magex agentos:check     # Verify installation and version
magex agentos:upgrade   # Upgrade with user data preservation

Configuration (.mage.yaml):

agentos:
  base_dir: "agent-os"
  profile: "default"
  claude_code_commands: true
  use_claude_code_subagents: true
  standards_as_skills: false

User Data Preservation

Agent OS preserves your important project data during upgrades:

agent-os/specs/ - All your feature specifications
agent-os/product/ - Your product roadmap and mission

The following are refreshed during upgrades:

agent-os/standards/ - Standards from your profile
.claude/commands/agent-os/ - Claude Code commands
.claude/agents/agent-os/ - Claude Code agents

Pro tip: Create custom profiles in ~/agent-os/profiles/ to customize standards and workflows without losing your changes during updates.

🧪 Examples & Tests

All examples and tests run via GitHub Actions using Go 1.25+. View the examples directory for complete project demonstrations.

Run Tests

# Quick test suite
magex test

# Comprehensive testing
magex test:race test:cover test:fuzz

# JSON output for tooling integration
magex test -json               # JSON output for CI/CD tools
magex test:coverrace -json     # Coverage + race with JSON output

# Performance benchmarks
magex bench                    # Default benchmarks (10s duration)
magex bench time=50ms          # Quick benchmarks for CI
magex bench time=10s count=3   # Comprehensive benchmarks with count parameter
magex test:bench               # Via test namespace
magex test:bench time=30s      # Test namespace with custom timing

Example Projects

Basic Project - Zero-configuration MAGE-X usage
With Configuration - Using .mage.yaml for project customization
With Custom Commands - Adding project-specific commands
Zero Config - Instant productivity with magex

⚡ Benchmarks

Performance benchmarks for core MAGE-X operations:

Operation	Time	Memory	Notes
Build Detection	1.2ms	256KB	Project type and configuration
Command Execution	0.8ms	128KB	Secure command validation
Configuration Loading	2.1ms	512KB	YAML parsing and validation

Benchmarks run on Apple M1 Pro (ARM64) with Go 1.25+ All operations show consistent sub-5ms performance with minimal memory allocation

🛠️ Code Standards

MAGE-X follows strict coding standards and best practices:

Code Quality: >80% test coverage, comprehensive linting, and security scanning
Go Best Practices: Idiomatic Go code following community standards
Security First: Input validation, secure command execution, minimal dependencies
Documentation: Comprehensive godoc coverage and usage examples
AI Compliance: Machine-readable guidelines for AI assistants

Read more about our code standards and contribution guidelines.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.

👥 Maintainers


mrz

🤝 Contributing

We welcome contributions from the community! Please read our contributing guidelines and code of conduct.

How Can I Help?

All kinds of contributions are welcome! 🙌

⭐ Star the project to show your support
🐛 Report bugs through GitHub issues
💡 Suggest features with detailed use cases
📝 Improve documentation with examples and clarity
🔧 Submit pull requests with bug fixes or new features

📝 License

Built with ❤️ by the Go community

MAGE-X: Write Once, Mage Everywhere

Name		Name	Last commit message	Last commit date
Latest commit History 894 Commits
.claude/commands		.claude/commands
.github		.github
.specify		.specify
.vscode		.vscode
cmd/magex		cmd/magex
docs		docs
examples		examples
pkg		pkg
specs/001-ci-test-output		specs/001-ci-test-output
tests		tests
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
.mage.yaml		.mage.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum
magefile.go		magefile.go

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🪄 MAGE-X

Project Navigation

🧩 What's Inside

🎥 Demo

⚡ Quick Start

Which Path Should I Take?

Zero Boilerplate Installation

Quick Project Check

Full Command List

Optional: Add Custom Commands

Hybrid Execution Model

🚀 Features

Core Excellence

Developer Experience

Production Features

⚙️ Configuration

📚 Documentation

Available Commands

📋 Complete Command List

📚 Documentation System

Smart Tool Detection

Multiple Serving Modes

Advanced Features

🔧 Advanced Namespaces

📐 Spec-Driven Development

Quick Start

Development Workflow

1. Constitution (One-time setup)

2. Specify (Define requirements)

3. Clarify (Optional but recommended)

4. Plan (Design implementation)

5. Tasks (Generate action items)

6. Analyze (Validate consistency)

7. Implement (Build the feature)

Management Commands

Automated Upgrade (Recommended)

Manual Upgrade (Alternative)

Step 1: Backup Your Constitution

Step 2: Upgrade the CLI

Step 3: Upgrade Project Configuration

Step 4: Restore Custom Constitution

Quick Start

Development Workflow

1. Initialize (Set up project)

2a. Product Brief (Product Requirements)

3a. PRD (Product Requirements)

3b. UX Design (Optional)

4. Architecture (System Design)

5. Create Epics & Stories (Sprint Planning)

6. Test Design (Test Engineering Architect)

7. Check Implementation Readiness (Final validation)

8. Start Sprint Planning (Development)

9. Create Story (Individual tasks) (1 of 3)

10. Implement Stories (Development) (2 of 3)

11. Code Review & Testing (Quality Assurance) (3 of 3)

12. Retrospective (Sprint Review)

Management Commands

Quick Start

Development Workflow

1. Write Spec (Define your feature)

2. Shape Spec (Refine requirements)

3. Plan Product (Design implementation)

4. Create Tasks (Generate action items)

5. Implement Tasks (Build the feature)

6. Orchestrate Tasks (Multi-agent coordination)

Management Commands

User Data Preservation

🧪 Examples & Tests

Run Tests

Example Projects

⚡ Benchmarks

🛠️ Code Standards

🤖 AI Usage & Assistant Guidelines

👥 Maintainers

🤝 Contributing

`Project Navigation`

Packages