amplihack

Development framework for Claude Code, GitHub Copilot CLI, and Microsoft Amplifier. Adds structured workflows, persistent memory, specialized agents, goal-seeking capabilities, autonomous execution, and continuous improvement for systematic software engineering.

📚 View Full Documentation

# Quick start
uvx --from git+https://github.com/rysweet/amplihack amplihack claude

Table of Contents

• Why amplihack?
• Quick Start
• Core Concepts
• Feature Catalog
• Configuration
• Documentation Navigator
• Development
• RustyClawd Integration
• License

Why amplihack?

The Problem: Claude Code and GitHub Copilot CLI are barebones development tools. They provide a chat interface and model access, but no engineering system for managing complexity, maintaining consistency, or shipping reliable code at scale.

The Solution: amplihack builds the engineering system around your coding agent:

• Structured workflows replace ad-hoc prompting (DEFAULT_WORKFLOW.md defines 22 systematic steps)
• Specialized agents handle architecture, building, testing, and review with defined responsibilities
• Persistent memory across sessions with knowledge graphs and discoveries
• Quality gates enforce philosophy compliance, test coverage, and code standards
• Self-improvement through reflection, pattern capture, and continuous learning

The Benefit: Systematic workflows and quality gates produce consistent, high-quality code.

Quick Start

Prerequisites

• Platform: macOS, Linux, or Windows via WSL (native Windows is not supported)
• Runtime: Python 3.12+, Node.js 18+
• Tools: git, npm, uv (astral.sh/uv)
• Optional: GitHub CLI (gh), Azure CLI (az)

Detailed setup: docs/PREREQUISITES.md

Installation

Option 1: Zero-Install (try before you commit)

# Launch with Claude Code
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
uvx --from git+https://github.com/rysweet/amplihack amplihack copilot

Option 2: Global Install (for daily use)

# Install once
uv tool install git+https://github.com/rysweet/amplihack

# Use directly
amplihack claude
amplihack amplifier
amplihack copilot

# Update later
uv tool upgrade amplihack

Alias for convenience:

# Add to ~/.bashrc or ~/.zshrc
alias amplihack='uvx --from git+https://github.com/rysweet/amplihack amplihack'

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

First Session

After launching amplihack (e.g., amplihack claude), you'll be inside an interactive agent session — a chat interface powered by your chosen coding agent. Everything you type in this session is interpreted by amplihack's workflow engine, not by your regular shell.

New users — start with the interactive tutorial:

I am new to amplihack. Teach me the basics.

This triggers a guided tutorial (60-90 minutes) that walks you through amplihack's core concepts and workflows.

Experienced users — just describe what you want to build:

cd /path/to/my/project
Add user authentication with OAuth2 support

The /dev command automatically classifies your task, detects parallel workstreams, and orchestrates execution.

Developer Quick Example

Here is a complete end-to-end example of amplihack in action:

1. Single task — fix a bug:

cd /path/to/your/project
/dev fix the authentication bug where JWT tokens expire too early

What happens:

• Classifies as: Development | 1 workstream
• Builder agent follows the full 23-step DEFAULT_WORKFLOW
• Creates a branch, implements the fix, creates a PR
• Reviewer evaluates the result — if incomplete, automatically runs another round
• Final output: # Dev Orchestrator -- Execution Complete with PR link

2. Parallel task — two independent features at once:

/dev build a REST API and a React webui for user management

What happens:

• Classifies as: Development | 2 workstreams
• Both workstreams launch in parallel (separate /tmp clones)
• Each follows the full workflow independently
• Both PRs created simultaneously

3. Investigation — understand existing code before changing it:

/dev investigate how the caching layer works, then add Redis support

What happens:

• Detects two workstreams: investigate + implement
• Investigation phase runs first, findings pass to implementation
• Result: informed implementation with full context

What you'll see during execution:

1. [dev-orchestrator] Classified as: Development | Workstreams: 2 — starting execution...
2. Builder agent output streaming (the actual work)
3. Reviewer evaluation with GOAL_STATUS: ACHIEVED or PARTIAL
4. If partial — another round runs automatically (up to 3 total)
5. # Dev Orchestrator -- Execution Complete with summary and PR links

Note: The Task() syntax shown in some documentation is an advanced programmatic API for scripting agent workflows. For interactive use, plain natural language prompts are all you need.

Core Concepts

Philosophy

