Amplifier: Metacognitive AI Development

"Automate complex workflows by describing how you think through them."

Caution

This project is a research demonstrator. It is in early development and may change significantly. Using permissive AI tools in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk. See Disclaimer.

Amplifier is a coordinated and accelerated development system that turns your expertise into reusable AI tools without requiring code. Describe the step-by-step thinking process for handling a task—a "metacognitive recipe"—and Amplifier builds a tool that executes it reliably. As you create more tools, they combine and build on each other, transforming individual solutions into a compounding automation system.

🚀 QuickStart

Prerequisites Guide

Click to expand prerequisite instructions

1. Check if prerequisites are already met.

   • python3 --version  # Need 3.11+

   • uv --version       # Need any version

   • node --version     # Need any version

   • pnpm --version     # Need any version

   • git --version      # Need any version

2. Install what is missing.

   Mac

   brew install python3 node git pnpm uv

   Ubuntu/Debian/WSL

   # System packages
   sudo apt update && sudo apt install -y python3 python3-pip nodejs npm git
   
   # pnpm
   npm install -g pnpm
   pnpm setup && source ~/.bashrc
   
   # uv (Python package manager)
   curl -LsSf https://astral.sh/uv/install.sh | sh

   Windows

   1. Install WSL2
   2. Run Ubuntu commands above inside WSL

   Manual Downloads

   • Python (3.11 or newer)
   • Node.js (any recent version)
   • pnpm (package manager)
   • Git (any version)
   • uv (Python package manager)

Platform Note: Development and testing has primarily been done in Windows WSL2. macOS and Linux should work but have received less testing. Your mileage may vary.

Setup

# Clone Amplifier repository
git clone https://github.com/microsoft/amplifier.git amplifier
cd amplifier

# Install dependencies
make install

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac/WSL
# .venv\Scripts\Activate.ps1  # Windows PowerShell

Get Started

# Start with the unified CLI (recommended)
./amplify.py

# Or start Claude Code directly
claude

Create your first tool in 5 steps:

1. Identify a task you want to automate (e.g., "weekly learning digest")

   Need ideas? Try This:

   /ultrathink-task I'm new to "metacognitive recipes". What are some useful
   tools I could create with Amplifier that show how recipes can self-evaluate
   and improve via feedback loops? Just brainstorm ideas, don't build them yet.
   

2. Describe the thinking process - How would an expert handle it step-by-step?

   Need help? Try This:

   /ultrathink-task This is my idea: <your idea here>. Can you help me describe the
   thinking process to handle it step-by-step?
   

   Example of a metacognitive recipe:

   I want to create a tool called "Research Synthesizer". Goal: help me research a topic by finding sources, extracting key themes, then asking me to choose which themes to explore in depth, and finally producing a summarized report.
   
   Steps:
   
   1. Do a preliminary web research on the topic and collect notes.
   2. Extract the broad themes from the notes.
   3. Present me the list of themes and highlight the top 2-3 you recommend focusing on (with reasons).
   4. Allow me to refine or add to that theme list.
   5. Do in-depth research on the refined list of themes.
   6. Draft a report based on the deep research, ensuring the report stays within my requested length and style.
   7. Offer the draft for my review and incorporate any feedback.

3. Generate with /ultrathink-task - Let Amplifier build the tool

   /ultrathink-task <your metacognitive recipe here>
   

4. Refine through feedback - "Make connections more insightful"

   Let's see how it works. Run <your generated tool>.
   

   Then:

   • Observe and note issues.
   • Provide feedback in context.
   • Iterate until satisfied.

Learn more with Create Your Own Tools - Deep dive into the process.

---

📖 How to Use Amplifier

Choosing Your Backend

Amplifier supports two AI backends:

Claude Code (VS Code Extension):

• Native VS Code integration
• Automatic hooks for session management
• Slash commands for common tasks
• Best for: VS Code users, GUI-based workflows

Codex (CLI):

• Standalone command-line interface
• MCP servers for extensibility
• Scriptable and automatable
• Best for: Terminal users, CI/CD, automation

Using the Unified CLI (Recommended)

The unified CLI provides a consistent interface for both backends:

# Start with default backend (Claude Code)
./amplify.py

# Start with specific backend
./amplify.py --backend codex

# Start Codex with specific profile
./amplify.py --backend codex --profile review

