sandbox-agent/research/agents/amp.md

Amp Research

Research notes on Sourcegraph Amp's configuration, credential discovery, and runtime behavior.

Overview

• Provider: Anthropic (via Sourcegraph)
• Execution Method: CLI subprocess (amp command)
• Session Persistence: Session ID (string)
• SDK: @sourcegraph/amp-sdk (closed source)
• Binary Location: /usr/local/bin/amp

CLI Usage

Interactive Mode

amp "your prompt here"
amp --model claude-sonnet-4 "your prompt"

Non-Interactive Mode

amp --print --output-format stream-json "your prompt"
amp --print --output-format stream-json --dangerously-skip-permissions "prompt"
amp --continue SESSION_ID "follow up"

Custom Args (CLI Flags)

Core Flags

Flag	Type	Description
--print	bool	Output mode (non-interactive)
--execute	bool	Alternative output mode (some versions)
--output-format stream-json	string	JSONL streaming output
--model MODEL	string	Specify model to use
--continue SESSION_ID	string	Resume existing session

Permission Flags

Flag	Type	Description
--dangerously-skip-permissions	bool	Skip all permission prompts

Configuration Flags

Flag	Type	Description
--toolbox NAME	string	Toolbox configuration to use
--mcp-config FILE	path	Path to MCP configuration file

Note: Amp CLI flags vary by version. The daemon uses flag detection (amp --help) to determine which flags are supported before invocation.

Credential Discovery

Priority Order

1. Environment variable: ANTHROPIC_API_KEY
2. Sourcegraph authentication
3. Claude Code credentials (shared)

Config File Locations

Path	Description
~/.amp/config.json	Primary config
~/.claude/.credentials.json	Shared with Claude Code

Amp can use Claude Code's OAuth credentials as fallback.

Streaming Response Format

Amp outputs newline-delimited JSON events:

{"type": "system", "subtype": "init", "session_id": "...", "tools": [...]}
{"type": "assistant", "message": {...}, "session_id": "..."}
{"type": "user", "message": {...}, "session_id": "..."}
{"type": "result", "subtype": "success", "result": "...", "session_id": "..."}

Event Types

Type	Description
system	System initialization with tools list
assistant	Assistant message with content blocks
user	User message (tool results)
result	Final result with session ID

Content Block Types

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
  | { type: "thinking"; thinking: string }
  | { type: "redacted_thinking"; data: string };

Response Schema

interface AmpResultMessage {
  type: "result";
  subtype: "success";
  duration_ms: number;
  is_error: boolean;
  num_turns: number;
  result: string;
  session_id: string;
}

Session Management

• Session ID captured from streaming events
• Use --continue SESSION_ID to resume
• Sessions stored internally by Amp CLI

Agent Modes vs Permission Modes

Permission Modes (Declarative Rules)

Amp uses declarative permission rules configured before execution:

interface PermissionRule {
  tool: string;  // Glob pattern: "Bash", "mcp__playwright__*"
  matches?: { [argumentName: string]: string | string[] | boolean };
  action: "allow" | "reject" | "ask" | "delegate";
  context?: "thread" | "subagent";
}

Action	Behavior
allow	Automatically permit
reject	Automatically deny
ask	Prompt user (CLI handles internally)
delegate	Delegate to subagent context

Example Rules

const permissions: PermissionRule[] = [
  { tool: "Read", action: "allow" },
  { tool: "Bash", matches: { command: "git *" }, action: "allow" },
  { tool: "Write", action: "ask" },
  { tool: "mcp__*", action: "reject" }
];

Agent Modes

No documented agent mode concept. Behavior controlled via:

• --toolbox flag for different tool configurations
• Permission rules for feature coverage restrictions

Bypass All Permissions

amp --dangerously-skip-permissions "prompt"

Or via SDK:

execute(prompt, { dangerouslyAllowAll: true });

Human-in-the-Loop

No Interactive HITL API

While permission rules support "ask" action, Amp does not expose an SDK-level API for programmatically responding to permission requests. The CLI handles user interaction internally.

For universal API integration, Amp should be run with:

• Pre-configured permission rules, or
• dangerouslyAllowAll: true to bypass

SDK Usage

import { execute, type AmpOptions } from '@sourcegraph/amp-sdk';

interface AmpOptions {
  cwd?: string;
  dangerouslyAllowAll?: boolean;
  toolbox?: string;
  mcpConfig?: MCPConfig;
  permissions?: PermissionRule[];
  continue?: boolean | string;
}

const result = await execute(prompt, options);

Installation

# Get latest version
VERSION=$(curl -s https://storage.googleapis.com/amp-public-assets-prod-0/cli/cli-version.txt)

# Linux x64
curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-linux-x64" \
  -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp

# Linux ARM64
curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-linux-arm64" \
  -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp

# macOS ARM64
curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-darwin-arm64" \
  -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp

# macOS x64
curl -fsSL "https://storage.googleapis.com/amp-public-assets-prod-0/cli/${VERSION}/amp-darwin-x64" \
  -o /usr/local/bin/amp && chmod +x /usr/local/bin/amp

Timeout

• Default timeout: 5 minutes (300,000 ms)
• Process killed with SIGTERM on timeout

Notes

• Amp is similar to Claude Code (same streaming format)
• Can share credentials with Claude Code
• No interactive HITL - must use pre-configured permissions
• SDK is closed source but types are documented
• MCP server integration supported via mcpConfig