TypeScript SDK

Complete API reference for the Amp TypeScript SDK. This document provides detailed information about all functions, types, and interfaces.

Installation

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

# or yarn
yarn add @ampcode/sdk

# Optional: manually install the Amp CLI, already a dependency
npx -y @ampcode/sdk install

If you need to use Amp before Amp Neo, install the legacy SDK release @ampcode/sdk@0.1.0-20260528044221-ge0e19fa:

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

Functions

execute()

The main function for executing Amp CLI commands programmatically.

function execute(options: ExecuteOptions): AsyncIterable<StreamMessage>

Parameters

• options (ExecuteOptions) - Configuration for the execution

Returns

• AsyncIterable<StreamMessage> - Stream of messages from the Amp CLI

Example

import { execute } from '@ampcode/sdk'

for await (const message of execute({
	prompt: 'Analyze this codebase',
	options: {
		cwd: './my-project',
	},
})) {
	if (message.type === 'assistant') {
		console.log('Assistant:', message.message.content)
	} else if (message.type === 'result' && !message.is_error) {
		console.log('Final result:', message.result)
		break
	}
}

createUserMessage()

Helper function to create properly formatted user input messages for streaming conversations.

function createUserMessage(text: string, options?: { requestId?: string }): UserInputMessage

Parameters

• text (string) - The text content for the user message
• options.requestId (string, optional) - A 1–256 character ID. Reusing it for a retry on the same thread prevents Amp from creating another user message.

Returns

• UserInputMessage - A formatted user input message

Example

import { createUserMessage } from '@ampcode/sdk'

const message = createUserMessage('Analyze this code', { requestId: 'analysis-123' })
console.log(message)
// Output: { type: 'user', requestId: 'analysis-123', message: { role: 'user', content: [{ type: 'text', text: 'Analyze this code' }] } }

createPermission()

Helper function to create permissions plugin rule objects for controlling tool usage.

function createPermission(
	tool: string,
	action: 'allow' | 'reject' | 'ask' | 'delegate',
	options?: {
		matches?: Record<string, PermissionMatchCondition>
		context?: 'thread' | 'subagent'
		to?: string
	},
): Permission

Parameters

• tool (string) - The name of the tool to which this permission applies (supports glob patterns)
• action ('allow' | 'reject' | 'ask' | 'delegate') - How Amp should proceed when matched
• options (object, optional) - Additional configuration for the permission
  • matches (Record<string, PermissionMatchCondition>) - Match conditions for tool arguments
  • context ('thread' | 'subagent') - Only apply this rule in specific context
  • to (string) - Command to delegate to (required when action is 'delegate')

Returns

• Permission - A permission object that can be used in the permissions array

Examples

import { createPermission } from '@ampcode/sdk'

// Allow all Bash commands
createPermission('Bash', 'allow')

// Allow specific git commands
createPermission('Bash', 'allow', {
	matches: { cmd: 'git *' },
})

// Ask for approval on Read operations for sensitive paths
createPermission('Read', 'ask', {
	matches: { path: '/etc/*' },
})

// Delegate web browsing to a custom command
createPermission('mcp__playwright__*', 'delegate', {
	to: 'node browse.js',
})

// Only apply in subagent context
createPermission('Bash', 'reject', {
	context: 'subagent',
})

threads.new()

Create a new empty thread and return its ID.

async function threads.new(options?: ThreadsNewOptions): Promise<string>

Parameters

• options (ThreadsNewOptions, optional) - Configuration for the new thread

Returns

• Promise<string> - The thread ID

Example

import { threads } from '@ampcode/sdk'

// Create a new private thread
const threadId = await threads.new({ visibility: 'private' })
console.log('Created thread:', threadId)

threads.markdown()

Get a thread rendered as markdown.

async function threads.markdown(options: ThreadsMarkdownOptions): Promise<string>

Parameters

• options (ThreadsMarkdownOptions) - Options containing the thread ID

Returns

• Promise<string> - The thread content as markdown

