🚀 MAP Framework Installation Guide

The MAP Framework can be installed in any project to provide powerful AI-driven development capabilities using the Modular Agentic Planner architecture.

Prerequisites

Python 3.11 or higher
Git (optional, for repository initialization)
Claude Code CLI

Quick Install

Option 1: Using UV Tool (Recommended)

Install the mapify CLI tool globally and use it to set up projects:

# Install mapify CLI
uv tool install --from git+https://github.com/azalio/map-framework.git mapify-cli

# Create a new project with MAP Framework
mapify init my-project

# Or initialize in current directory
mapify init .

⚠️ Important: PATH Configuration

After installation, you may need to add UV's bin directory to your PATH.

Verify Installation

Check if mapify is accessible:

which mapify

Expected output: /Users/your-username/.local/bin/mapify (macOS/Linux) or C:\Users\your-username\.local\bin\mapify (Windows)

If the command is not found, you need to add ~/.local/bin to your PATH.

Quick Fix: Automatic PATH Setup

UV provides a helper command to automatically configure your shell:

uv tool update-shell

This will update your shell configuration file (.zshrc, .bashrc, etc.) automatically.

Manual PATH Setup

If you prefer manual configuration, add the following to your shell configuration file:

For Zsh (macOS default, Linux):

# Add to ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

For Bash (Linux, older macOS):

# Add to ~/.bashrc or ~/.bash_profile
export PATH="$HOME/.local/bin:$PATH"

For Fish:

# Add to ~/.config/fish/config.fish
set -gx PATH $HOME/.local/bin $PATH

For Windows (PowerShell):

# Run in PowerShell as Administrator
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$env:USERPROFILE\.local\bin"
if ($userPath -notlike "*$newPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$newPath", "User")
    Write-Host "Added $newPath to user PATH"
} else {
    Write-Host "$newPath already in PATH"
}

Apply Changes

After editing your shell configuration file, apply the changes:

# For Zsh
source ~/.zshrc

# For Bash
source ~/.bashrc

# Or simply open a new terminal window

Verify PATH Configuration

Confirm mapify is now accessible:

mapify --version

Expected output:

mapify-cli version x.x.x

Troubleshooting:

If which mapify shows the path but mapify doesn't work, check file permissions: ls -la ~/.local/bin/mapify
If using a custom shell or environment, ensure UV_TOOL_BIN_DIR is not set to a different location
For Docker/CI environments, consider setting UV_TOOL_BIN_DIR=/usr/local/bin for system-wide access

Option 2: Direct UV Execution

Run without installing:

# One-time usage
uvx --from git+https://github.com/azalio/map-framework.git mapify init my-project

Installation Options

Basic Installation

mapify init my-project

This will:

✅ Create project directory
✅ Install MAP agents (including Synthesizer, DebateArbiter, ResearchAgent, FinalVerifier)
✅ Add 10 command files plus the skill-backed /map-learn slash surface
✅ Configure essential MCP servers
✅ Initialize git repository
✅ Install branch-scoped .map/<branch>/ workflow runtime used by /map-plan and /map-efficient

Note: MAP Framework is designed for Claude Code. All generated agents and commands are optimized for the Claude Code CLI.

MCP Server Configuration

Choose which MCP servers to enable:

# All available MCP servers
mapify init my-project --mcp all

# Essential servers only (sequential-thinking, deepwiki)
mapify init my-project --mcp essential

# Specific servers
mapify init my-project --mcp "sequential-thinking,deepwiki"

# No MCP servers
mapify init my-project --mcp none

Current Directory Installation

# Initialize in current directory
mapify init .

# Force overwrite existing files in current directory
mapify init . --force

Advanced Options

# Skip git initialization
mapify init my-project --no-git

# Combine options
mapify init my-project --mcp all --no-git

Manual Installation

If you prefer manual setup:

Download the latest release:

wget https://github.com/azalio/map-framework/releases/latest/download/map-kit-template-claude.zip

Extract to your project:

unzip map-kit-template-claude.zip -d your-project/
cd your-project

The structure will be:

your-project/
├── .claude/
│   ├── agents/                    # 11 specialized agents
│   │   ├── task-decomposer.md     # Decomposes tasks into subtasks
│   │   ├── actor.md               # Implements code
│   │   ├── monitor.md             # Validates implementations
│   │   ├── predictor.md           # Analyzes impact and risks
│   │   ├── evaluator.md           # Scores solution quality
│   │   ├── reflector.md           # Extracts lessons
│   │   ├── synthesizer.md         # Self-MoA: Merges variants
│   │   ├── debate-arbiter.md      # Opus: Cross-evaluates variants
│   │   ├── research-agent.md      # Isolated codebase research
│   │   ├── final-verifier.md      # Adversarial verification (Ralph Loop)
│   │   └── documentation-reviewer.md  # Reviews technical docs
│   ├── commands/                  # 10 command-backed slash commands
│   │   ├── map-efficient.md       # Optimized workflow (recommended)
│   │   ├── map-debug.md           # Debug workflow
│   │   ├── map-fast.md            # Minimal workflow (low-risk only)
│   │   ├── map-review.md          # Review workflow
│   │   ├── map-release.md         # Release workflow
│   │   ├── map-check.md           # Quality gates & verification
│   │   ├── map-plan.md            # Architecture decomposition
│   │   ├── map-task.md            # Execute one planned subtask
│   │   ├── map-tdd.md             # Test-first workflow
│   │   └── map-resume.md          # Resume interrupted workflows
│   ├── skills/
│   │   ├── README.md
│   │   ├── skill-rules.json
│   │   ├── map-planning/
│   │   │   └── SKILL.md           # Planning/reference skill
│   │   └── map-learn/
│   │       └── SKILL.md           # Skill-backed /map-learn workflow
│   └── mcp_config.json

Verify Installation

Check that everything is installed correctly:

mapify check

Output should show:

Check Available Tools
● Git version control       (available)
● Claude Code CLI          (available)

✅ All tools are installed! MAP Framework is ready to use.

Using MAP Framework

After installation, you can use MAP commands in Claude Code:

Slash Commands

# Standard production workflow (RECOMMENDED)
/map-efficient Add user authentication with JWT tokens

# Debug an issue
/map-debug Fix API timeout on large file uploads

# Quick low-risk change
/map-fast Implement a small UI tweak

# Review changes
/map-review

# Extract lessons after workflow completion
/map-learn

Workflow Architecture

MAP Framework uses slash commands as entry points that coordinate specialized agents in the main Claude Code context:

/map-efficient ⭐ - Optimized workflow (5-6 agents): task-decomposer → actor → monitor → predictor (conditional)
/map-debug - Diagnostic and fix workflows with agent coordination
/map-fast - Minimal workflow (3 agents) — small, low-risk changes (reduced analysis)
/map-review - Comprehensive review with Monitor, Predictor, and Evaluator agents
/map-check - Quality gates and verification for staged changes
/map-plan - Architect phase only: decompose task without implementation
/map-release - Package release workflow with validation gates
/map-resume - Resume incomplete MAP workflow from checkpoint
/map-learn - Extract lessons from completed workflows (implemented as a skill, not a command file)

Note: Agents are invoked automatically by slash commands. Direct agent invocation is not the recommended approach—use the slash commands above for proper workflow orchestration.

MCP Server Setup

If you selected MCP servers during installation, ensure they're configured:

Sequential-Thinking (Chain-of-Thought)

Complex problem decomposition
Iterative refinement of solutions
Edge case discovery

Deepwiki (GitHub Intelligence)

Read documentation from any GitHub repo
Analyze architectural patterns
Learn from production implementations

Optional: Semantic Search

For enhanced pattern retrieval using semantic similarity instead of keyword matching:

# Install semantic search dependencies
pip install -r requirements-semantic.txt

What you get:

🎯 Meaning-based search (not just keywords)
🧠 Synonym understanding: "JWT signature" ≈ "token verification"
⚡ Automatic deduplication of similar patterns (90% threshold)
💾 Fast embedding cache (.claude/embeddings_cache/)

Technical Details:

Model: all-MiniLM-L6-v2 (80MB, 384 dimensions)
Speed: ~3000 sentences/second on CPU
First run downloads ~500MB model (works offline afterwards)

Fallback: If not installed, MAP uses keyword matching automatically.

Troubleshooting: Common issues include:

HuggingFace authentication issues (set HF_TOKEN if needed)
Keras 3 compatibility (update to latest sentence-transformers)
Model download problems (check network connectivity)

Updating MAP Framework

To update to the latest version:

# Reinstall mapify with latest version
uv tool upgrade mapify-cli

# Update agents in existing project
mapify init . --force

Troubleshooting

Issue: Command not found

If you get zsh: command not found: mapify or bash: mapify: command not found, this is usually a PATH configuration issue.

Diagnosis:

# Check if mapify binary exists
ls ~/.local/bin/mapify

# Check if ~/.local/bin is in your PATH
echo $PATH | grep ".local/bin"

Solution 1: Add UV bin directory to PATH (Recommended)

See the PATH Configuration section above for detailed shell-specific instructions, or use UV's automatic setup:

uv tool update-shell

Then open a new terminal or run:

source ~/.zshrc  # or ~/.bashrc for Bash

Solution 2: Use full path as workaround

~/.local/bin/mapify --version

Solution 3: Check custom UV_TOOL_BIN_DIR

If you've set a custom UV_TOOL_BIN_DIR, check that location instead:

echo $UV_TOOL_BIN_DIR
ls $UV_TOOL_BIN_DIR/mapify

Solution 4: Reinstall mapify

If the binary doesn't exist, reinstall:

# Ensure UV is installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reinstall mapify
uv tool install --from git+https://github.com/azalio/map-framework.git mapify-cli

Verify the fix:

mapify --version

Issue: Claude Code not detected

# Check Claude installation
which claude

# If using local installation after migrate-installer
ls ~/.claude/local/claude

Issue: MCP servers not working

Check that MCP servers are properly configured in your Claude Code settings. The configuration file is at .claude/mcp_config.json.

Uninstalling

To remove MAP Framework:

# Remove from project
rm -rf .claude/agents/
rm -rf .claude/commands/
rm .claude/mcp_config.json
rm -rf .claude/embeddings_cache/

# Uninstall mapify CLI
uv tool uninstall mapify-cli

Support

GitHub Issues: https://github.com/azalio/map-framework/issues
Documentation: https://github.com/azalio/map-framework
Community: Discussions on GitHub

License

MIT License - See LICENSE file for details

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 MAP Framework Installation Guide

Prerequisites

Quick Install

Option 1: Using UV Tool (Recommended)

Verify Installation

Quick Fix: Automatic PATH Setup

Manual PATH Setup

Apply Changes

Verify PATH Configuration

Option 2: Direct UV Execution

Installation Options

Basic Installation

MCP Server Configuration

Current Directory Installation

Advanced Options

Manual Installation

Verify Installation

Using MAP Framework

Slash Commands

Workflow Architecture

MCP Server Setup

Sequential-Thinking (Chain-of-Thought)

Deepwiki (GitHub Intelligence)

Optional: Semantic Search

Updating MAP Framework

Troubleshooting

Issue: Command not found

Issue: Claude Code not detected

Issue: MCP servers not working

Uninstalling

Support

License

FilesExpand file tree

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

🚀 MAP Framework Installation Guide

Prerequisites

Quick Install

Option 1: Using UV Tool (Recommended)

Verify Installation

Quick Fix: Automatic PATH Setup

Manual PATH Setup

Apply Changes

Verify PATH Configuration

Option 2: Direct UV Execution

Installation Options

Basic Installation

MCP Server Configuration

Current Directory Installation

Advanced Options

Manual Installation

Verify Installation

Using MAP Framework

Slash Commands

Workflow Architecture

MCP Server Setup

Sequential-Thinking (Chain-of-Thought)

Deepwiki (GitHub Intelligence)

Optional: Semantic Search

Updating MAP Framework

Troubleshooting

Issue: Command not found

Issue: Claude Code not detected

Issue: MCP servers not working

Uninstalling

Support

License