# List available backends
./amplify.py --list-backends

# Show backend information
./amplify.py --info codex

Using Claude Code

# Set backend (optional, this is the default)
export AMPLIFIER_BACKEND=claude

# Start Claude Code normally
claude

Using Codex

# Set backend
export AMPLIFIER_BACKEND=codex

# Start Codex with Amplifier integration
./amplify-codex.sh

# Or with specific profile
./amplify-codex.sh --profile review

Environment Variables

• AMPLIFIER_BACKEND - Choose backend: "claude" or "codex" (default: claude)
• CODEX_PROFILE - Codex profile to use: "development", "ci", "review" (default: development)
• MEMORY_SYSTEM_ENABLED - Enable/disable memory system: "true" or "false" (default: true)

See .env.example for complete configuration options.

Unified CLI Reference

The ./amplify.py script provides a unified interface for both backends with the following options:

Backend Selection:

• --backend, -b - Choose backend: "claude" or "codex" (default: from config)
• --profile, -p - Codex profile: "development", "ci", "review" (default: development)

Configuration:

• --config - Path to configuration file (default: .env, overrides ENV_FILE)

Information:

• --list-backends - List available backends and exit
• --info [BACKEND] - Show information for specified backend (or current if not specified)
• --version, -v - Show version information and exit

Configuration Precedence:

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (.env by default, or specified by --config or ENV_FILE)
4. Auto-detection (if enabled)
5. Defaults (lowest priority)

Backward Compatibility

Legacy commands continue to work:

• claude - Direct Claude Code launch
• ./amplify-codex.sh - Codex wrapper script
• ./amplify.sh - Legacy wrapper script

Setup Your Project

# Clone Amplifier repository
git clone https://github.com/microsoft/amplifier.git amplifier

1. For existing GitHub projects

   # Add your project as a submodule
   cd amplifier
   git submodule add https://github.com/<your-username>/<your-project-name>.git my-project

2. For new projects

   # Create a new GitHub repository
   
   # Option 1: gh CLI
   gh repo create <your-username>/<your-project-name> --private
   
   # Option 2: Go to https://github.com/new

   # Initialize your new project
   git init my-project
   cd my-project/
   git remote add origin https://github.com/<your-username>/<your-project-name>.git
   echo "# My Project" > README.md
   git add .
   git commit -m "Initial commit"
   git push -u origin main
   
   # 2. Add as submodule
   cd ../amplifier
   git submodule add https://github.com/<your-username>/<your-project-name>.git my-project

# Install dependencies
make install

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac/WSL
# .venv\Scripts\Activate.ps1  # Windows PowerShell

# Set up project context & start Claude
echo "# Project-specific AI guidance" > my-project/AGENTS.md
claude

Tell Claude Code:

I'm working on @my-project/ with Amplifier.
Read @my-project/AGENTS.md for project context.
Let's use /ddd:1-plan to design the architecture.

Note

Why use this? Clean git history per component, independent Amplifier updates, persistent context across sessions, scalable to multiple projects. See Workspace Pattern for Serious Projects below for full details.

---

Codex Integration

Amplifier now provides comprehensive Codex CLI integration with 95% feature parity to Claude Code, including new task tracking and web research capabilities.

Key Features

• Task Tracking: TodoWrite-equivalent functionality for managing development tasks
• Web Research: WebFetch-equivalent for gathering information during development
• Enhanced Automation: Auto-quality checks, periodic transcript saves, and smart context detection
• Agent Context Bridge: Seamless context passing between main sessions and spawned agents
• MCP Server Architecture: Extensible tool system for custom integrations

Quick Start

Get started with Codex in 5 minutes: Quick Start Tutorial

Feature Comparison

See how Codex compares to Claude Code: Feature Parity Matrix

The amplify-codex.sh wrapper provides seamless integration with Codex CLI:

Features

• Automatic Session Management: Loads context at start, saves memories at end
• MCP Server Integration: Quality checks, transcript export, memory system
• Profile Support: Different configurations for development, CI, and review
• User Guidance: Clear instructions for available tools and workflows

Quick Start

# Make wrapper executable (first time only)
chmod +x amplify-codex.sh

# Start Codex with Amplifier
./amplify-codex.sh

# Follow the on-screen guidance to use MCP tools

Available MCP Tools

When using Codex, these tools are available:

• initialize_session - Load relevant memories from previous work
• check_code_quality - Run quality checks after editing files
• save_current_transcript - Export session transcript
• finalize_session - Extract and save memories before ending

See .codex/README.md for detailed documentation.

Manual Session Management

You can also run session management scripts manually:

# Initialize session with specific context
uv run python .codex/tools/session_init.py --prompt "Working on authentication"

# Clean up after session
uv run python .codex/tools/session_cleanup.py --session-id a1b2c3d4

Wrapper Options

# Use specific profile
./amplify-codex.sh --profile ci

# Skip initialization
./amplify-codex.sh --no-init

# Skip cleanup
./amplify-codex.sh --no-cleanup

# Show help
./amplify-codex.sh --help

Agent Conversion

Amplifier includes 25+ specialized agents that have been converted from Claude Code format to Codex format:

Converting Agents:

# Convert all agents from .claude/agents/ to .codex/agents/
make convert-agents

# Preview conversion without writing files
make convert-agents-dry-run

# Validate converted agents
make validate-codex-agents

Using Converted Agents:

# Automatic agent selection based on task
codex exec "Find and fix the authentication bug"
# Routes to bug-hunter agent

# Manual agent selection
codex exec --agent zen-architect "Design the caching layer"

# Programmatic usage
from amplifier import spawn_agent
result = spawn_agent("bug-hunter", "Investigate memory leak")

Available Agents:

• Architecture: zen-architect, database-architect, api-contract-designer
• Implementation: modular-builder, integration-specialist
• Quality: bug-hunter, test-coverage, security-guardian
• Analysis: analysis-engine, pattern-emergence, insight-synthesizer
• Knowledge: concept-extractor, knowledge-archaeologist, content-researcher
• Specialized: amplifier-cli-architect, performance-optimizer

See .codex/agents/README.md for complete agent documentation.

Backend Abstraction

Amplifier provides a unified API for working with both Claude Code and Codex backends through the backend abstraction layer.

Quick Start

from amplifier import get_backend

# Get backend (automatically selects based on AMPLIFIER_BACKEND env var)
backend = get_backend()

# Initialize session with memory loading
result = backend.initialize_session("Working on authentication")

# Run quality checks
result = backend.run_quality_checks(["src/auth.py"])

# Finalize session with memory extraction
messages = [{"role": "user", "content": "..."}]
result = backend.finalize_session(messages)

Backend Selection

Choose your backend via environment variable:

# Use Claude Code (default)
export AMPLIFIER_BACKEND=claude

# Use Codex
export AMPLIFIER_BACKEND=codex

# Auto-detect based on available CLIs
export AMPLIFIER_BACKEND_AUTO_DETECT=true

Agent Spawning

Spawn sub-agents with a unified API:

from amplifier import spawn_agent

result = spawn_agent(
    agent_name="bug-hunter",
    task="Find potential bugs in src/auth.py"
)
print(result['result'])

Available Operations

• Session Management: initialize_session(), finalize_session()
• Quality Checks: run_quality_checks()
• Transcript Export: export_transcript()
• Agent Spawning: spawn_agent()

Documentation

For detailed documentation, see:

• Backend Abstraction Guide
• Claude Code Integration
• Codex Integration

✨ Features To Try

🔧 Create Amplifier-powered Tools for Scenarios

Amplifier is designed so you can create new AI-powered tools just by describing how they should think. See the Create Your Own Tools guide for more information.

• Tell Claude Code: Walk me through creating my own scenario tool

• View the documentation: Scenario Creation Guide

🎨 Design Intelligence

Amplifier includes comprehensive design intelligence with 7 specialist agents, evidence-based design knowledge, and orchestrated design workflows:

• Tell Claude Code:

  /designer create a button component with hover states and accessibility

  Use the art-director agent to establish visual direction for my app

  Deploy component-designer to create a reusable card component

• Available Design Specialists:

  • animation-choreographer - Motion design and transitions
  • art-director - Aesthetic strategy and visual direction
  • component-designer - Component design and creation
  • design-system-architect - Design system architecture
  • layout-architect - Information architecture and layout
  • responsive-strategist - Device adaptation and responsive design
  • voice-strategist - Voice & tone for UI copy