• Ruthless Simplicity: Start simple, add complexity only when justified
• Modular Design: Self-contained modules ("bricks") with clear interfaces ("studs")
• Zero-BS Implementation: Every function works or doesn't exist (no stubs, TODOs, or placeholders)
• Test-Driven: Tests before implementation, behavior verification at module boundaries

Philosophy guide: ~/.amplihack/.claude/context/PHILOSOPHY.md

Workflows

All work flows through structured workflows that detect user intent and guide execution:

For most tasks, type /dev <your task> — the smart-orchestrator automatically selects the right workflow.

• DEFAULT_WORKFLOW: 23-step systematic development process, steps 0–22 (features, bugs, refactoring)
• INVESTIGATION_WORKFLOW: 6-phase knowledge excavation (understanding existing systems)
• Q&A_WORKFLOW: 3-step minimal workflow (simple questions, quick answers)
• OPS_WORKFLOW: 1-step administrative operations (cleanup, maintenance)

Workflows are customizable - edit ~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md to change process.

Workflow customization: docs/WORKFLOW_COMPLETION.md

Features

What Most People Use

These are the features you'll use daily:

Feature	What It Does
/dev <task>	The main command. Classifies your task, runs the right workflow, creates PRs
37 Agents	Specialized AI agents (architect, builder, reviewer, tester, security, etc.)
Recipe Runner	Code-enforced workflows that models cannot skip
/fix <pattern>	Rapid resolution of common errors (imports, CI, tests, config)
85+ Skills	PDF/Excel/Word processing, Azure admin, pre-commit management, and more

Everything Else

Orchestration & Execution (6 features)

• dev-orchestrator (/dev) — Unified task orchestrator with goal-seeking loop
• Recipe Runner — Code-enforced workflows (10 bundled recipes, also available via amplihack recipe CLI)
• Auto Mode — Autonomous agentic loops
• Multitask — Parallel workstream execution
• Expert Panel — Multi-expert review with voting
• N-Version Programming — Generate multiple implementations, select best

Recipe CLI — Run recipes directly from your shell (outside interactive sessions):

amplihack recipe list                  # List available recipes
amplihack recipe show smart-orchestrator  # View recipe details
amplihack recipe run smart-orchestrator -c task_description="fix login bug"
amplihack recipe run ./my-recipe.yaml --dry-run  # Preview execution
amplihack recipe validate my-recipe.yaml         # Validate recipe syntax

Full reference: docs/reference/recipe-cli-reference.md

Workflows & Methodologies (5 features)

• Document-Driven Development — Docs-first for large features
• Pre-Commit Diagnostics — Fix linting before push
• CI Diagnostics — Iterate until PR is mergeable
• Cascade Fallback — Graceful degradation
• Quality Audit — Seek/validate/fix/recurse quality loop

Memory & Knowledge (5 features)

• Kuzu Memory System — Persistent memory across sessions
• Investigation Workflow — Deep knowledge excavation with auto-documentation
• Discoveries — Documented problems and solutions
• Knowledge Builder — Build knowledge base from codebase
• Goal-Seeking Agent Generator — Create agents from prompts

Integration & Compatibility (5 features)

• GitHub Copilot CLI — Full Copilot compatibility
• Microsoft Amplifier — Multi-model support
• Azure OpenAI Proxy — Use Azure models via Claude Code
• RustyClawd — High-performance Rust launcher (5-10x faster startup)
• Remote Execution — Distribute work across Azure VMs

Quality, Security & Customization (5 features)

• Security Analysis — Cross-prompt injection defense
• Socratic Questioning — Challenge claims and clarify requirements
• Benchmarking — Performance measurement
• Customization — User preferences (verbosity, style, workflow)
• Statusline — Real-time session info

Configuration

Claude Code (Default)

Get your API key from platform.claude.com/account/keys. Claude API is pay-per-use; typical amplihack sessions cost $0.01–$2 depending on task complexity.

Add to ~/.bashrc or ~/.zshrc for permanent setup:

export ANTHROPIC_API_KEY=your-key-here

Then verify and launch:

# Verify the key is set
echo $ANTHROPIC_API_KEY

amplihack claude

GitHub Copilot CLI

All 38 agents and 73 skills work with Copilot:

# Default mode (no agent)
amplihack copilot -- -p "Your task"

# With specific agent
amplihack copilot -- --agent architect -p "Design REST API"

