Amp by Sourcegraph

Relevant source files

• Amp/README.md
• Amp/claude-4-sonnet.yaml
• Amp/gpt-5.yaml
• Amp/view-thread-yaml.png

This document covers Amp, a multi-LLM AI coding agent built by Sourcegraph. Amp is an IDE-integrated assistant available in VSCode that features dual LLM configurations (GPT-5 and Claude 4 Sonnet), an Oracle advisor powered by OpenAI's o3 reasoning model, a sub-agent delegation system, and the AGENTS.md convention for project-specific context. For other IDE-integrated assistants, see VSCode Agent, Windsurf Cascade, and Claude Code.

System Overview and LLM Configuration

Amp provides two distinct system prompt configurations optimized for different language models. Users can switch between configurations via VSCode settings to access model-specific optimizations.

Dual Configuration Architecture

Configuration	File	Model Target	Key Optimizations
GPT-5	Amp/gpt-5.yaml1-1920	gpt-5	Minimal reasoning emphasis, strict concision rules
Claude 4 Sonnet	Amp/claude-4-sonnet.yaml1-1920	Claude 4 Sonnet	4-line response limit, detailed communication guidelines

To enable the GPT-5 configuration, users must set VSCode user settings:

Core Identity and Agency

Both configurations define Amp as "a powerful AI coding agent built by Sourcegraph" Amp/gpt-5.yaml10-12 Amp/claude-4-sonnet.yaml5-7 The system operates under three agency principles:

1. End-to-end execution - Fully resolve user requests, keep working through problems until complete solution is reached
2. Balance initiative with restraint - If user asks for a plan, provide a plan; don't immediately edit files
3. Minimal explanation - After edits, stop; do not add explanations unless asked

Sources: Amp/gpt-5.yaml10-29 Amp/claude-4-sonnet.yaml1-33 Amp/README.md13-20

Environment Context

Amp receives detailed environment information including working directory, workspace root, operating system details, repository URL, and Amp thread URL Amp/gpt-5.yaml516-610 Amp/claude-4-sonnet.yaml755-852 A cached directory listing provides immediate workspace structure awareness without additional tool calls.

Sources: Amp/gpt-5.yaml516-610 Amp/claude-4-sonnet.yaml755-852

Oracle AI Advisor Architecture

The Oracle is a senior engineering advisor tool powered by OpenAI's o3 reasoning model. It provides expert guidance for planning, code reviews, debugging, and architectural decisions.

Oracle Tool Capabilities

The Oracle operates with a restricted tool subset focused on read-only analysis:

Tool	Purpose
list_directory	Directory exploration
Read	File content reading
Grep	Exact pattern searching
glob	File pattern matching
web_search	External information retrieval
read_web_page	Web documentation access

When to Use Oracle

The GPT-5 configuration provides explicit decision logic Amp/gpt-5.yaml223-232:

• Use Oracle for: "I need a senior engineer to think with me"
• Use Codebase Search Agent for: "I need to find code that matches a concept"
• Use Task Tool for: "I know what to do, need large multi-step execution"

Specific use cases include:

1. Code Reviews - Architecture feedback and quality analysis Amp/gpt-5.yaml261-263
2. Complex Debugging - Multi-file bug investigation Amp/claude-4-sonnet.yaml241-248
3. Planning - Complex implementation or refactoring strategy Amp/gpt-5.yaml259-260
4. Performance Analysis - Deep performance debugging Amp/gpt-5.yaml262

Sources: Amp/gpt-5.yaml223-270 Amp/claude-4-sonnet.yaml211-297

Oracle Prompting Guidelines

The system instructs users to be explicit when invoking Oracle Amp/claude-4-sonnet.yaml223-226:

• Mention to user why Oracle is invoked
• Use language like "I'm going to ask the oracle for advice" or "I need to consult with the oracle"
• Provide precise problem description with attached files
• Request concrete outcomes and trade-off analysis

Sources: Amp/gpt-5.yaml254-269 Amp/claude-4-sonnet.yaml223-226

Sub-agent Delegation and Task Tool

Amp implements a three-tier sub-agent system for delegating specialized work. Each sub-agent has distinct responsibilities and tool access patterns.

Sub-agent Types

Sub-agent	Purpose	When to Use	Tool Access
Task Tool	Fire-and-forget executor	Feature scaffolding, cross-layer refactors, mass migrations, boilerplate generation	Full tool suite
Oracle	Senior engineering advisor	Reviews, architecture, deep debugging, planning	list_directory, Read, Grep, glob, web_search, read_web_page
Codebase Search Agent	Smart code explorer	Mapping features, tracking capabilities, finding side-effects	list_directory, Grep, glob, Read

Task Tool Workflow

The Task Tool is described as "a productive junior engineer who can't ask follow-ups once started" Amp/gpt-5.yaml237-240 Prompting requirements include:

1. Detailed instructions on the goal
2. Enumerated deliverables
3. Step-by-step procedures
4. Validation methods
5. Constraints (e.g., coding style)
6. Relevant context snippets or examples

Don't use Task Tool for: Exploratory work, architectural decisions, debugging analysis Amp/gpt-5.yaml245-246

Codebase Search Agent Workflow

The Codebase Search Agent locates logic based on conceptual descriptions across languages and layers Amp/gpt-5.yaml274-276 Prompting guidelines:

• Describe real-world behavior being tracked
• Give hints with keywords, file types, or directories
• Specify desired output format
• Make query clear about completion criteria

Don't use Codebase Search Agent for: Code changes, design advice, simple exact text searches Amp/gpt-5.yaml281-282

Sources: Amp/gpt-5.yaml220-298 Amp/claude-4-sonnet.yaml41-47

Parallel Sub-agent Execution

Amp defaults to parallel execution for independent sub-agents Amp/gpt-5.yaml75-94:

• Parallelize: Codebase Search agents (different concepts/paths), Oracle calls (distinct concerns), Task executors (disjoint write targets)
• Serialize: Plan → Code dependencies, write conflicts (same files or shared contracts), chained transforms

Example of good parallelization: Oracle(plan-API), codebase_search_agent("validation flow"), codebase_search_agent("timeout handling"), Task(add-UI), Task(add-logs) — all disjoint paths Amp/gpt-5.yaml111-113

Sources: Amp/gpt-5.yaml72-121 Amp/claude-4-sonnet.yaml60-62

Task Planning and Todo System

Amp provides todo_write and todo_read tools for task tracking and planning. The system emphasizes frequent use to prevent forgetting important tasks.

Todo Tool Usage Patterns

Both configurations mandate frequent todo tool usage:

• GPT-5: "MARK todos as completed as soon as you are done with a task. Do not batch up multiple tasks before marking them as completed." Amp/gpt-5.yaml176-177
• Claude: "It is critical that you mark todos as completed as soon as you are done with a task. Do not batch up multiple tasks before marking them as completed." Amp/claude-4-sonnet.yaml315-317

Todo Workflow

The standard workflow follows this pattern Amp/gpt-5.yaml180-218:

1. Initial Planning - Use todo_write to create task list
2. Mark In Progress - Mark current todo as in_progress
3. Complete Task - Perform the work
4. Mark Completed - Immediately mark todo as completed
5. Move to Next - Repeat for next todo

Complex Task Planning

For complex tasks requiring deep analysis, the recommended workflow is:

1. Use Oracle for planning guidance Amp/claude-4-sonnet.yaml42-44
2. Use todo_write to break down plan into steps
3. Use Codebase Search Agent to validate scope
4. Use Task Tool to execute individual steps

Sources: Amp/gpt-5.yaml160-218 Amp/claude-4-sonnet.yaml301-399

Todo Integration with Verification

After completing tasks, Amp must run get_diagnostics and lint/typecheck commands Amp/claude-4-sonnet.yaml50-57 If commands are unknown, the system should:

1. Ask user for the command
2. Suggest writing it to AGENTS.md
3. Update todo list when validation passes

Sources: Amp/claude-4-sonnet.yaml50-57 Amp/gpt-5.yaml133-136

AGENTS.md Convention and Ground Truth

The AGENTS.md file (or legacy AGENT.md variant) serves as automatically-loaded project context that documents common commands, code style preferences, and project structure.

Auto-Context Loading

Both configurations automatically add AGENTS.md to the assistant's context Amp/gpt-5.yaml300-313 Amp/claude-4-sonnet.yaml457-471 The file provides:

1. Common Commands - Typecheck, lint, build, test commands Amp/gpt-5.yaml305
2. Code Style Preferences - Naming conventions, formatting rules Amp/gpt-5.yaml306
3. Project Structure - Overall architecture and organization Amp/gpt-5.yaml307

Ground Truth Principle

AGENTS.md is treated as "ground truth" for commands, style, and structure Amp/gpt-5.yaml416-417 Amp/claude-4-sonnet.yaml457-467 When Amp discovers recurring commands or conventions not documented in AGENTS.md, it should ask the user whether to append them for future runs Amp/gpt-5.yaml312-313

Integration with Verification Gates

The verification gate workflow explicitly references AGENTS.md for command discovery Amp/gpt-5.yaml336-338:

"Use commands from AGENTS.md or neighbors; if unknown, search the repo."

If commands cannot be found, Amp suggests writing them to AGENTS.md for future use Amp/claude-4-sonnet.yaml54-56

Sources: Amp/gpt-5.yaml300-420 Amp/claude-4-sonnet.yaml457-471

Guardrails and Quality Standards

Amp enforces strict guardrails to maintain code quality and prevent over-engineering. These rules apply before any action is taken.

Core Guardrails

The GPT-5 configuration lists four primary guardrails under "Read this before doing anything" Amp/gpt-5.yaml31-44:

Guardrail	Description	Example
Simple-first	Prefer smallest, local fix over cross-file "architecture change"	Add guard clause instead of refactoring error handling system
Reuse-first	Search for existing patterns; mirror naming, error handling, I/O, typing, tests	Use existing UserRepository pattern when adding OrderRepository
No surprise edits	If changes affect >3 files or multiple subsystems, show short plan first	Multi-file refactor requires plan before execution
No new deps	No new dependencies without explicit user approval	Must ask before adding new npm package

Quality Bar for Code

The quality standards emphasize consistency and minimalism Amp/gpt-5.yaml316-329:

• Match style - Follow style of recent code in same subsystem
• Small, cohesive diffs - Prefer single file if viable
• Strong typing - Explicit error paths, predictable I/O
• No suppressions - No as any or linter suppression unless explicitly requested
• Minimal tests - Add/adjust minimal tests if adjacent coverage exists; follow patterns
• Reuse interfaces - Don't duplicate existing schemas

Verification Gates

Mandatory verification follows a strict order Amp/gpt-5.yaml332-343:

Typecheck → Lint → Tests → Build

For each gate:

1. Use commands from AGENTS.md or search repo if unknown
2. Report evidence concisely (counts, pass/fail)
3. If unrelated pre-existing failures block progress, say so and scope the change

Sources: Amp/gpt-5.yaml31-343 Amp/claude-4-sonnet.yaml403-452

Over-Engineering Prevention

Additional guidelines prevent unnecessary complexity Amp/gpt-5.yaml405-411:

• Local guard > cross-layer refactor - Add simple guard instead of refactoring entire layer
• Single-purpose util > new abstraction layer - Create specific utility instead of new abstraction
• Don't introduce patterns not used by this repo - Follow existing patterns only

Security and Convention Rules

The Claude configuration adds security-focused rules Amp/claude-4-sonnet.yaml410-452:

• Always use absolute file paths, not relative paths
• Never assume library availability - check package.json/cargo.toml first
• Look at existing components for framework choice, naming, typing conventions
• Never introduce code that exposes or logs secrets
• Handle redaction markers [REDACTED:amp-token] carefully - don't overwrite with marker
• Never use background processes with & operator

Sources: Amp/gpt-5.yaml405-411 Amp/claude-4-sonnet.yaml403-452