• Design Framework:

  • 9 Dimensions - Purpose, hierarchy, color, typography, spacing, responsive, accessibility, motion, voice
  • 4 Layers - Foundational, structural, behavioral, experiential
  • Evidence-based - WCAG 2.1, color theory, animation principles, accessibility standards

• View the documentation: Design Intelligence

🤖 Explore Amplifier's agents on your code

Try out one of the specialized experts:

• Tell Claude Code:

  Use the zen-architect agent to design my application's caching layer

  Deploy bug-hunter to find why my login system is failing

  Have security-guardian review my API implementation for vulnerabilities

• View the files: Agents

📝 Document-Driven Development

Why use this? Eliminate doc drift and context poisoning. When docs lead and code follows, your specifications stay perfectly in sync with reality.

Execute a complete feature workflow with numbered slash commands:

/ddd:1-plan         # Design the feature
/ddd:2-docs         # Update all docs (iterate until approved)
/ddd:3-code-plan    # Plan code changes
/ddd:4-code         # Implement and test (iterate until working)
/ddd:5-finish       # Clean up and finalize

Each phase creates artifacts the next phase reads. You control all git operations with explicit authorization at every step. The workflow prevents expensive mistakes by catching design flaws before implementation.

• Tell Claude Code: /ddd:0-help

• View the documentation: Document-Driven Development Guide

🌳 Parallel Development

Why use this? Stop wondering "what if" — build multiple solutions simultaneously and pick the winner.

# Try different approaches in parallel
make worktree feature-jwt     # JWT authentication approach
make worktree feature-oauth   # OAuth approach in parallel

# Compare and choose
make worktree-list            # See all experiments
make worktree-rm feature-jwt  # Remove the one you don't want

Each worktree is completely isolated with its own branch, environment, and context.

See the Worktree Guide for advanced features, such as hiding worktrees from VSCode when not in use, adopting branches from other machines, and more.

• Tell Claude Code: What make worktree commands are available to me?

• View the documentation: Worktree Guide

📊 Enhanced Status Line

See costs, model, and session info at a glance:

Example: ~/repos/amplifier (main → origin) Opus 4.1 💰$4.67 ⏱18m

Shows:

• Current directory and git branch/status
• Model name with cost-tier coloring (red=high, yellow=medium, blue=low)
• Running session cost and duration

Enable with:

/statusline use the script at .claude/tools/statusline-example.sh

💬 Conversation Transcripts

Never lose context again. Amplifier automatically exports your entire conversation before compaction, preserving all the details that would otherwise be lost. When Claude Code compacts your conversation to stay within token limits, you can instantly restore the full history.

Automatic Export: A PreCompact hook captures your conversation before any compaction event:

• Saves complete transcript with all content types (messages, tool usage, thinking blocks)
• Timestamps and organizes transcripts in .data/transcripts/
• Works for both manual (/compact) and auto-compact events

Easy Restoration: Use the /transcripts command in Claude Code to restore your full conversation:

/transcripts  # Restores entire conversation history

The transcript system helps you:

• Continue complex work after compaction without losing details
• Review past decisions with full context
• Search through conversations to find specific discussions
• Export conversations for sharing or documentation

Transcript Commands (via Makefile):

make transcript-list                # List available transcripts
make transcript-search TERM="auth"  # Search past conversations
make transcript-restore             # Restore full lineage (for CLI use)

🏗️ Workspace Pattern for Serious Projects

For long-term development, consider using the workspace pattern where Amplifier hosts your project as a git submodule. This architectural approach provides:

• Clean boundaries - Project files stay in project directory, Amplifier stays pristine and updatable
• Version control isolation - Each component maintains independent git history
• Context persistence - AGENTS.md preserves project guidance across sessions
• Scalability - Work on multiple projects simultaneously without interference
• Philosophy alignment - Project-specific decision filters and architectural principles

Perfect for:

• Projects that will live for months or years
• Codebases with their own git repository
• Teams collaborating on shared projects
• When you want to update Amplifier without affecting your projects
• Working on multiple projects that need isolation

The pattern inverts the typical relationship: instead of your project containing Amplifier, Amplifier becomes a dedicated workspace that hosts your projects. Each project gets persistent context through AGENTS.md (AI guidance), philosophy documents (decision filters), and clear namespace boundaries using @project-name/ syntax.

• Tell Claude Code: What are the recommended workspace patterns for serious projects?