Example

import { threads } from '@ampcode/sdk'

// Get thread content as markdown
const markdown = await threads.markdown({ threadId: 'T-abc123-def456' })
console.log(markdown)

threads.setMultiplayer()

Open or close a thread for contributions (multiplayer). Only works on orb threads with shared (non-private) visibility, and only for the thread owner.

async function threads.setMultiplayer(options: ThreadsSetMultiplayerOptions): Promise<void>

Parameters

• options (ThreadsSetMultiplayerOptions) - The thread ID, enabled flag, and optional open-window duration

Returns

• Promise<void>

Example

import { threads } from '@ampcode/sdk'

// Open a thread for contributions for the default duration (currently 1 week)
await threads.setMultiplayer({ threadId: 'T-abc123-def456' })

// Open a thread for contributions for 12 hours
await threads.setMultiplayer({ threadId: 'T-abc123-def456', hours: 12 })

// Close a thread for contributions
await threads.setMultiplayer({ threadId: 'T-abc123-def456', enabled: false })

Types

ExecuteOptions

Configuration options for the execute() function.

interface ExecuteOptions {
	prompt: string | AsyncIterable<UserInputMessage>
	options?: AmpOptions
	signal?: AbortSignal
}

Properties

AmpOptions

Configuration options that map to Amp CLI flags.

interface AmpOptions {
	cwd?: string
	mode?: string // Prefer 'low', 'medium', 'high', or 'ultra'
	effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
	dangerouslyAllowAll?: boolean
	noArchiveAfterExecute?: boolean
	visibility?: 'private' | 'unlisted' | 'workspace' | 'group'
	settingsFile?: string
	logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'audit'
	logFile?: string
	mcpConfig?: string | MCPConfig
	env?: Record<string, string>
	continue?: boolean | string
	skills?: string
	enabledTools?: string[]
	permissions?: Permission[]
	labels?: string[]
	thinking?: boolean
	executor?: 'local' | 'orb'
	project?: string
	title?: string
}

The built-in modes are 'low', 'medium', 'high', and 'ultra'. You can also pass a string for a custom plugin-defined mode.

executor defaults to local execution. With executor: 'orb', prompt must be a string rather than streaming input. project requires orb execution; when it is omitted, Amp may infer a project from the Git remotes under cwd, or start the orb without a repository if none match. The orb executor ignores local-only options (permissions, enabledTools, skills, mcpConfig, and dangerouslyAllowAll) with a warning; configure those in the Amp project instead.

Properties

Message Types

The SDK streams various message types during execution. All messages implement the base StreamMessage type.

SystemMessage

Initial message containing session information and available tools.

interface SystemMessage {
	type: 'system'
	subtype: 'init'
	session_id: string
	cwd: string
	tools: string[]
	mcp_servers: Array<{
		name: string
		status:
			| 'awaiting-approval'
			| 'authenticating'
			| 'connecting'
			| 'reconnecting'
			| 'connected'
			| 'denied'
			| 'failed'
			| 'blocked-by-registry'
	}>
}

Properties

AssistantMessage

AI assistant responses with text content and tool usage.

interface AssistantMessage {
	type: 'assistant'
	session_id: string
	message: {
		id: string
		type: 'message'
		role: 'assistant'
		model: string
		content: Array<TextContent | ToolUseContent>
		stop_reason: 'end_turn' | 'tool_use' | 'max_tokens' | null
		stop_sequence: string | null
		usage?: Usage
	}
	parent_tool_use_id: string | null
}

Properties

UserMessage

User input and tool results.

interface UserMessage {
	type: 'user'
	session_id: string
	message: {
		role: 'user'
		content: Array<TextContent | ToolResultContent>
	}
	parent_tool_use_id: string | null
}

Properties

ResultMessage

Final successful execution result.

interface ResultMessage {
	type: 'result'
	subtype: 'success'
	session_id: string
	is_error: false
	result: string
	duration_ms: number
	num_turns: number
	usage?: Usage
	permission_denials?: string[]
}

