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

Requires: Python 3.11+, Node.js 18+, git, uv.
macOS/Linux/WSL only.

# Quick start — uvx is uv's package runner (like npx for Python)
uvx --from git+https://github.com/rysweet/amplihack amplihack claude

New to amplihack? Start with Quick Start, then
Core Concepts, then Configuration.

Want to contribute? Go to Development and
CONTRIBUTING.md.

Already familiar? Check out Features and
Documentation Navigator.

Table of Contents

• Why amplihack?
• Quick Start
• Core Concepts
• Feature Catalog
• Fleet Management
• Configuration
• Documentation Navigator
• Windows Support
• 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 has
  partial support.
• Runtime: Python 3.11+, Node.js 18+
• Tools: git, npm, uv (astral.sh/uv)
• Recommended: Rust/cargo (rustup.rs) — required for
  the Rust recipe runner
• Optional: GitHub CLI (gh), Azure CLI (az)

Detailed setup:
docs/PREREQUISITES.md

Installation

Install the prerequisites above first, then choose an option below.

Option 1: Quick Start (requires uv and Python)

# 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

This launches an interactive Claude Code session enhanced with amplihack's
workflows, specialized agents, and development tools. You'll get a CLI prompt
where you can describe tasks and the framework orchestrates their execution.

Rust CLI status

The main amplihack entrypoint is still Python-owned today, but the runtime is
no longer purely Python-first:

• when an installed Rust CLI is available, the Python entrypoint now hands
  install, recipe, mode, and update through to that Rust binary
• when amplihack-hooks is installed, hook configuration now prefers the Rust
  hook engine automatically unless AMPLIHACK_HOOK_ENGINE=python is set

The fully isolated helper below is still the easiest way to exercise the Rust
CLI end-to-end without touching your real ~/.claude state. On a fresh machine,
it downloads the latest compatible published amplihack-rs release binary
automatically.

# Single-command GitHub install for daily use
uvx --from git+https://github.com/rysweet/amplihack \
  amplihack-rust-trial \
  install

# The installer downloads the latest published Rust release, places it in
# ~/.local/bin, updates your shell profile PATH, and runs `amplihack install`
# automatically so the framework assets are ready immediately.

# Fully isolated fresh-machine flow
uvx --from git+https://github.com/rysweet/amplihack \
  amplihack-rust-trial \
  --trial-home ~/.amplihack-rust-e2e \
  copilot

# Try specific commands without touching your current amplihack install
uvx --from git+https://github.com/rysweet/amplihack amplihack-rust-trial recipe list
uvx --from git+https://github.com/rysweet/amplihack amplihack-rust-trial mode detect

By default the helper stores trial state under ~/.amplihack-rust-trial. It
remains useful for proving end-to-end Rust behavior because the default product
entrypoint and install/bootstrap flow are still not fully Rust-native.

Option 2: Global Install (for daily use)

# Install once directly from GitHub
uvx --from git+https://github.com/rysweet/amplihack amplihack-rust-trial install

# Use directly
amplihack claude
amplihack amplifier
amplihack copilot

# Update later
amplihack update

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 is amplihack's primary entry point for development tasks. It
automatically classifies your task, detects parallel workstreams, and
orchestrates execution through the 23-step default workflow.

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:

Everything Else

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

# From the shell:
amplihack fleet              # Interactive TUI dashboard
amplihack fleet scout        # Discover all VMs/sessions, dry-run reasoning
amplihack fleet advance      # Send next commands to sessions (live)
amplihack fleet status       # Quick text overview
amplihack fleet adopt devo   # Bring existing sessions under management
amplihack fleet auth devo    # Propagate auth tokens to a VM

# From the Claude Code REPL (interactive session):
/fleet scout                 # Same commands available as slash commands
/fleet advance --session deva:rustyclawd

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.

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
• 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
• Gherkin Expert - BDD specification
  skill for behavioral requirements (+26% over English)
• 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

Windows Support

amplihack has partial support for Windows native (PowerShell). The recommended
approach remains WSL for full compatibility, but core features work
natively.

Installation on Windows native:

# Requires Python 3.11+, Node.js 18+, git, uv
uvx --from git+https://github.com/rysweet/amplihack amplihack copilot

Known limitations:

• Fleet commands (amplihack fleet *) are unavailable — they require tmux and
  SSH, which are Linux/macOS only. Use WSL for fleet operations.
• Some language server integrations (multilspy) may have reduced functionality.
• File permission management (chmod) is a no-op on Windows.

For full compatibility, use
WSL.

See issue #3112 for the
complete Windows compatibility tracker.

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/

Some tests require optional dependencies (e.g. kuzu graph database). These skip
gracefully when the dependency is absent via pytest.importorskip. See
docs/KUZU_TEST_CONFIGURATION.md for details
on kuzu test isolation and the approved skip pattern.

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.