Skip to content

amplihack

Agentic coding framework for Claude Code, Microsoft Amplifier, GitHub Copilot CLI, and Codex that uses specialized AI agents to accelerate software development through intelligent automation and collaborative problem-solving.

What is amplihack?

amplihack is a development framework for popular coding agent systems (Claude Code, Microsoft Amplifier, GitHub Copilot CLI, and Codex) that leverages multiple specialized AI agents working together to handle complex software development tasks. It combines ruthless simplicity with powerful capabilities to make AI-assisted development more effective and maintainable.

Quick Navigation

New to amplihack? Start here:

Looking for something specific?

🚀 Get Started

Everything you need to install and configure amplihack.

Choose Your Tool

amplihack works with multiple agentic coding tools. Choose the one that fits your workflow:

# Launch with Claude Code (default)
uvx --from git+https://github.com/rysweet/amplihack amplihack claude

# Launch with Microsoft Amplifier
uvx --from git+https://github.com/rysweet/amplihack amplihack amplifier

# Launch with GitHub Copilot CLI
uvx --from git+https://github.com/rysweet/amplihack amplihack copilot

Tool Compatibility Matrix:

Feature Claude Code Amplifier Copilot CLI Codex
Plugin Architecture ✅ Yes ❌ No ❌ No ❌ No
Per-Project Staging ✅ Yes ✅ Yes ✅ Yes ✅ Yes
All Agents (38) ✅ Yes ✅ Yes ✅ Yes ⚠️ Limited
All Skills (73) ✅ Yes ✅ Yes ✅ Yes ⚠️ Limited
All Commands (24) ✅ Yes ✅ Yes ✅ Yes ⚠️ Limited
Workflows ✅ All ✅ All ✅ All ⚠️ Limited
Auto Mode ✅ Yes ✅ Yes ✅ Yes ⚠️ Limited

New to amplihack? After launching, try the interactive tutorial:

Task(subagent_type='guide', prompt='I am new to amplihack. Teach me the basics.')

The guide agent will walk you through workflows, prompting strategies, and hands-on exercises (60-90 minutes).

Plugin Architecture ⭐ NEW

Centralized plugin system that works across all your projects:

Note: Plugin architecture is Claude Code only. Microsoft Amplifier, GitHub Copilot CLI, and Codex use per-project ~/.amplihack/.claude/ staging instead.

Installation

Configuration

Tool-Specific Setup

Claude Code (Default)

  • Requires: $ANTHROPIC_API_KEY environment variable for Anthropic models
  • Plugin mode: Install globally with Plugin Installation Guide
  • Per-project mode: Copy ~/.amplihack/.claude/ directory to your project
  • Azure OpenAI: Use proxy configuration (see Proxy Configuration)

Microsoft Amplifier

amplihack amplifier

Amplifier walks you through model configuration on first startup. Supports all Amplifier-compatible models including Claude, GPT-4, and local models.

GitHub Copilot CLI

amplihack copilot
  • Uses GitHub Copilot models (switch with /model command)
  • Adaptive hooks enable preference injection and context loading
  • All 38 agents available via --agent <name> flag
  • See GitHub Copilot Integration for complete guide

Codex

  • Limited support via per-project ~/.amplihack/.claude/ staging
  • Most features work but may require adaptation
  • Tested primarily with Claude models

General Configuration

Deployment

💡 Core Concepts

Understand the philosophy and architecture behind amplihack.

Philosophy & Principles

Architecture

Key Features

📋 Workflows

Proven methodologies for consistent, high-quality results.

Automatic Workflow Classification ⭐ NEW

Mandatory at Session Start (Issue #2353) - amplihack now automatically classifies your request and executes the appropriate workflow when you start a session:

  • 4-Way Classification: Q&A, Operations, Investigation, or Development
  • Recipe Runner Execution: Code-enforced workflow steps with fail-fast behavior
  • Graceful Fallback: Recipe Runner → Workflow Skills → Markdown
  • Explicit Command Bypass: Commands like /fix, /analyze skip auto-classification

Quick Reference: | Your Request | Classified As | Workflow | Steps | |--------------|---------------|----------|-------| | "What is..." | Q&A | Direct answer | 3 | | "Clean up..." | Operations | Direct execution | 1 | | "How does X work?" | Investigation | Deep exploration | 6 | | "Add feature X" | Development | Full workflow | 23 |

Implementation: src/amplihack/workflows/ - classifier, execution_tier_cascade, session_start modules

Core Workflows

DDD Deep Dive

Document-Driven Development is a systematic methodology where documentation comes first and acts as the specification.

Recipe Runner

Code-enforced workflow execution engine with declarative YAML recipes.

Quick Start:

# List available recipes
amplihack recipe list

# Execute a workflow recipe
amplihack recipe run default-workflow \
  --context '{"task_description": "Add user authentication", "repo_path": "."}'

# Validate recipe YAML
amplihack recipe validate my-workflow.yaml

# Show recipe details
amplihack recipe show default-workflow

Advanced Workflows

🤖 Agents & Tools

Specialized AI agents and tools for every development task.

Core Agents

  • Architect - System design and specifications
  • Builder - Code implementation from specs
  • Reviewer - Quality assurance and compliance
  • Tester - Test generation and validation

Specialized Agents

Goal-Seeking Agents

Autonomous agents that learn, remember, teach, and apply knowledge across four SDK backends.

📚 Tutorials (Learning-Oriented)

  • Goal-Seeking Agent Tutorial - Interactive 10-lesson tutorial covering agent generation, SDK selection, multi-agent architecture, evaluations (L1-L12), and self-improvement loops

📖 How-To Guides (Problem-Oriented)

📋 Reference (Information-Oriented)

💡 Explanation (Understanding-Oriented)

Key Features:

  • SDK-Agnostic: Write once, run on Copilot, Claude, Microsoft Agent Framework, or lightweight mini-framework
  • 7 Learning Tools: learn, search, explain, verify, find gaps, store, summary
  • Progressive Eval (L1-L12): From simple recall to far transfer across domains
  • 3-Run Median Eval: --runs 3 for stable benchmarks (reduces LLM stochasticity)
  • Multi-Vote Grading: --grader-votes 3 for noise reduction on ambiguous answers
  • Teaching Evaluation: Multi-turn teacher-student knowledge transfer (Chi 1994, Vygotsky ZPD)
  • Self-Improvement Loop: EVAL -> ANALYZE -> RESEARCH -> IMPROVE -> RE-EVAL -> DECIDE with automated error analysis
  • 5 Domain Agents: Code Review, Meeting Synthesizer, Data Analysis, Document Creator, Project Planning
  • Long-Horizon Memory Eval: 1000-turn dialogue stress test
  • Multi-SDK Comparison: 4-way eval comparison via sdk_eval_loop.py
  • Current Score: 97.5% overall median (L1-L7, 3-run median, mini SDK)

Memory-Enabled Agents ⭐ NEW

Learning agents that improve through experience and persist knowledge across sessions.

Key Features:

  • Standalone Library: pip install amplihack-memory-lib - Use in any Python project
  • Persistent Memory: SQLite-based storage (no external database required)
  • Pattern Recognition: Automatically recognize recurring situations after 3 occurrences
  • Learning Metrics: Track runtime improvement, pattern recognition rate, confidence growth
  • Four Experience Types: SUCCESS, FAILURE, PATTERN, INSIGHT
  • Validated Learning: Test-driven validation ensures agents actually learn

Demonstration Agents:

  1. Documentation Analyzer - Learns documentation quality patterns (MS Learn integration)
  2. Code Pattern Recognizer - Identifies reusable code patterns and abstractions
  3. Bug Predictor - Predicts likely bug locations based on learned characteristics
  4. Performance Optimizer - Learns performance anti-patterns and optimization techniques

Meta-Agentic Task Delegation ⭐ NEW

Run AI agents in isolated subprocess environments with automatic validation and evidence collection.

Key Feature: Delegate complex tasks to specialized personas (guide, QA engineer, architect, junior developer) running in isolated environments. The system monitors execution, collects evidence, validates success criteria, and provides detailed reports.

Workflow Agents

Claude Code Skills

Modular, on-demand capabilities that extend amplihack:

Scenario Tools

Production-ready executable tools following the Progressive Maturity Model:

Available Tools

  • check-broken-links - Automated link checker for documentation sites and markdown files
  • Check GitHub Pages sites or local documentation
  • Catch broken internal links and dead external URLs
  • Integrates with Makefile: make check-broken-links TARGET=<url-or-path>

  • Returns exit codes for CI integration

  • Platform Bridge - Multi-platform support for GitHub and Azure DevOps

  • Automatic platform detection from git remotes
  • Unified API for both GitHub and Azure DevOps
  • Zero configuration required
  • Used by DEFAULT_WORKFLOW for cross-platform compatibility

⚡️ Commands & Operations

Execute complex tasks with simple slash commands.

Command Reference

Core Commands

  • /ultrathink - Main orchestration command (reads workflow, orchestrates agents)
  • /analyze - Comprehensive code review for philosophy compliance
  • /improve - Capture learnings and self-improvement
  • /fix - Intelligent fix workflow for common error patterns

Document-Driven Development Commands

  • /ddd:0-help - Get help and understand DDD
  • /ddd:prime - Prime context with DDD overview
  • /ddd:1-plan - Phase 0: Planning & Alignment
  • /ddd:2-docs - Phase 1: Documentation Retcon
  • /ddd:3-code-plan - Phase 3: Implementation Planning
  • /ddd:4-code - Phase 4: Code Implementation
  • /ddd:5-finish - Phase 5: Testing & Phase 6: Cleanup
  • /ddd:status - Check current phase and progress

Advanced Commands

  • /amplihack:n-version <task> - Generate N independent solutions for critical code
  • /amplihack:debate <question> - Multi-agent structured debate for decisions
  • /amplihack:cascade <task> - Fallback cascade for resilient operations
  • /amplihack:customize - Manage user preferences and settings

Auto Mode

🧠 Memory & Knowledge

Persistent memory systems and knowledge management.

5-Type Memory System ⭐ NEW

Psychological memory model with episodic, semantic, procedural, prospective, and working memory:

Memory Systems

Kuzu Memory System

Embedded graph-based memory using Kuzu (NO Neo4j required):

Code Graph

Query your codebase structure via the Kuzu graph database:

python -m amplihack.memory.kuzu.query_code_graph stats
python -m amplihack.memory.kuzu.query_code_graph search <name>
python -m amplihack.memory.kuzu.query_code_graph functions --file <path>

Historical Research (Neo4j was replaced with Kuzu in Week 7):

Memory Testing

External Knowledge

Blarify Code Indexing

Complete code indexing and analysis with multi-language support:

🔧 Features & Integrations

Specific features and third-party integrations.

Native Binary Trace Logging ⭐ NEW

Optional request/response logging using Anthropic's native Claude binary:

Key Features: Zero overhead when disabled (<0.1ms), automatic security sanitization, session-scoped JSONL logs, no NPM dependencies.

Power Steering

Intelligent guidance system that prevents common mistakes:

Compaction Handling ⭐ NEW

Robust handling of conversation compaction in long sessions:

Other Features

Third-Party Integrations

⚙️ Configuration & Deployment

Advanced configuration, deployment patterns, and environment management.

Configuration

Deployment

Build System

Remote Sessions

🧪 Testing & Quality

Testing strategies, quality assurance, and validation patterns.

Testing

Code Review

🔒 Security

Security guidelines, context preservation, and best practices.

Security Documentation

Safe Operations

🛠️ Troubleshooting & Discoveries

Fix common issues and learn from past solutions.

Troubleshooting

Documentation Guides

How-To Guides

🔬 Research & Advanced Topics

Cutting-edge research, experimental features, and deep technical dives.

Research Projects

Advanced Topics

📚 Reference & Resources

Quick references, guides, and additional resources.

Quick References

Developing amplihack

Contributing

GitHub & Community

Philosophy in Action

amplihack follows three core principles:

  1. Ruthless Simplicity: Start with the simplest solution that works. Add complexity only when justified.

  2. Modular Design: Build self-contained modules (bricks) with clear public contracts (studs) that others can connect to.

  3. Zero-BS Implementation: No stubs, no placeholders, no dead code. Every function must work or not exist.

Example Workflow

# Start with a feature request
/ultrathink "Add user authentication to the API"

# UltraThink will:
# 1. Read the default workflow
# 2. Orchestrate multiple agents (architect, security, api-designer, database, builder, tester)
# 3. Follow all workflow steps systematically
# 4. Ensure quality and philosophy compliance
# 5. Generate tests and documentation

Use Cases

amplihack excels at:

  • Feature Development: Orchestrate multiple agents to design, implement, test, and document new features
  • Code Review: Comprehensive analysis for philosophy compliance and best practices
  • Refactoring: Systematic cleanup and improvement of existing code
  • Investigation: Deep understanding of complex codebases and architectures
  • Integration: Connect external services with proper error handling and testing
  • Security: Vulnerability assessment and secure implementation patterns

Need Help?

Ready to get started? Head to Prerequisites to set up amplihack in your development environment.