Amplifier Setup (`amp`)

A transparent wrapper for Claude Code that automatically manages the Amplifier development environment.

✨ What's New (December 2025)

Complete workspace isolation with git worktrees! Each project now gets its own isolated environment:

🔒 Isolated Python environments - No more dependency conflicts between projects
🌳 Git worktree-based - Work on different branches per project independently
📁 Separate AI working directories - Each project has its own ai_working/ and .data/
🚀 New commands: amp workspace, amp new, amp update, amp uninstall
🔌 Claude Code plugins - Git workflow helpers (/pull, /submit-pr) with more coming

See full changelog →

Quick Start

One-Time Installation

Windows

Step 1: Install (PowerShell or Command Prompt)

irm https://raw.githubusercontent.com/kenotron-ms/amplifier-setup/main/install.ps1 | iex

Step 2: Reload your shell

PowerShell: . $PROFILE
CMD: Close and reopen Command Prompt

Step 3: Done!

Installation complete. Works in PowerShell, pwsh, and CMD.

Mac / Linux

Step 1: Install

curl -fsSL https://raw.githubusercontent.com/kenotron-ms/amplifier-setup/main/install.sh | bash

Step 2: Reload your shell

source ~/.${SHELL##*/}rc

Step 3: Done!

Installation complete. You only need to do this once.

Everyday Use

Every time you want to work with Claude Code + Amplifier:

cd ~/your-project
amp

That's it! Use amp exactly like you would use claude:

amp "implement feature X"
amp --model opus
amp --help

What is `amp`?

amp is a command that you use exactly like claude, but with all the amplifier complexity handled automatically behind the scenes.

The Problem

Setting up and maintaining the amplifier environment involves many manual steps:

Cloning the amplifier repository
Running make install after every clone/update
Activating the virtual environment
Providing workspace context to Claude Code
Managing updates

This creates friction, especially for non-technical users.

The Solution

amp is a direct replacement for the claude command that:

✅ Installs amplifier automatically on first run
✅ Updates amplifier daily (when needed)
✅ Activates the virtual environment automatically
✅ Provides proper workspace context to Claude Code
✅ Passes through all claude arguments transparently

You just type amp instead of claude - that's it.

Detailed Installation

Prerequisites

The installer automatically installs all prerequisites:

Windows:

Windows 10 1809+ or Windows 11 (for winget package manager)
PowerShell or Command Prompt

Mac:

Homebrew (installed automatically if missing)

Linux:

Python 3.11+ (install manually: sudo apt install python3 or equivalent)
Git (install manually: sudo apt install git or equivalent)

The installer automatically installs:

✅ Python 3.12 (if not present)
✅ Git (if not present - Windows/Mac only)
✅ uv (Python package manager)
✅ Claude Code (using native binary installer - no Node.js required)

Installation Options

Windows

PowerShell or Command Prompt:

irm https://raw.githubusercontent.com/kenotron-ms/amplifier-setup/main/install.ps1 | iex

Mac / Linux

Terminal:

curl -fsSL https://raw.githubusercontent.com/kenotron-ms/amplifier-setup/main/install.sh | bash

This will:

Download latest amp.sh and amp-workspace.sh to ~/.amp/
Add it to your ~/.bashrc and ~/.zshrc
Make it available immediately in your current shell

That's it! After installation completes, just type amp to get started.

Note: This installer is idempotent - run it anytime to get the latest version of amp scripts.

Note: The installer will tell you exactly what to run after it completes.

Usage

Basic Usage

Use amp exactly like you would use claude:

# Start Claude Code in current directory (creates workspace worktree if needed)
amp

# Run with a prompt
amp "implement feature X"

# Pass any claude arguments
amp --help
amp --model opus
amp "analyze this code" --add-dir ../other-project

Creating New Projects

# Initialize current directory as an Amplifier project
amp new

# Create a new project directory
amp new my-project

# Creates:
# - CLAUDE.md with Flow-Driven Development guidance
# - Git repository (if git is available)
# - Offers to create GitHub repo (if gh CLI is available)

Workspace Management

# List all workspace worktrees
amp workspace list

# Show info about current workspace
amp workspace info

# Remove a workspace worktree
amp workspace remove
amp workspace remove /path/to/project

# Clean up orphaned workspaces (project directories deleted)
amp workspace prune

Update

# Update everything (amplifier + amp scripts)
amp update

# Then reload your shell to use updated scripts
source ~/.zshrc  # or source ~/.bashrc

Uninstall

# Remove amp (keeps workspace data)
amp uninstall

# Remove amp and all workspace data
amp uninstall --data

# View uninstall options
amp uninstall --help

First Run

On your first amp command, it will automatically:

Check that prerequisites are installed
Clone the amplifier repository to ~/.amp/main
Run make install to set up dependencies
Create a workspace worktree for your current directory
Launch Claude Code with proper workspace context

This takes about 2-5 minutes depending on your network speed.

Subsequent Runs

After the first run, amp is fast:

Checks for updates once per 24 hours
If updates are available, pulls and reinstalls automatically
Otherwise, launches immediately

How It Works

Workspace Pattern

When you run amp from any directory, it automatically provides Claude Code with workspace context via --append-system-prompt:

I'm working on the {project-name} project.
The project is located at {current-directory}.
The {worktree-path} directory is the amplifier dev environment for this workspace.

Please read @{current-directory}/CLAUDE.md for project-specific guidance.

Whenever we execute any tools, we should assume {current-directory} is the root directory.

This tells Claude Code:

What project you're working on
Where the project is located
Where the amplifier dev environment is (separate from your project)
To look for CLAUDE.md for project-specific instructions
To use your current directory as the working directory

File Structure

~/.amp/                          # State directory
├── amp.sh                       # The amp command (installed by install.sh)
├── amp-workspace.sh             # Workspace worktree management
├── .amp_ready                   # Flag: bootstrap completed
├── .amp_last_check              # Timestamp of last update check
├── .amp.log                     # Operation log
└── w/                           # Workspace worktrees
    ├── Users-ken-projects-foo/  # Worktree for /Users/ken/projects/foo
    │   ├── .git                 # Git worktree metadata
    │   ├── .venv/               # Isolated Python environment
    │   ├── ai_working/          # Project-specific AI work
    │   ├── .data/               # Project-specific data
    │   ├── amplifier/           # Amplifier modules
    │   └── Makefile             # Full amplifier functionality
    └── Users-ken-workspace-bar/ # Worktree for /Users/ken/workspace/bar
        └── (same structure)

~/.amp/main/                     # Main amplifier repository (git worktree parent)
├── .venv/                       # Main virtual environment
├── Makefile                     # Build system
└── amplifier/                   # Amplifier modules

Key Concept: Each project directory gets its own isolated amplifier worktree in ~/.amp/w/. This provides complete isolation of:

Python dependencies (.venv)
AI working files (ai_working/)
Data files (.data/)
Git branches (can be on different branches)

The main amplifier repository at ~/.amp/main serves as the parent for all workspace worktrees.

Configuration

Environment Variables

AMP_HOME - Override state directory (default: ~/.amp)
AMP_AMPLIFIER_DIR - Override amplifier clone location (default: ~/.amp/main)

Example:

export AMP_HOME="$HOME/.my-amp"
export AMP_AMPLIFIER_DIR="$HOME/.my-amp/main"
amp

Update Frequency

By default, amp checks for updates once per 24 hours. To force an update check:

rm ~/.amp/.amp_last_check
amp

Health Check (`amp doctor`)

Check if your amp setup is healthy with a single command:

Mac / Linux

curl -fsSL https://raw.githubusercontent.com/kenotron-ms/amplifier-setup/main/doctor.sh | bash

What it checks

Prerequisites
- ✅ Python 3.11+ installed
- ✅ Git installed
- ✅ uv package manager installed
- ✅ Claude Code installed
amp Installation
- ✅ Scripts installed correctly (amp.sh, amp-workspace.sh)
- ✅ amp function can be loaded successfully
- ✅ amp configured in shell RC file (.bashrc/.zshrc)
Script Versions
- ✅ Local scripts match remote versions
- ⚠️ Shows if updates are available
Repository Health
- ✅ Main amplifier repo on correct branch (amplifier-claude)
- ✅ Main repo tracking correct upstream (origin/amplifier-claude, not origin/main)
- ✅ Main repo in sync with remote
- ✅ All worktrees on valid branch (amplifier-claude or workspace/*)
- ✅ All worktrees tracking correct upstream (origin/amplifier-claude)
- ✅ All worktrees pointing to correct origin
- ✅ All worktrees have correct Claude Code settings:
  - .claude/settings.local.json exists
  - amplifier-setup marketplace configured
  - git@amplifier-setup plugin enabled
Git Plugin Verification (NEW!)
- ✅ Git plugin installed correctly
- ✅ /git:submit-pr command exists
- ✅ All expected workflow steps present (8 steps)
- ✅ Key features: auto-merge, monitoring, autonomous fixing
- ✅ Continuous polling with sleep + gh pr
Summary Report
- Shows counts: ✅ Success, ⚠️ Warnings, ❌ Errors
- Provides recommended actions

Sample Output

🏥 amp Doctor - Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Checking Prerequisites
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Python 3.12.3
✅ Git installed: git version 2.43.0
✅ uv installed: uv 0.5.0
✅ Claude Code: 1.2.0

🔧 Checking amp Installation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ AMP_HOME exists: /Users/you/.amp
✅ amp.sh found
✅ amp-workspace.sh found
✅ amp function can be loaded successfully
✅ amp configured in shell RC file

📦 Checking Script Versions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ amp.sh is up to date
⚠️  amp-workspace.sh differs from remote version
ℹ️  Run 'amp update' to sync

🌿 Checking Amplifier Repository Branch
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Main repo on correct branch: amplifier-claude
✅ Main repo upstream: origin/amplifier-claude ✓
✅ Branch amplifier-claude exists on remote
✅ Main repo is up to date: abc1234

🌲 Checking Project Worktrees
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 2 worktree(s):

  📁 my-project
    ✅ Branch: workspace/Users-you-my-project (workspace branch) ✓
    ✅ Upstream: origin/amplifier-claude ✓
    ✅ Origin: [email protected]:username/amplifier.git ✓
    ✅ In sync with main repo
    ✅ Claude Code settings configured ✓

  📁 another-project
    ✅ Branch: workspace/Users-you-another-project (workspace branch) ✓
    ✅ Upstream: origin/amplifier-claude ✓
    ✅ Origin: [email protected]:username/amplifier.git ✓
    ✅ In sync with main repo
    ✅ Claude Code settings configured ✓

🔌 Verifying Git Plugin via amp
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ git plugin installed and configured correctly
✅ All expected features present (auto-merge, monitoring, autonomous fixing)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Health Check Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Success: 20
⚠️  Warnings: 1
❌ Errors: 0

⚡ Your amp setup is working but has minor issues.

Recommended action:
  amp update

When to run doctor

After installation to verify setup
When things aren't working as expected
Before asking for help (include output in issue)
After major system updates
Periodically to ensure health

Troubleshooting

Check the Log

If something goes wrong, check the log:

tail -f ~/.amp/.amp.log

Force Reinstall

If the amplifier installation is corrupted:

rm ~/.amp/.amp_ready
amp  # Will trigger full bootstrap

Complete Reinstall

To start from scratch:

rm -rf ~/.amp
amp  # Will re-clone and install everything

Common Issues

"Missing required tools"

Install the missing prerequisites:

git: https://git-scm.com/downloads
make: xcode-select --install (macOS) or via package manager (Linux)
python3: https://www.python.org/downloads/
uv: https://docs.astral.sh/uv/getting-started/installation/
claude: https://docs.anthropic.com/en/docs/claude-code/install

"Virtual environment not found"

The installation may have been interrupted:

rm ~/.amp/.amp_ready
amp  # Will retry installation

"Failed to pull updates"

Network issue or local changes in amplifier repo:

cd ~/.amp/main
git status  # Check for local changes
git reset --hard origin/main  # Reset to clean state

Uninstall

# Remove amp from shell configuration (keeps workspace data)
amp uninstall

# Remove amp AND all workspace data
amp uninstall --data

# View all options
amp uninstall --help

Platform Support

✅ macOS (bash & zsh)
✅ Linux (bash & zsh)
⏸️ Windows (not yet supported)

Documentation

Quick Reference - Essential commands and workflows
Plugins - Claude Code plugins and extensions
Migration Guide - Upgrading from pre-worktree versions
Changelog - Complete history of changes
Amplifier Docs - Amplifier development environment
Claude Code Docs - Claude Code documentation

Contributing

See the amplifier-setup repository for contribution guidelines.

License

This project is licensed under the MIT License.

Related Projects

Amplifier - The underlying development environment
Claude Code - Anthropic's AI coding assistant

Made with ❤️ to simplify amplifier setup

Name		Name	Last commit message	Last commit date
Latest commit History 90 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
ai_context/claude_code		ai_context/claude_code
assets		assets
docs		docs
plugins		plugins
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
MIGRATION.md		MIGRATION.md
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
WINDOWS_SUPPORT.md		WINDOWS_SUPPORT.md
amp-workspace.sh		amp-workspace.sh
amp.cmd		amp.cmd
amp.ps1		amp.ps1
amp.sh		amp.sh
changelog-slide.html		changelog-slide.html
doctor.sh		doctor.sh
install.ps1		install.ps1
install.sh		install.sh
presentation.html		presentation.html
reload-amp.sh		reload-amp.sh
uninstall.sh		uninstall.sh

kenotron-ms/amplifier-setup

Folders and files

Latest commit

History

Repository files navigation

Amplifier Setup (amp)

✨ What's New (December 2025)

Quick Start

One-Time Installation

Windows

Mac / Linux

Everyday Use

What is amp?

The Problem

The Solution

Detailed Installation

Prerequisites

Installation Options

Windows

Mac / Linux

Usage

Basic Usage

Creating New Projects

Workspace Management

Update

Uninstall

First Run

Subsequent Runs

How It Works

Workspace Pattern

File Structure

Configuration

Environment Variables

Update Frequency

Health Check (amp doctor)

Mac / Linux

What it checks

Sample Output

When to run doctor

Troubleshooting

Check the Log

Force Reinstall

Complete Reinstall

Common Issues

"Missing required tools"

"Virtual environment not found"

"Failed to pull updates"

Uninstall

Platform Support

Documentation

Contributing

License

Related Projects

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Amplifier Setup (`amp`)

What is `amp`?

Health Check (`amp doctor`)

Packages