Properties

ErrorResultMessage

Final error result indicating execution failure.

interface ErrorResultMessage {
	type: 'result'
	subtype: 'error_during_execution' | 'error_max_turns'
	session_id: string
	is_error: true
	error: string
	duration_ms: number
	num_turns: number
	usage?: Usage
	permission_denials?: string[]
}

Properties

TextContent

Plain text content block.

interface TextContent {
	type: 'text'
	text: string
}

ToolUseContent

Tool execution request.

interface ToolUseContent {
	type: 'tool_use'
	id: string
	name: string
	input: Record<string, unknown>
}

ToolResultContent

Result from tool execution.

interface ToolResultContent {
	type: 'tool_result'
	tool_use_id: string
	content: string
	is_error: boolean
}

Usage

Token usage and billing information from API calls.

interface Usage {
	input_tokens: number
	cache_creation_input_tokens?: number
	cache_read_input_tokens?: number
	output_tokens: number
	service_tier?: string
}

Properties

Input Types

UserInputMessage

Formatted user input message for streaming conversations.

interface UserInputMessage {
	type: 'user'
	requestId?: string
	message: {
		role: 'user'
		content: Array<{
			type: 'text'
			text: string
		}>
	}
}

MCPConfig

Configuration for MCP (Model Context Protocol) servers. Supports both stdio-based and HTTP-based servers.

type MCPConfig = Record<string, MCPServer>

// MCPServer is a union of stdio and HTTP server configurations

MCPServer accepts either a stdio server config (with command) or an HTTP server config (with url):

const mcpConfig: MCPConfig = {
	playwright: { command: 'npx', args: ['-y', '@playwright/mcp'] },
	remote: { url: 'https://api.example.com/mcp' },
}

Stdio server properties:

HTTP server properties:

ThreadsNewOptions

Options for creating a new thread.

interface ThreadsNewOptions {
	visibility?: 'private' | 'unlisted' | 'workspace' | 'group'
}

Properties

ThreadsMarkdownOptions

Options for getting thread markdown.

interface ThreadsMarkdownOptions {
	threadId: string
}

Properties

ThreadsSetMultiplayerOptions

Options for opening or closing a thread for contributions (multiplayer). The duration options are summed; the total must be between 5 minutes and 7 days. When enabled is true and no duration is given, the server default (currently 1 week) is used. Duration options are not allowed when enabled is false.

interface ThreadsSetMultiplayerOptions {
	threadId: string
	enabled?: boolean
	minutes?: number
	hours?: number
	days?: number
	weeks?: number
}

Properties

Permission

Individual permissions plugin rule for controlling tool usage.

interface Permission {
	tool: string
	matches?: Record<string, PermissionMatchCondition>
	action: 'allow' | 'reject' | 'ask' | 'delegate'
	context?: 'thread' | 'subagent'
	to?: string
}

Properties

Example

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

for await (const message of execute({
	prompt: 'Deploy the application',
	options: {
		permissions: [
			// Allow git commands
			createPermission('Bash', 'allow', { matches: { cmd: 'git *' } }),
			// Allow reading files
			createPermission('Read', 'allow'),
		],
	},
})) {
	// Handle messages
}

PermissionMatchCondition

Match condition for tool arguments. Supports strings (with glob patterns or regex), arrays (OR logic), booleans, numbers, null, undefined, and nested objects.

type PermissionMatchCondition =
	| string
	| PermissionMatchCondition[]
	| { [key: string]: PermissionMatchCondition }
	| boolean
	| number
	| null
	| undefined

Examples

// String pattern with wildcard
{
	cmd: 'npm *'
}

// Array for OR logic
{
	cmd: ['npm install', 'npm test', 'npm run build']
}

// Regex pattern
{
	cmd: '/^git (status|log|diff)$/'
}

// Nested object matching
{
	env: {
		NODE_ENV: 'production'
	}
}

Requirements

• Node.js 18 or higher