• View the documentation: Workspace Pattern Guide - complete setup, usage patterns, and migration from ai_working/.

💡 Best Practices & Tips

Want to get the most out of Amplifier? Check out The Amplifier Way for battle-tested strategies including:

• Understanding capability vs. context

• Decomposition strategies for complex tasks

• Using transcript tools to capture and improve workflows

• Demo-driven development patterns

• Practical tips for effective AI-assisted development

• Tell Claude Code: What are the best practices to get the MOST out of Amplifier?

• View the documentation: The Amplifier Way

⚙️ Development Commands

make check            # Format, lint, type-check
make test             # Run tests
make ai-context-files # Rebuild AI context

🧪 Testing & Benchmarks

Testing and benchmarking are critical to ensuring that any product leveraging AI, including Amplifier, is quantitatively measured for performance and reliability. Currently, we leverage terminal-bench to reproducibly benchmark Amplifier against other agents. Further details on how to run the benchmark can be found in tests/terminal_bench/README.md.

---

Tutorials

Amplifier provides comprehensive tutorials to help you master both Claude Code and Codex integrations:

Tutorial Index

• **Quick Start (5 min)** - Get started with Codex in 5 minutes
• **Beginner Guide (30 min)** - Complete Codex workflows walkthrough
• Workflow Diagrams - Visual guides to architecture and processes
• Feature Parity Matrix - Compare Codex vs Claude Code features
• Troubleshooting Tree - Decision-tree guide for common issues

Learning Paths

New to Amplifier:

1. Quick Start Tutorial (5 min)
2. Beginner Guide (30 min)

Migrating from Claude Code:

1. Feature Parity Matrix (20 min)
2. Workflow Diagrams (15 min)

CI/CD Integration:

1. Quick Start Tutorial (5 min)
2. Feature Parity Matrix (20 min) - Focus on CI sections

---

Project Structure

• amplify-codex.sh - Wrapper script for Codex CLI with Amplifier integration
• tools/convert_agents.py - Script to convert Claude Code agents to Codex format
• .codex/ - Codex configuration, MCP servers, and tools
  • config.toml - Codex configuration with MCP server definitions
  • mcp_servers/ - MCP server implementations (session, quality, transcripts)
  • tools/ - Session management scripts (init, cleanup, export)
  • README.md - Detailed Codex integration documentation
• .codex/agents/ - Converted agent definitions for Codex
  • README.md - Agent usage documentation
  • *.md - Individual agent definitions
• .claude/ - Claude Code configuration and hooks
  • README.md - Claude Code integration documentation
• amplifier/core/ - Backend abstraction layer with dual-backend support
  • backend.py - Core backend interface and implementations
  • agent_backend.py - Agent spawning abstraction
  • config.py - Backend configuration management
  • README.md - Detailed backend abstraction documentation

Both backends share the same amplifier modules (memory, extraction, etc.) for consistent functionality. See .codex/README.md and .claude/README.md for detailed backend-specific documentation.

---

Troubleshooting

Codex Issues

Wrapper script won't start:

• Ensure Codex CLI is installed: codex --version
• Check that .codex/config.toml exists
• Verify virtual environment: ls .venv/
• Check logs: cat .codex/logs/session_init.log

MCP servers not working:

• Verify server configuration in .codex/config.toml
• Check server logs: tail -f .codex/logs/*.log
• Ensure amplifier modules are importable: uv run python -c "import amplifier.memory"

Session management fails:

• Check MEMORY_SYSTEM_ENABLED environment variable
• Verify memory data directory exists: ls .data/memories/
• Run scripts manually with --verbose flag for debugging

---

Disclaimer

[!IMPORTANT] > This is an experimental system. We break things frequently.

• Not accepting contributions yet (but we plan to!)
• No stability guarantees
• Pin commits if you need consistency
• This is a learning resource, not production software
• No support provided - See SUPPORT.md

Contributing

Note

This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!

Working with Agents

Converting Agents: When Claude Code agents are updated, reconvert them:

make convert-agents
make validate-codex-agents

Testing Agent Conversion:

make test-agent-conversion

Creating New Agents:

1. Create agent in .claude/agents/ following existing patterns
2. Run conversion: make convert-agents
3. Review converted agent in .codex/agents/
4. Test with Codex: codex exec --agent <name> "<test-task>"

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.