Skip to content

rysweet/amplihack

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1,428 Commits
.claude-plugin
.claude-plugin
 
 
.claude
.claude
 
 
.devcontainer
.devcontainer
 
 
.github
.github
 
 
Specs
Specs
 
 
amplifier-bundle
amplifier-bundle
 
 
amplifier-module-orchestrator-amplihack
amplifier-module-orchestrator-amplihack
 
 
amplihack-logparse
amplihack-logparse
 
 
amplihack
amplihack
 
 
archive/legacy
archive/legacy
 
 
docker
docker
 
 
docs
docs
 
 
examples
examples
 
 
experiments
experiments
 
 
proxy
proxy
 
 
scripts
scripts
 
 
src/amplihack
src/amplihack
 
 
tests
tests
 
 
tools
tools
 
 
worktrees
worktrees
 
 
.dockerignore
.dockerignore
 
 
.env.example
.env.example
 
 
.env.passthrough.example
.env.passthrough.example
 
 
.env.security-template
.env.security-template
 
 
.ggignore
.ggignore
 
 
.gitattributes
.gitattributes
 
 
.gitguardian.yaml
.gitguardian.yaml
 
 
.gitguardian.yml
.gitguardian.yml
 
 
.github.copilot.env
.github.copilot.env
 
 
.gitignore
.gitignore
 
 
.markdownlint.json
.markdownlint.json
 
 
.mcp.json
.mcp.json
 
 
.pre-commit-config.yaml
.pre-commit-config.yaml
 
 
.prettierrc.json
.prettierrc.json
 
 
.secrets.baseline
.secrets.baseline
 
 
CLAUDE.md
CLAUDE.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Dockerfile
Dockerfile
 
 
MANIFEST.in
MANIFEST.in
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
agents
agents
 
 
build_hooks.py
build_hooks.py
 
 
commands
commands
 
 
conftest.py
conftest.py
 
 
litellm_standalone_config.yaml
litellm_standalone_config.yaml
 
 
marketplace.json
marketplace.json
 
 
mkdocs.yml
mkdocs.yml
 
 
poetry.lock
poetry.lock
 
 
pyproject.toml
pyproject.toml
 
 
pyrightconfig.json
pyrightconfig.json
 
 
pytest.ini
pytest.ini
 
 
requirements-docs.txt
requirements-docs.txt
 
 
skills
skills
 
 
uv.lock
uv.lock
 
 

Repository files navigation

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?

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: 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

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.

Trial the Rust CLI without replacing your current install

Use the opt-in helper below to run the bundled Rust CLI under an isolated home directory. On a fresh machine, the helper downloads the latest compatible published amplihack-rs release binary automatically. Trial state stays out of your real ~/.claude setup.

# Single-command 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 and does not change the default Python-based amplihack entrypoint.

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 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

Term Definition
Agent A specialized AI role (e.g., architect, builder, reviewer) with a defined responsibility
Workflow A structured step-by-step process that guides task execution (e.g., the 23-step DEFAULT_WORKFLOW)
Orchestrator Routes tasks to the right workflow and coordinates agents
Recipe A code-enforced workflow definition (YAML) that models cannot skip or shortcut
Skill A self-contained capability that auto-activates based on context (e.g., PDF processing, Azure admin)

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)

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)
Memory & Knowledge (5 features)
Integration & Compatibility (5 features)
Quality, Security & Customization (5 features)

Fleet Management

Manage coding agents (Claude Code, Copilot, Amplifier) running across multiple Azure VMs. The fleet admiral monitors sessions, reasons about what each agent needs, and can send commands autonomously.

# 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

Key capabilities:

  • Scout discovers all VMs and sessions via azlin (no SSH needed for discovery)
  • Admiral reasoning uses LLM streaming to decide: wait, send_input, restart, or escalate
  • SessionCopilot watches local sessions and auto-continues toward a goal (/amplihack:lock)
  • Dual backend — uses Anthropic API when available, falls back to GitHub Copilot SDK
  • Safety — dangerous input patterns blocked, shell metacharacter rejection, confidence thresholds

Requires azlin for VM management.

See Fleet Tutorial | Architecture | Admiral Reasoning

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

Core Features

Skills & Integrations

Methodology & Patterns

Configuration & Customization

Development & Contributing

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

Windows Support

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

Feature Windows Native WSL / macOS / Linux
Core CLI (amplihack claude/copilot/amplifier) ✅ ✅
Workflows & recipes ✅ ✅
Persistent memory ✅ ✅
Proxy (LiteLLM) ✅ ✅
Fleet management (multi-VM) ❌ (requires tmux/SSH) ✅
Rust recipe runner ⚠️ (untested) ✅
Docker sandbox ⚠️ (Docker Desktop required) ✅

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.

About

Framework for agentic coding supporting many popular agent coding tools.

rysweet.github.io/amplihack/

Resources

Readme

Contributing

Contributing
Activity

Stars

32 stars

Watchers

1 watching

Forks

16 forks
Report repository

Releases 82

Eval: 100 agents × 5000 turns — 99.29% Latest
Mar 13, 2026
+ 81 releases

Packages

 
 
 

Contributors

Languages