Amp SDK

# Install the Amp SDK using npm
npm install @ampcode/sdk

# or yarn
yarn add @ampcode/sdk

# Install or upgrade the Amp CLI used by the SDK (optional if a compatible version is already installed)
npx -y @ampcode/sdk install

npm install @ampcode/sdk@0.1.0-20260528044221-ge0e19fa

import { execute } from '@ampcode/sdk'

// Simple execution - get the final result
for await (const message of execute({ prompt: 'What files are in this directory?' })) {
	if (message.type === 'result' && !message.is_error) {
		console.log('Result:', message.result)
		break
	}
}

for await (const message of execute({ prompt: 'Run tests' })) {
	if (message.type === 'system') {
		// Session info, available tools, MCP servers
		console.log('Available tools:', message.tools)
	} else if (message.type === 'assistant') {
		// AI responses and tool usage
		console.log('Assistant is working...')
	} else if (message.type === 'result') {
		console.log(message.is_error ? `Failed: ${message.error}` : `Done: ${message.result}`)
	}
}

async function getResult(prompt: string): Promise<string> {
	for await (const message of execute({ prompt, options: {} })) {
		if (message.type === 'result') {
			if (message.is_error) {
				throw new Error(message.error)
			}
			return message.result
		}
	}
	throw new Error('No result received')
}

// Usage
try {
	const result = await getResult('List all TypeScript files in this project')
	console.log('Found files:', result)
} catch (error) {
	console.error('Failed:', error instanceof Error ? error.message : String(error))
}

// Continue the most recent conversation
for await (const message of execute({
	prompt: 'What was the last error you found?',
	options: { continue: true },
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
	}
}

// Continue a specific thread by ID
for await (const message of execute({
	prompt: 'Can you update that code we discussed?',
	options: { continue: 'T-abc123-def456' },
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
	}
}

for await (const message of execute({
	prompt: 'Refactor the auth module',
	options: { cwd: './my-project' },
})) {
	// Process messages...
}

for await (const message of execute({
	prompt: 'Analyze this project',
	options: {
		logLevel: 'debug', // Shows CLI command in console
		logFile: './amp-debug.log', // Optional: write logs to file
	},
})) {
	// Process messages
}

for await (const message of execute({
	prompt: 'Quickly fix this typo',
	options: {
		mode: 'low', // Use low mode for faster responses
	},
})) {
	// Process messages
}

for await (const message of execute({
	prompt: 'Think carefully and explain your plan before coding.',
	options: {
		mode: 'medium',
		effort: 'high',
	},
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
		break
	}
}

for await (const message of execute({
	prompt: 'Summarize this repo',
	options: {
		labels: ['sdk', 'summary'],
	},
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
		break
	}
}

for await (const message of execute({
	prompt: 'Review pull request 42',
	options: {
		executor: 'orb',
		title: 'Review acme/widgets#42',
	},
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
		break
	}
}

for await (const message of execute({
	prompt: 'Analyze this private codebase',
	options: {
		visibility: 'private', // Visible only to you (and workspace admins if you're in a workspace)
	},
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
		break
	}
}

async function executeWithProgress(prompt: string) {
	console.log('Starting task...')

	for await (const message of execute({ prompt })) {
		if (message.type === 'system' && message.subtype === 'init') {
			console.log('Tools available:', message.tools.join(', '))
		} else if (message.type === 'assistant') {
			// Show tool usage or assistant responses
			for (const content of message.message.content) {
				if (content.type === 'tool_use') {
					console.log(`Using ${content.name}...`)
				} else if (content.type === 'text') {
					console.log('Assistant:', content.text.slice(0, 100) + '...')
				}
			}
		} else if (message.type === 'result') {
			if (message.is_error) {
				console.log('Failed:', message.error)
			} else {
				console.log('Completed successfully!')
				console.log(message.result)
			}
		}
	}
}

async function executeWithTimeout(prompt: string, timeoutMs = 30000) {
	const signal = AbortSignal.timeout(timeoutMs)

	try {
		for await (const message of execute({
			prompt,
			signal,
			options: {},
		})) {
			if (message.type === 'result') {
				if (message.is_error) {
					throw new Error(message.error)
				}
				return message.result
			}
		}
	} catch (error) {
		if (signal.aborted) {
			throw new Error(`Operation timed out after ${timeoutMs}ms`)
		}
		throw error
	}
}

import { execute, type MCPConfig } from '@ampcode/sdk'

const mcpConfig: MCPConfig = {
	playwright: {
		command: 'npx',
		args: ['-y', '@playwright/mcp@latest', '--headless'],
		env: { NODE_ENV: 'production' },
	},
	database: {
		command: 'node',
		args: ['./custom-mcp-server.js'],
		// ${VAR} placeholders are expanded from Amp's environment at server startup
		env: { DB_CONNECTION_STRING: '${DATABASE_URL}' },
	},
}

for await (const message of execute({
	prompt: 'Test the login flow on staging environment',
	options: { mcpConfig },
})) {
	if (message.type === 'system') {
		console.log(
			'MCP Servers:',
			message.mcp_servers.map((s) => `${s.name}: ${s.status}`),
		)
	}
	// Handle other messages...
}

import { execute, createUserMessage } from '@ampcode/sdk'

async function* generateMessages() {
	yield createUserMessage('Start analyzing the codebase')

	// Wait for some condition or user input
	await new Promise((resolve) => setTimeout(resolve, 1000))

	yield createUserMessage('Now focus on the authentication module')
}

for await (const message of execute({
	prompt: generateMessages(),
})) {
	if (message.type === 'result' && !message.is_error) {
		console.log(message.result)
	}
}

import { execute } from '@ampcode/sdk'

// Use a custom settings file
for await (const message of execute({
	prompt: 'Deploy the application',
	options: {
		settingsFile: './settings.json',
		logLevel: 'debug',
	},
})) {
	// Handle messages...
}

for await (const message of execute({
	prompt: 'Use my custom deployment skill',
	options: {
		skills: './my-skills', // Path to custom skills directory
	},
})) {
	// Process messages
}