# List available agents
ls .github/agents/*.md

Note: Copilot shows "No custom agents configured" until you select one with --agent <name>.

Full guide: COPILOT_CLI.md

Microsoft Amplifier

Interactive configuration wizard on first startup:

amplihack amplifier

Supports all models available in GitHub Copilot ecosystem.

Azure OpenAI via Proxy

Create azure.env:

AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1
AZURE_OPENAI_API_VERSION=2024-12-01-preview  # Optional

Launch with configuration:

amplihack launch --with-proxy-config ./azure.env

Security: Never commit API keys to version control.

Full guide: docs/PROXY_CONFIG_GUIDE.md

Workflow Customization

Edit ~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md to customize the development process. Changes apply immediately to all commands.

Custom workflows: docs/WORKFLOW_COMPLETION.md

Documentation Navigator

Getting Started

• Prerequisites - Platform setup, runtime dependencies, tool installation
• Proxy Configuration - Azure OpenAI setup for Claude Code
• First Session Tutorial - Interactive guide to amplihack basics

Core Features

• Auto Mode - Autonomous agentic loops for multi-turn workflows
• Profile Management - Token optimization via component filtering
• Goal Agent Generator - Create autonomous agents from prompts
• Goal-Seeking Agents - Multi-SDK agents with memory, eval, and self-improvement
• Agent Tutorial - Step-by-step guide to generating and evaluating agents
• Interactive Tutorial - 14-lesson interactive tutor via /agent-generator-tutor skill
• Session-to-Agent - Convert interactive sessions into reusable agents
• Eval System - L1-L12 progressive evaluation with long-horizon memory testing and self-improvement
• SDK Adapters Guide - Deep dive into Copilot, Claude, Microsoft, and Mini SDK backends
• amplihack-agent-eval - Standalone eval framework package
• Kuzu Memory System - Persistent knowledge graphs
• Benchmarking - Performance measurement with eval-recipes

Skills & Integrations

• Skills System - 85+ skills including office, Azure, and workflow patterns
• GitHub Copilot Integration - Full CLI support
• Awesome-Copilot Integration - MCP server and plugin marketplace
• Azure DevOps Tools - Work item management with CLI tools

Methodology & Patterns

• Document-Driven Development - Documentation-first approach for large features
• DDD Phases - Step-by-step implementation guide
• Core Concepts - Context poisoning, file crawling, retcon writing
• Workspace Pattern - Multi-project organization

Configuration & Customization

• Hook Configuration - Session hooks and lifecycle management
• Settings Hook - Automatic validation and troubleshooting
• Workflow Customization - Modify development process
• Hooks Comparison - Adaptive hook system details

Development & Contributing

• Developing amplihack - Contributing guide, local setup, testing
• Implementation Summary - Architecture overview
• Creating Tools - Build custom AI-powered tools

Core Principles

• The Amplihack Way - Effective strategies for AI-agent development
• Philosophy - Ruthless simplicity, modular design, zero-BS implementation
• Patterns - Proven solutions for recurring challenges
• Discoveries - Problems, solutions, and learnings

Security

• Security Recommendations - Best practices and guidelines
• Security Context Preservation - Context handling

Development

Contributing

Fork the repository and submit PRs. Add agents to ~/.amplihack/.claude/agents/, patterns to ~/.amplihack/.claude/context/PATTERNS.md.

Contributing guide: docs/DEVELOPING_AMPLIHACK.md

Local Development

git clone https://github.com/rysweet/amplihack.git
cd amplihack
uv pip install -e .
amplihack launch

Testing

pytest tests/

RustyClawd Integration

RustyClawd is a high-performance Rust implementation of Claude Code with 5-10x faster startup, 7x less memory, and Rust safety guarantees. Drop-in compatible with amplihack.

Installation

Option 1: Via cargo

cargo install --git https://github.com/rysweet/RustyClawd rusty

Option 2: Build from source

git clone https://github.com/rysweet/RustyClawd
cd RustyClawd
cargo build --release
export RUSTYCLAWD_PATH=$PWD/target/release/rusty

Usage

# Explicit mode
amplihack RustyClawd -- -p "your prompt"

# Environment variable
export AMPLIHACK_USE_RUSTYCLAWD=1
amplihack launch -- -p "your prompt"

Configuration

• AMPLIHACK_USE_RUSTYCLAWD: Force RustyClawd usage (1/true/yes)
• RUSTYCLAWD_PATH: Custom binary path (optional)

License

MIT. See LICENSE.