TypeScript SDK

API reference for the Amp TypeScript SDK.

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' }] } }

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()

Turn multiplayer on or off. This only works for the owner of a shared thread that runs in an orb or on a shared runner.

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

Parameters

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

Returns

• Promise<void>

Example

import { threads } from '@ampcode/sdk'

// Enable multiplayer for the default duration (currently 1 week)
await threads.setMultiplayer({ threadId: 'T-abc123-def456' })

// Enable multiplayer for 12 hours
await threads.setMultiplayer({ threadId: 'T-abc123-def456', hours: 12 })

// Disable multiplayer
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'
	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[]
	labels?: string[]
	thinking?: boolean
	executor?: 'local' | 'orb' | 'runner'
	runnerId?: string
	runnerDir?: string
	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. executor: 'orb' runs the agent in an orb; executor: 'runner' runs it on one of your runners, identified by runnerId. Set runnerDir to the absolute path of one directory the runner serves, or omit it to use its starting directory. Each thread has one working directory; use separate execute() calls for multiple directories. Continuing a thread ignores this option and keeps its existing directory. cwd only sets the local CLI subprocess directory, not the remote runner directory.

With either remote executor, prompt must be a string rather than streaming input, and local-only options such as enabledTools, skills, and mcpConfig are ignored with a warning; configure those in the Amp project or on the runner instead. Plugin agent modes must be loaded on the runner. 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.

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 enabling or disabling 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

Requirements

• Node.js 18 or higher