amplihack

Development framework for popular coding agent systems (Claude Code, Github Copilot CLI, Microsoft Amplifier, codex) that provides structured dev workflows, memory, a package of useful skills and agents, goal-seeking agent generator, auto mode, self-improvement with reflection, and commands for getting the most out of agentic coding. Unlikely to work on Windows without WSL.

📚 View Full Documentation

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

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

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

Try asking the amplihack-guide agent for help.

Table of Contents

• Quick Start
  • Prerequisites
  • Basic Usage
  • Create Alias for Easy Access
• Core Concepts
  • Workflow
  • Philosophy
• Configuration
  • Anthropic (Default)
  • Azure OpenAI
  • GitHub Copilot CLI
  • Custom Workflows
• Commands Reference
• Agents Reference
  • Core Agents
  • Specialized Agents
• Features
  • Workflow Orchestration by Default
  • Goal-Seeking Agent Generator
  • Profile Management
  • GitHub Pages Documentation Generation
  • Additional Features
  • Statusline
• Documentation
  • Getting Started
  • Features
  • Patterns
  • Configuration
  • Development
  • Methodology
  • Security
  • Core Principles
• Development
  • Contributing
  • Local Development
  • Testing
• License

Quick Start

Prerequisites

• MacOS, WSL, or Linux
• Python 3.2+, Node.js 18+, npm, git
• GitHub CLI (gh) for PR/issue management
• az cli for AzDO and Azure skills
• uv (astral.sh/uv)

For detailed installation instructions, see docs/PREREQUISITES.md.

You may find that its useful to use amplihack with azlin which makes it easy to start linux based agentic coding vms in the azure cloud.

Basic Usage

# Launch Claude Code with amplihack
amplihack launch

# With Azure OpenAI (requires azure.env configuration)
amplihack launch --with-proxy-config ./azure.env

# Work directly in a GitHub repository
amplihack launch --checkout-repo owner/repo

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. Takes 60-90 minutes to complete.

Already familiar? Tell Claude Code to cd /path/to/my/project and provide your prompt. All prompts are automatically wrapped with /amplihack:ultrathink for workflow orchestration (use --no-ultrathink flag to opt-out for simple tasks).

Create Alias for Easy Access

Instead of typing the full uvx command, create an alias:

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

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

Now you can simply run:

amplihack launch
amplihack launch --with-proxy-config ./azure.env
amplihack launch --checkout-repo owner/repo

Core Concepts

Philosophy

• Simplicity - Start simple, add only justified complexity
• Modular - Self-contained modules with clear interfaces
• Test-driven - Tests before implementation
• Zero BS Principle - continually reinforcing zero tolerance of stubs, TODOs, faked apis or data, etc

Workflows

The system tries to direct all work to one of a few customizeable structured workflows which attempt to detect the user intent and guide the agent through a structured set of steps. The workflows try to put solid gaurdrails and multiagent points of view around the work. See the DEFAULT_WORKFLOW.md for an example.

Configuration

amplihack works with Claude Code and Anthropic models by default. You can, however also use it with Microsoft Amplifier and Github Copilot CLI.

Anthropic (Default)

Set your $ANTHROPIC_API_KEY prior to launching amplihack.

Other models with GH Copilot CLI

Github Copilot CLI supports all the models supported by GH Copilot - though most of the framework is only tested with Anthropic.

amplihack copilot

and then use /model

Other models with Microosft Amplifier

Amplifier wil walk you through model configuration on first startup:

amplihack amplfier

Azure OpenAI in Claude via proxy

To use Azure OpenAI models, create an azure.env file with the following minimum configuration:

# Required: Your Azure OpenAI API key
AZURE_OPENAI_API_KEY=your-api-key

# Required: Azure OpenAI endpoint (base URL without path)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com

# Required: Model deployment name (use either BIG_MODEL or AZURE_OPENAI_DEPLOYMENT_NAME)
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1

# Optional: API version (defaults to 2025-04-01-preview)
AZURE_OPENAI_API_VERSION=2024-12-01-preview

Launch with Azure configuration:

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

Note: The endpoint should be just the base URL (e.g., https://your-resource.openai.azure.com) without /openai or other path suffixes. The proxy will automatically construct the correct API paths.

Security Warning: Never commit API keys to version control. Use environment variables or secure key management systems.

GitHub Copilot CLI

amplihack fully supports GitHub Copilot CLI with adaptive hooks that enable preference injection and context loading. All 38 agents, 73 skills, and 24 commands work seamlessly with Copilot.

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

# With specific agent
amplihack copilot -- --agent architect -p "Design a REST API"
amplihack copilot -- --agent builder -p "Implement the spec"

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

Note: Copilot shows "No custom agents configured" until you select one with --agent <name>. All 38 amplihack agents are available in .github/agents/.

See COPILOT_CLI.md for complete integration guide and docs/HOOKS_COMPARISON.md for adaptive hook system details.

Custom Workflows

The iterative-step workflow is fully customizable. Edit ~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md to modify the development process - changes apply immediately to /ultrathink and other commands. See docs/WORKFLOW_COMPLETION.md for detailed customization instructions.

Commands Reference

| Command | Description | | ------------------------------ | ------------------------------------------------------- | | amplihack new | Generate goal-seeking agents from prompts | | /amplihack:ultrathink | Deep multi-agent analysis (now DEFAULT for all prompts) | | /amplihack:analyze | Code analysis and philosophy compliance review | | /amplihack:auto | Autonomous agentic loop (clarify → plan → execute) | | /amplihack:cascade | Fallback cascade for resilient operations | | /amplihack:debate | Multi-agent debate for complex decisions | | /amplihack:expert-panel | Multi-expert review with voting | | /amplihack:n-version | N-version programming for critical code | | /amplihack:socratic | Generate Socratic questions to challenge claims | | /amplihack:reflect | Session reflection and improvement analysis | | /amplihack:improve | Capture learnings and implement improvements | | /amplihack:fix | Fix common errors and code issues | | /amplihack:modular-build | Build self-contained modules with clear contracts | | /amplihack:knowledge-builder | Build comprehensive knowledge base | | /amplihack:transcripts | Conversation transcript management | | /amplihack:xpia | Security analysis and threat detection | | /amplihack:customize | Manage user-specific preferences | | /amplihack:ddd:0-help | Document-Driven Development help and guidance | | /amplihack:ddd:1-plan | Phase 0: Planning & Alignment | | /amplihack:ddd:2-docs | Phase 1: Documentation Retcon | | /amplihack:ddd:3-code-plan | Phase 3: