Shadow Workspace¶

Work safely with AI-generated changes using a shadow copy of your project.

Overview¶

A shadow workspace lets you:

Review AI changes before they touch your real code
Test in isolation without risk to your project
Compare diffs between original and modified
Rollback easily if something goes wrong

The Problem¶

When Amplifier writes code, it modifies files directly. This can be risky:

Changes might break things
Hard to see what changed
Difficult to undo

The Solution¶

Work in a shadow copy:

my-project/           # Your real project (read-only to AI)
my-project-shadow/    # Shadow copy (AI writes here)

Setup Methods¶

Method 1: Manual Copy¶

# Create shadow workspace
cp -r my-project my-project-shadow
cd my-project-shadow

# Start Amplifier
amp

Method 2: Git Worktree¶

If your project uses git:

cd my-project

# Create worktree
git worktree add ../my-project-shadow -b ai-changes

# Work in shadow
cd ../my-project-shadow
amp

Benefits: - Shares git history - Easy to create PR - Clean branch management

Method 3: Amplifier Shadow CLI¶

Amplifier includes a dedicated amplifier-shadow CLI for creating and managing isolated shadow environments:

# Create a shadow environment with a local repo override
amplifier-shadow create --local ~/repos/amplifier-core:microsoft/amplifier-core --name my-test

# Run a command inside the shadow environment
amplifier-shadow exec my-test "command"

# Tear down the shadow environment
amplifier-shadow destroy my-test

The --local flag maps a local repo path to a package name, so the shadow environment installs your working copy instead of the published package. You can pass multiple --local flags to test changes across several repositories together.

Method 4: bkrabach's Shadow Script¶

From bkrabach's setup-tools:

# Install
curl -o ~/bin/shadow https://raw.githubusercontent.com/bkrabach/setup-tools/main/shadow.sh
chmod +x ~/bin/shadow

# Use
shadow my-project
# Creates my-project-shadow and cd's into it

Workflow¶

Step 1: Create Shadow¶

shadow my-project
# or
cp -r my-project my-project-shadow
cd my-project-shadow

Step 2: Work with Amplifier¶

amp

> Refactor the authentication module
> Add comprehensive tests
> Update the documentation

Step 3: Review Changes¶

# See what changed
diff -r ../my-project . --exclude=.git --exclude=node_modules

# Or with git
git diff
git status

Step 4: Accept or Reject¶

Accept changes:

# If using git worktree
git add .
git commit -m "AI-assisted refactoring"
git checkout main
git merge ai-changes

# If manual copy
cp -r . ../my-project

Reject changes:

# Just delete the shadow
cd ..
rm -rf my-project-shadow

Best Practices¶

Keep Shadow Fresh¶

Sync periodically:

cd my-project-shadow
rsync -av --exclude='.git' ../my-project/ .

Use Git Worktrees for Teams¶

# Create feature branch worktree
git worktree add ../feature-auth -b feature/auth-refactor

# Work with AI
cd ../feature-auth
amp

# Create PR when done
gh pr create

Exclude Large Directories¶

When copying:

rsync -av --exclude='node_modules' --exclude='.venv' \
  --exclude='dist' --exclude='build' \
  my-project/ my-project-shadow/

Multiple Shadows¶

For comparing approaches:

shadow my-project approach-a
shadow my-project approach-b

# Try different prompts in each
cd ../approach-a && amp
cd ../approach-b && amp

# Compare results
diff -r approach-a approach-b

Shadow Environment Agents¶

Amplifier provides two specialized agents for working with shadow environments programmatically, eliminating the need to manage the CLI manually.

shadow-operator¶

The shadow-operator agent creates and manages shadow environments on your behalf. Instead of running CLI commands yourself, you can ask the agent to set up an isolated environment, run tests, and report results.

Typical use: "Create a shadow environment with my local amplifier-core changes and run the test suite."

The agent handles the full lifecycle -- create, execute, and destroy -- so you do not need to remember CLI flags or clean up manually.

amplifier-smoke-test¶

The amplifier-smoke-test agent validates that a shadow environment is correctly configured for Amplifier development. It runs Amplifier-specific checks including:

Import validation: Verifies that amplifier_core imports (Session, Coordinator, etc.) resolve correctly
Provider configuration: Confirms provider installation and configuration
Bundle loading: Checks that bundles load and agents are available
CLI commands: Validates that Amplifier CLI commands execute successfully

Use amplifier-smoke-test after shadow-operator creates an environment to get an objective PASS/FAIL verdict with evidence before you start working in the shadow.

Typical Agent Workflow¶

Ask shadow-operator to create a shadow with your local changes
Ask amplifier-smoke-test to validate the environment
Work in the validated shadow environment
Ask shadow-operator to destroy the environment when finished

When to Use Shadow Environments¶

Shadow environments add overhead. Use them when the situation warrants isolation:

Changes touch cross-repo dependencies. If your change spans amplifier-core and amplifier-foundation (or other repos), a shadow lets you test them together without polluting either local checkout.
You need clean install testing. Your local environment accumulates state -- editable installs, cached builds, modified configs. A shadow starts from a clean slate.
Your local environment could influence results. Environment variables, locally patched files, or development-only config can mask bugs. Shadows eliminate that noise.
Testing could disrupt your local environment. Destructive tests, database migrations, or config changes that you do not want in your working checkout belong in a shadow.
You need to isolate context from local overrides. Workspace-level .amplifier/ config, local skills, or project-specific bundles can change behavior. A shadow gives you a controlled baseline.

If none of these apply -- for example, you are editing a single file in a single repo -- a shadow is unnecessary. Use your normal working directory.

Shadow Script¶

Create ~/bin/shadow:

#!/bin/bash
# Shadow workspace creator

if [ -z "$1" ]; then
  echo "Usage: shadow <project-dir> [shadow-name]"
  exit 1
fi

PROJECT="$1"
SHADOW="${2:-$1-shadow}"

if [ -d "$SHADOW" ]; then
  echo "Shadow already exists: $SHADOW"
  cd "$SHADOW"
else
  echo "Creating shadow workspace: $SHADOW"

  if [ -d "$PROJECT/.git" ]; then
    # Use git worktree if possible
    cd "$PROJECT"
    git worktree add "../$SHADOW" -b "shadow-$(date +%Y%m%d-%H%M%S)"
    cd "../$SHADOW"
  else
    # Fall back to copy
    cp -r "$PROJECT" "$SHADOW"
    cd "$SHADOW"
  fi

  echo "Shadow workspace ready: $SHADOW"
fi

# Start shell in shadow
exec $SHELL

Try It Yourself¶

Exercise 1: Create Shadow¶

# Pick any project
shadow my-project

# Verify you're in shadow
pwd

Exercise 2: Make AI Changes¶

amp

> Add input validation to all API endpoints

Exercise 3: Review and Decide¶

# See changes
git diff

# Accept or reject

Troubleshooting¶

"Directory already exists"¶

rm -rf my-project-shadow
shadow my-project

Large Projects Take Too Long¶

Use rsync with exclusions:

rsync -av --exclude='node_modules' --exclude='.venv' \
  --progress my-project/ my-project-shadow/

Git Worktree Conflicts¶

# Clean up orphaned worktree
git worktree prune
git worktree list

Next¶

Learn about remote development options:

→ Remote Development