airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb4aea57a87f6c20a68caf66533d734b08ee29e4
claude-mem/docs/context/agent-sdk-ts-reference.md
T
basher83 97d565e3cd Replace search skill with mem-search (#91) 
* feat: add mem-search skill with progressive disclosure architecture

Add comprehensive mem-search skill for accessing claude-mem's persistent
cross-session memory database. Implements progressive disclosure workflow
and token-efficient search patterns.

Features:
- 12 search operations (observations, sessions, prompts, by-type, by-concept, by-file, timelines, etc.)
- Progressive disclosure principles to minimize token usage
- Anti-patterns documentation to guide LLM behavior
- HTTP API integration for all search functionality
- Common workflows with composition examples

Structure:
- SKILL.md: Entry point with temporal trigger patterns
- principles/: Progressive disclosure + anti-patterns
- operations/: 12 search operation files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add CHANGELOG entry for mem-search skill

Document mem-search skill addition in Unreleased section with:
- 100% effectiveness compliance metrics
- Comparison to previous search skill implementation
- Progressive disclosure architecture details
- Reference to audit report documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add mem-search skill audit report

Add comprehensive audit report validating mem-search skill against
Anthropic's official skill-creator documentation.

Report includes:
- Effectiveness metrics comparison (search vs mem-search)
- Critical issues analysis for production readiness
- Compliance validation across 6 key dimensions
- Reference implementation guidance

Result: mem-search achieves 100% compliance vs search's 67%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: Add comprehensive search architecture analysis document

- Document current state of dual search architectures (HTTP API and MCP)
- Analyze HTTP endpoints and MCP search server architectures
- Identify DRY violations across search implementations
- Evaluate the use of curl as the optimal approach for search
- Provide architectural recommendations for immediate and long-term improvements
- Outline action plan for cleanup, feature parity, DRY refactoring

* refactor: Remove deprecated search skill documentation and operations

* refactor: Reorganize documentation into public and context directories

Changes:
- Created docs/public/ for Mintlify documentation (.mdx files)
- Created docs/context/ for internal planning and implementation docs
- Moved all .mdx files and assets to docs/public/
- Moved all internal .md files to docs/context/
- Added CLAUDE.md to both directories explaining their purpose
- Updated docs.json paths to work with new structure

Benefits:
- Clear separation between user-facing and internal documentation
- Easier to maintain Mintlify docs in dedicated directory
- Internal context files organized separately

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Enhance session management and continuity in hooks

- Updated new-hook.ts to clarify session_id threading and idempotent session creation.
- Modified prompts.ts to require claudeSessionId for continuation prompts, ensuring session context is maintained.
- Improved SessionStore.ts documentation on createSDKSession to emphasize idempotent behavior and session connection.
- Refined SDKAgent.ts to detail continuation prompt logic and its reliance on session.claudeSessionId for unified session handling.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Alex Newman <thedotmack@gmail.com>
2025-11-11 16:15:07 -05:00

1798 lines
47 KiB
Markdown
Raw Blame History

# Agent SDK reference - TypeScript
> Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces.
<script src="/components/typescript-sdk-type-links.js" defer />
## Installation
```bash theme={null}
npm install @anthropic-ai/claude-agent-sdk
```
## Functions
### `query()`
The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive.
```ts theme={null}
function query({
prompt,
options
}: {
prompt: string | AsyncIterable<SDKUserMessage>;
options?: Options;
}): Query
```
#### Parameters
| Parameter | Type | Description |
| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------- |
| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode |
| `options` | [`Options`](#options) | Optional configuration object (see Options type below) |
#### Returns
Returns a [`Query`](#query-1) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods.
### `tool()`
Creates a type-safe MCP tool definition for use with SDK MCP servers.
```ts theme={null}
function tool<Schema extends ZodRawShape>(
name: string,
description: string,
inputSchema: Schema,
handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>
```
#### Parameters
| Parameter | Type | Description |
| :------------ | :---------------------------------------------------------------- | :---------------------------------------------- |
| `name` | `string` | The name of the tool |
| `description` | `string` | A description of what the tool does |
| `inputSchema` | `Schema extends ZodRawShape` | Zod schema defining the tool's input parameters |
| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic |
### `createSdkMcpServer()`
Creates an MCP server instance that runs in the same process as your application.
```ts theme={null}
function createSdkMcpServer(options: {
name: string;
version?: string;
tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance
```
#### Parameters
| Parameter | Type | Description |
| :---------------- | :---------------------------- | :------------------------------------------------------- |
| `options.name` | `string` | The name of the MCP server |
| `options.version` | `string` | Optional version string |
| `options.tools` | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) |
## Types
### `Options`
Configuration object for the `query()` function.
| Property | Type | Default | Description |
| :--------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations |
| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access |
| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Programmatically define subagents |
| `allowedTools` | `string[]` | All tools | List of allowed tool names |
| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function for tool usage |
| `continue` | `boolean` | `false` | Continue the most recent conversation |
| `cwd` | `string` | `process.cwd()` | Current working directory |
| `disallowedTools` | `string[]` | `[]` | List of disallowed tool names |
| `env` | `Dict<string>` | `process.env` | Environment variables |
| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime to use |
| `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable |
| `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments |
| `fallbackModel` | `string` | `undefined` | Model to use if primary fails |
| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |
| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Hook callbacks for events |
| `includePartialMessages` | `boolean` | `false` | Include partial message events |
| `maxThinkingTokens` | `number` | `undefined` | Maximum tokens for thinking process |
| `maxTurns` | `number` | `undefined` | Maximum conversation turns |
| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP server configurations |
| `model` | `string` | Default from CLI | Claude model to use |
| `pathToClaudeCodeExecutable` | `string` | Auto-detected | Path to Claude Code executable |
| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session |
| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts |
| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/en/docs/agent-sdk/plugins) for details |
| `resume` | `string` | `undefined` | Session ID to resume |
| `settingSources` | [`SettingSource`](#settingsource)`[]` | `[]` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `'project'` to load CLAUDE.md files |
| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output |
| `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation |
| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` (empty prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |
### `Query`
Interface returned by the `query()` function.
```ts theme={null}
interface Query extends AsyncGenerator<SDKMessage, void> {
interrupt(): Promise<void>;
setPermissionMode(mode: PermissionMode): Promise<void>;
}
```
#### Methods
| Method | Description |
| :-------------------- | :------------------------------------------------------------------- |
| `interrupt()` | Interrupts the query (only available in streaming input mode) |
| `setPermissionMode()` | Changes the permission mode (only available in streaming input mode) |
### `AgentDefinition`
Configuration for a subagent defined programmatically.
```ts theme={null}
type AgentDefinition = {
description: string;
tools?: string[];
prompt: string;
model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
}
```
| Field | Required | Description |
| :------------ | :------- | :------------------------------------------------------------- |
| `description` | Yes | Natural language description of when to use this agent |
| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |
| `prompt` | Yes | The agent's system prompt |
| `model` | No | Model override for this agent. If omitted, uses the main model |
### `SettingSource`
Controls which filesystem-based configuration sources the SDK loads settings from.
```ts theme={null}
type SettingSource = 'user' | 'project' | 'local';
```
| Value | Description | Location |
| :---------- | :------------------------------------------- | :---------------------------- |
| `'user'` | Global user settings | `~/.claude/settings.json` |
| `'project'` | Shared project settings (version controlled) | `.claude/settings.json` |
| `'local'` | Local project settings (gitignored) | `.claude/settings.local.json` |
#### Default behavior
When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.
#### Why use settingSources?
**Load all filesystem settings (legacy behavior):**
```typescript theme={null}
// Load all settings like SDK v0.0.x did
const result = query({
prompt: "Analyze this code",
options: {
settingSources: ['user', 'project', 'local'] // Load all settings
}
});
```
**Load only specific setting sources:**
```typescript theme={null}
// Load only project settings, ignore user and local
const result = query({
prompt: "Run CI checks",
options: {
settingSources: ['project'] // Only .claude/settings.json
}
});
```
**Testing and CI environments:**
```typescript theme={null}
// Ensure consistent behavior in CI by excluding local settings
const result = query({
prompt: "Run tests",
options: {
settingSources: ['project'], // Only team-shared settings
permissionMode: 'bypassPermissions'
}
});
```
**SDK-only applications:**
```typescript theme={null}
// Define everything programmatically (default behavior)
// No filesystem dependencies - settingSources defaults to []
const result = query({
prompt: "Review this PR",
options: {
// settingSources: [] is the default, no need to specify
agents: { /* ... */ },
mcpServers: { /* ... */ },
allowedTools: ['Read', 'Grep', 'Glob']
}
});
```
**Loading CLAUDE.md project instructions:**
```typescript theme={null}
// Load project settings to include CLAUDE.md files
const result = query({
prompt: "Add a new feature following project conventions",
options: {
systemPrompt: {
type: 'preset',
preset: 'claude_code' // Required to use CLAUDE.md
},
settingSources: ['project'], // Loads CLAUDE.md from project directory
allowedTools: ['Read', 'Write', 'Edit']
}
});
```
#### Settings precedence
When multiple sources are loaded, settings are merged with this precedence (highest to lowest):
1. Local settings (`.claude/settings.local.json`)
2. Project settings (`.claude/settings.json`)
3. User settings (`~/.claude/settings.json`)
Programmatic options (like `agents`, `allowedTools`) always override filesystem settings.
### `PermissionMode`
```ts theme={null}
type PermissionMode =
| 'default' // Standard permission behavior
| 'acceptEdits' // Auto-accept file edits
| 'bypassPermissions' // Bypass all permission checks
| 'plan' // Planning mode - no execution
```
### `CanUseTool`
Custom permission function type for controlling tool usage.
```ts theme={null}
type CanUseTool = (
toolName: string,
input: ToolInput,
options: {
signal: AbortSignal;
suggestions?: PermissionUpdate[];
}
) => Promise<PermissionResult>;
```
### `PermissionResult`
Result of a permission check.
```ts theme={null}
type PermissionResult =
| {
behavior: 'allow';
updatedInput: ToolInput;
updatedPermissions?: PermissionUpdate[];
}
| {
behavior: 'deny';
message: string;
interrupt?: boolean;
}
```
### `McpServerConfig`
Configuration for MCP servers.
```ts theme={null}
type McpServerConfig =
| McpStdioServerConfig
| McpSSEServerConfig
| McpHttpServerConfig
| McpSdkServerConfigWithInstance;
```
#### `McpStdioServerConfig`
```ts theme={null}
type McpStdioServerConfig = {
type?: 'stdio';
command: string;
args?: string[];
env?: Record<string, string>;
}
```
#### `McpSSEServerConfig`
```ts theme={null}
type McpSSEServerConfig = {
type: 'sse';
url: string;
headers?: Record<string, string>;
}
```
#### `McpHttpServerConfig`
```ts theme={null}
type McpHttpServerConfig = {
type: 'http';
url: string;
headers?: Record<string, string>;
}
```
#### `McpSdkServerConfigWithInstance`
```ts theme={null}
type McpSdkServerConfigWithInstance = {
type: 'sdk';
name: string;
instance: McpServer;
}
```
### `SdkPluginConfig`
Configuration for loading plugins in the SDK.
```ts theme={null}
type SdkPluginConfig = {
type: 'local';
path: string;
}
```
| Field | Type | Description |
| :----- | :-------- | :--------------------------------------------------------- |
| `type` | `'local'` | Must be `'local'` (only local plugins currently supported) |
| `path` | `string` | Absolute or relative path to the plugin directory |
**Example:**
```ts theme={null}
plugins: [
{ type: 'local', path: './my-plugin' },
{ type: 'local', path: '/absolute/path/to/plugin' }
]
```
For complete information on creating and using plugins, see [Plugins](/en/docs/agent-sdk/plugins).
## Message Types
### `SDKMessage`
Union type of all possible messages returned by the query.
```ts theme={null}
type SDKMessage =
| SDKAssistantMessage
| SDKUserMessage
| SDKUserMessageReplay
| SDKResultMessage
| SDKSystemMessage
| SDKPartialAssistantMessage
| SDKCompactBoundaryMessage;
```
### `SDKAssistantMessage`
Assistant response message.
```ts theme={null}
type SDKAssistantMessage = {
type: 'assistant';
uuid: UUID;
session_id: string;
message: APIAssistantMessage; // From Anthropic SDK
parent_tool_use_id: string | null;
}
```
### `SDKUserMessage`
User input message.
```ts theme={null}
type SDKUserMessage = {
type: 'user';
uuid?: UUID;
session_id: string;
message: APIUserMessage; // From Anthropic SDK
parent_tool_use_id: string | null;
}
```
### `SDKUserMessageReplay`
Replayed user message with required UUID.
```ts theme={null}
type SDKUserMessageReplay = {
type: 'user';
uuid: UUID;
session_id: string;
message: APIUserMessage;
parent_tool_use_id: string | null;
}
```
### `SDKResultMessage`
Final result message.
```ts theme={null}
type SDKResultMessage =
| {
type: 'result';
subtype: 'success';
uuid: UUID;
session_id: string;
duration_ms: number;
duration_api_ms: number;
is_error: boolean;
num_turns: number;
result: string;
total_cost_usd: number;
usage: NonNullableUsage;
permission_denials: SDKPermissionDenial[];
}
| {
type: 'result';
subtype: 'error_max_turns' | 'error_during_execution';
uuid: UUID;
session_id: string;
duration_ms: number;
duration_api_ms: number;
is_error: boolean;
num_turns: number;
total_cost_usd: number;
usage: NonNullableUsage;
permission_denials: SDKPermissionDenial[];
}
```
### `SDKSystemMessage`
System initialization message.
```ts theme={null}
type SDKSystemMessage = {
type: 'system';
subtype: 'init';
uuid: UUID;
session_id: string;
apiKeySource: ApiKeySource;
cwd: string;
tools: string[];
mcp_servers: {
name: string;
status: string;
}[];
model: string;
permissionMode: PermissionMode;
slash_commands: string[];
output_style: string;
}
```
### `SDKPartialAssistantMessage`
Streaming partial message (only when `includePartialMessages` is true).
```ts theme={null}
type SDKPartialAssistantMessage = {
type: 'stream_event';
event: RawMessageStreamEvent; // From Anthropic SDK
parent_tool_use_id: string | null;
uuid: UUID;
session_id: string;
}
```
### `SDKCompactBoundaryMessage`
Message indicating a conversation compaction boundary.
```ts theme={null}
type SDKCompactBoundaryMessage = {
type: 'system';
subtype: 'compact_boundary';
uuid: UUID;
session_id: string;
compact_metadata: {
trigger: 'manual' | 'auto';
pre_tokens: number;
};
}
```
### `SDKPermissionDenial`
Information about a denied tool use.
```ts theme={null}
type SDKPermissionDenial = {
tool_name: string;
tool_use_id: string;
tool_input: ToolInput;
}
```
## Hook Types
### `HookEvent`
Available hook events.
```ts theme={null}
type HookEvent =
| 'PreToolUse'
| 'PostToolUse'
| 'Notification'
| 'UserPromptSubmit'
| 'SessionStart'
| 'SessionEnd'
| 'Stop'
| 'SubagentStop'
| 'PreCompact';
```
### `HookCallback`
Hook callback function type.
```ts theme={null}
type HookCallback = (
input: HookInput, // Union of all hook input types
toolUseID: string | undefined,
options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;
```
### `HookCallbackMatcher`
Hook configuration with optional matcher.
```ts theme={null}
interface HookCallbackMatcher {
matcher?: string;
hooks: HookCallback[];
}
```
### `HookInput`
Union type of all hook input types.
```ts theme={null}
type HookInput =
| PreToolUseHookInput
| PostToolUseHookInput
| NotificationHookInput
| UserPromptSubmitHookInput
| SessionStartHookInput
| SessionEndHookInput
| StopHookInput
| SubagentStopHookInput
| PreCompactHookInput;
```
### `BaseHookInput`
Base interface that all hook input types extend.
```ts theme={null}
type BaseHookInput = {
session_id: string;
transcript_path: string;
cwd: string;
permission_mode?: string;
}
```
#### `PreToolUseHookInput`
```ts theme={null}
type PreToolUseHookInput = BaseHookInput & {
hook_event_name: 'PreToolUse';
tool_name: string;
tool_input: ToolInput;
}
```
#### `PostToolUseHookInput`
```ts theme={null}
type PostToolUseHookInput = BaseHookInput & {
hook_event_name: 'PostToolUse';
tool_name: string;
tool_input: ToolInput;
tool_response: ToolOutput;
}
```
#### `NotificationHookInput`
```ts theme={null}
type NotificationHookInput = BaseHookInput & {
hook_event_name: 'Notification';
message: string;
title?: string;
}
```
#### `UserPromptSubmitHookInput`
```ts theme={null}
type UserPromptSubmitHookInput = BaseHookInput & {
hook_event_name: 'UserPromptSubmit';
prompt: string;
}
```
#### `SessionStartHookInput`
```ts theme={null}
type SessionStartHookInput = BaseHookInput & {
hook_event_name: 'SessionStart';
source: 'startup' | 'resume' | 'clear' | 'compact';
}
```
#### `SessionEndHookInput`
```ts theme={null}
type SessionEndHookInput = BaseHookInput & {
hook_event_name: 'SessionEnd';
reason: 'clear' | 'logout' | 'prompt_input_exit' | 'other';
}
```
#### `StopHookInput`
```ts theme={null}
type StopHookInput = BaseHookInput & {
hook_event_name: 'Stop';
stop_hook_active: boolean;
}
```
#### `SubagentStopHookInput`
```ts theme={null}
type SubagentStopHookInput = BaseHookInput & {
hook_event_name: 'SubagentStop';
stop_hook_active: boolean;
}
```
#### `PreCompactHookInput`
```ts theme={null}
type PreCompactHookInput = BaseHookInput & {
hook_event_name: 'PreCompact';
trigger: 'manual' | 'auto';
custom_instructions: string | null;
}
```
### `HookJSONOutput`
Hook return value.
```ts theme={null}
type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
```
#### `AsyncHookJSONOutput`
```ts theme={null}
type AsyncHookJSONOutput = {
async: true;
asyncTimeout?: number;
}
```
#### `SyncHookJSONOutput`
```ts theme={null}
type SyncHookJSONOutput = {
continue?: boolean;
suppressOutput?: boolean;
stopReason?: string;
decision?: 'approve' | 'block';
systemMessage?: string;
reason?: string;
hookSpecificOutput?:
| {
hookEventName: 'PreToolUse';
permissionDecision?: 'allow' | 'deny' | 'ask';
permissionDecisionReason?: string;
}
| {
hookEventName: 'UserPromptSubmit';
additionalContext?: string;
}
| {
hookEventName: 'SessionStart';
additionalContext?: string;
}
| {
hookEventName: 'PostToolUse';
additionalContext?: string;
};
}
```
## Tool Input Types
Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions.
### `ToolInput`
**Note:** This is a documentation-only type for clarity. It represents the union of all tool input types.
```ts theme={null}
type ToolInput =
| AgentInput
| BashInput
| BashOutputInput
| FileEditInput
| FileReadInput
| FileWriteInput
| GlobInput
| GrepInput
| KillShellInput
| NotebookEditInput
| WebFetchInput
| WebSearchInput
| TodoWriteInput
| ExitPlanModeInput
| ListMcpResourcesInput
| ReadMcpResourceInput;
```
### Task
**Tool name:** `Task`
```ts theme={null}
interface AgentInput {
/**
* A short (3-5 word) description of the task
*/
description: string;
/**
* The task for the agent to perform
*/
prompt: string;
/**
* The type of specialized agent to use for this task
*/
subagent_type: string;
}
```
Launches a new agent to handle complex, multi-step tasks autonomously.
### Bash
**Tool name:** `Bash`
```ts theme={null}
interface BashInput {
/**
* The command to execute
*/
command: string;
/**
* Optional timeout in milliseconds (max 600000)
*/
timeout?: number;
/**
* Clear, concise description of what this command does in 5-10 words
*/
description?: string;
/**
* Set to true to run this command in the background
*/
run_in_background?: boolean;
}
```
Executes bash commands in a persistent shell session with optional timeout and background execution.
### BashOutput
**Tool name:** `BashOutput`
```ts theme={null}
interface BashOutputInput {
/**
* The ID of the background shell to retrieve output from
*/
bash_id: string;
/**
* Optional regex to filter output lines
*/
filter?: string;
}
```
Retrieves output from a running or completed background bash shell.
### Edit
**Tool name:** `Edit`
```ts theme={null}
interface FileEditInput {
/**
* The absolute path to the file to modify
*/
file_path: string;
/**
* The text to replace
*/
old_string: string;
/**
* The text to replace it with (must be different from old_string)
*/
new_string: string;
/**
* Replace all occurrences of old_string (default false)
*/
replace_all?: boolean;
}
```
Performs exact string replacements in files.
### Read
**Tool name:** `Read`
```ts theme={null}
interface FileReadInput {
/**
* The absolute path to the file to read
*/
file_path: string;
/**
* The line number to start reading from
*/
offset?: number;
/**
* The number of lines to read
*/
limit?: number;
}
```
Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks.
### Write
**Tool name:** `Write`
```ts theme={null}
interface FileWriteInput {
/**
* The absolute path to the file to write
*/
file_path: string;
/**
* The content to write to the file
*/
content: string;
}
```
Writes a file to the local filesystem, overwriting if it exists.
### Glob
**Tool name:** `Glob`
```ts theme={null}
interface GlobInput {
/**
* The glob pattern to match files against
*/
pattern: string;
/**
* The directory to search in (defaults to cwd)
*/
path?: string;
}
```
Fast file pattern matching that works with any codebase size.
### Grep
**Tool name:** `Grep`
```ts theme={null}
interface GrepInput {
/**
* The regular expression pattern to search for
*/
pattern: string;
/**
* File or directory to search in (defaults to cwd)
*/
path?: string;
/**
* Glob pattern to filter files (e.g. "*.js")
*/
glob?: string;
/**
* File type to search (e.g. "js", "py", "rust")
*/
type?: string;
/**
* Output mode: "content", "files_with_matches", or "count"
*/
output_mode?: 'content' | 'files_with_matches' | 'count';
/**
* Case insensitive search
*/
'-i'?: boolean;
/**
* Show line numbers (for content mode)
*/
'-n'?: boolean;
/**
* Lines to show before each match
*/
'-B'?: number;
/**
* Lines to show after each match
*/
'-A'?: number;
/**
* Lines to show before and after each match
*/
'-C'?: number;
/**
* Limit output to first N lines/entries
*/
head_limit?: number;
/**
* Enable multiline mode
*/
multiline?: boolean;
}
```
Powerful search tool built on ripgrep with regex support.
### KillBash
**Tool name:** `KillBash`
```ts theme={null}
interface KillShellInput {
/**
* The ID of the background shell to kill
*/
shell_id: string;
}
```
Kills a running background bash shell by its ID.
### NotebookEdit
**Tool name:** `NotebookEdit`
```ts theme={null}
interface NotebookEditInput {
/**
* The absolute path to the Jupyter notebook file
*/
notebook_path: string;
/**
* The ID of the cell to edit
*/
cell_id?: string;
/**
* The new source for the cell
*/
new_source: string;
/**
* The type of the cell (code or markdown)
*/
cell_type?: 'code' | 'markdown';
/**
* The type of edit (replace, insert, delete)
*/
edit_mode?: 'replace' | 'insert' | 'delete';
}
```
Edits cells in Jupyter notebook files.
### WebFetch
**Tool name:** `WebFetch`
```ts theme={null}
interface WebFetchInput {
/**
* The URL to fetch content from
*/
url: string;
/**
* The prompt to run on the fetched content
*/
prompt: string;
}
```
Fetches content from a URL and processes it with an AI model.
### WebSearch
**Tool name:** `WebSearch`
```ts theme={null}
interface WebSearchInput {
/**
* The search query to use
*/
query: string;
/**
* Only include results from these domains
*/
allowed_domains?: string[];
/**
* Never include results from these domains
*/
blocked_domains?: string[];
}
```
Searches the web and returns formatted results.
### TodoWrite
**Tool name:** `TodoWrite`
```ts theme={null}
interface TodoWriteInput {
/**
* The updated todo list
*/
todos: Array<{
/**
* The task description
*/
content: string;
/**
* The task status
*/
status: 'pending' | 'in_progress' | 'completed';
/**
* Active form of the task description
*/
activeForm: string;
}>;
}
```
Creates and manages a structured task list for tracking progress.
### ExitPlanMode
**Tool name:** `ExitPlanMode`
```ts theme={null}
interface ExitPlanModeInput {
/**
* The plan to run by the user for approval
*/
plan: string;
}
```
Exits planning mode and prompts the user to approve the plan.
### ListMcpResources
**Tool name:** `ListMcpResources`
```ts theme={null}
interface ListMcpResourcesInput {
/**
* Optional server name to filter resources by
*/
server?: string;
}
```
Lists available MCP resources from connected servers.
### ReadMcpResource
**Tool name:** `ReadMcpResource`
```ts theme={null}
interface ReadMcpResourceInput {
/**
* The MCP server name
*/
server: string;
/**
* The resource URI to read
*/
uri: string;
}
```
Reads a specific MCP resource from a server.
## Tool Output Types
Documentation of output schemas for all built-in Claude Code tools. These types represent the actual response data returned by each tool.
### `ToolOutput`
**Note:** This is a documentation-only type for clarity. It represents the union of all tool output types.
```ts theme={null}
type ToolOutput =
| TaskOutput
| BashOutput
| BashOutputToolOutput
| EditOutput
| ReadOutput
| WriteOutput
| GlobOutput
| GrepOutput
| KillBashOutput
| NotebookEditOutput
| WebFetchOutput
| WebSearchOutput
| TodoWriteOutput
| ExitPlanModeOutput
| ListMcpResourcesOutput
| ReadMcpResourceOutput;
```
### Task
**Tool name:** `Task`
```ts theme={null}
interface TaskOutput {
/**
* Final result message from the subagent
*/
result: string;
/**
* Token usage statistics
*/
usage?: {
input_tokens: number;
output_tokens: number;
cache_creation_input_tokens?: number;
cache_read_input_tokens?: number;
};
/**
* Total cost in USD
*/
total_cost_usd?: number;
/**
* Execution duration in milliseconds
*/
duration_ms?: number;
}
```
Returns the final result from the subagent after completing the delegated task.
### Bash
**Tool name:** `Bash`
```ts theme={null}
interface BashOutput {
/**
* Combined stdout and stderr output
*/
output: string;
/**
* Exit code of the command
*/
exitCode: number;
/**
* Whether the command was killed due to timeout
*/
killed?: boolean;
/**
* Shell ID for background processes
*/
shellId?: string;
}
```
Returns command output with exit status. Background commands return immediately with a shellId.
### BashOutput
**Tool name:** `BashOutput`
```ts theme={null}
interface BashOutputToolOutput {
/**
* New output since last check
*/
output: string;
/**
* Current shell status
*/
status: 'running' | 'completed' | 'failed';
/**
* Exit code (when completed)
*/
exitCode?: number;
}
```
Returns incremental output from background shells.
### Edit
**Tool name:** `Edit`
```ts theme={null}
interface EditOutput {
/**
* Confirmation message
*/
message: string;
/**
* Number of replacements made
*/
replacements: number;
/**
* File path that was edited
*/
file_path: string;
}
```
Returns confirmation of successful edits with replacement count.
### Read
**Tool name:** `Read`
```ts theme={null}
type ReadOutput =
| TextFileOutput
| ImageFileOutput
| PDFFileOutput
| NotebookFileOutput;
interface TextFileOutput {
/**
* File contents with line numbers
*/
content: string;
/**
* Total number of lines in file
*/
total_lines: number;
/**
* Lines actually returned
*/
lines_returned: number;
}
interface ImageFileOutput {
/**
* Base64 encoded image data
*/
image: string;
/**
* Image MIME type
*/
mime_type: string;
/**
* File size in bytes
*/
file_size: number;
}
interface PDFFileOutput {
/**
* Array of page contents
*/
pages: Array<{
page_number: number;
text?: string;
images?: Array<{
image: string;
mime_type: string;
}>;
}>;
/**
* Total number of pages
*/
total_pages: number;
}
interface NotebookFileOutput {
/**
* Jupyter notebook cells
*/
cells: Array<{
cell_type: 'code' | 'markdown';
source: string;
outputs?: any[];
execution_count?: number;
}>;
/**
* Notebook metadata
*/
metadata?: Record<string, any>;
}
```
Returns file contents in format appropriate to file type.
### Write
**Tool name:** `Write`
```ts theme={null}
interface WriteOutput {
/**
* Success message
*/
message: string;
/**
* Number of bytes written
*/
bytes_written: number;
/**
* File path that was written
*/
file_path: string;
}
```
Returns confirmation after successfully writing the file.
### Glob
**Tool name:** `Glob`
```ts theme={null}
interface GlobOutput {
/**
* Array of matching file paths
*/
matches: string[];
/**
* Number of matches found
*/
count: number;
/**
* Search directory used
*/
search_path: string;
}
```
Returns file paths matching the glob pattern, sorted by modification time.
### Grep
**Tool name:** `Grep`
```ts theme={null}
type GrepOutput =
| GrepContentOutput
| GrepFilesOutput
| GrepCountOutput;
interface GrepContentOutput {
/**
* Matching lines with context
*/
matches: Array<{
file: string;
line_number?: number;
line: string;
before_context?: string[];
after_context?: string[];
}>;
/**
* Total number of matches
*/
total_matches: number;
}
interface GrepFilesOutput {
/**
* Files containing matches
*/
files: string[];
/**
* Number of files with matches
*/
count: number;
}
interface GrepCountOutput {
/**
* Match counts per file
*/
counts: Array<{
file: string;
count: number;
}>;
/**
* Total matches across all files
*/
total: number;
}
```
Returns search results in the format specified by output\_mode.
### KillBash
**Tool name:** `KillBash`
```ts theme={null}
interface KillBashOutput {
/**
* Success message
*/
message: string;
/**
* ID of the killed shell
*/
shell_id: string;
}
```
Returns confirmation after terminating the background shell.
### NotebookEdit
**Tool name:** `NotebookEdit`
```ts theme={null}
interface NotebookEditOutput {
/**
* Success message
*/
message: string;
/**
* Type of edit performed
*/
edit_type: 'replaced' | 'inserted' | 'deleted';
/**
* Cell ID that was affected
*/
cell_id?: string;
/**
* Total cells in notebook after edit
*/
total_cells: number;
}
```
Returns confirmation after modifying the Jupyter notebook.
### WebFetch
**Tool name:** `WebFetch`
```ts theme={null}
interface WebFetchOutput {
/**
* AI model's response to the prompt
*/
response: string;
/**
* URL that was fetched
*/
url: string;
/**
* Final URL after redirects
*/
final_url?: string;
/**
* HTTP status code
*/
status_code?: number;
}
```
Returns the AI's analysis of the fetched web content.
### WebSearch
**Tool name:** `WebSearch`
```ts theme={null}
interface WebSearchOutput {
/**
* Search results
*/
results: Array<{
title: string;
url: string;
snippet: string;
/**
* Additional metadata if available
*/
metadata?: Record<string, any>;
}>;
/**
* Total number of results
*/
total_results: number;
/**
* The query that was searched
*/
query: string;
}
```
Returns formatted search results from the web.
### TodoWrite
**Tool name:** `TodoWrite`
```ts theme={null}
interface TodoWriteOutput {
/**
* Success message
*/
message: string;
/**
* Current todo statistics
*/
stats: {
total: number;
pending: number;
in_progress: number;
completed: number;
};
}
```
Returns confirmation with current task statistics.
### ExitPlanMode
**Tool name:** `ExitPlanMode`
```ts theme={null}
interface ExitPlanModeOutput {
/**
* Confirmation message
*/
message: string;
/**
* Whether user approved the plan
*/
approved?: boolean;
}
```
Returns confirmation after exiting plan mode.
### ListMcpResources
**Tool name:** `ListMcpResources`
```ts theme={null}
interface ListMcpResourcesOutput {
/**
* Available resources
*/
resources: Array<{
uri: string;
name: string;
description?: string;
mimeType?: string;
server: string;
}>;
/**
* Total number of resources
*/
total: number;
}
```
Returns list of available MCP resources.
### ReadMcpResource
**Tool name:** `ReadMcpResource`
```ts theme={null}
interface ReadMcpResourceOutput {
/**
* Resource contents
*/
contents: Array<{
uri: string;
mimeType?: string;
text?: string;
blob?: string;
}>;
/**
* Server that provided the resource
*/
server: string;
}
```
Returns the contents of the requested MCP resource.
## Permission Types
### `PermissionUpdate`
Operations for updating permissions.
```ts theme={null}
type PermissionUpdate =
| {
type: 'addRules';
rules: PermissionRuleValue[];
behavior: PermissionBehavior;
destination: PermissionUpdateDestination;
}
| {
type: 'replaceRules';
rules: PermissionRuleValue[];
behavior: PermissionBehavior;
destination: PermissionUpdateDestination;
}
| {
type: 'removeRules';
rules: PermissionRuleValue[];
behavior: PermissionBehavior;
destination: PermissionUpdateDestination;
}
| {
type: 'setMode';
mode: PermissionMode;
destination: PermissionUpdateDestination;
}
| {
type: 'addDirectories';
directories: string[];
destination: PermissionUpdateDestination;
}
| {
type: 'removeDirectories';
directories: string[];
destination: PermissionUpdateDestination;
}
```
### `PermissionBehavior`
```ts theme={null}
type PermissionBehavior = 'allow' | 'deny' | 'ask';
```
### `PermissionUpdateDestination`
```ts theme={null}
type PermissionUpdateDestination =
| 'userSettings' // Global user settings
| 'projectSettings' // Per-directory project settings
| 'localSettings' // Gitignored local settings
| 'session' // Current session only
```
### `PermissionRuleValue`
```ts theme={null}
type PermissionRuleValue = {
toolName: string;
ruleContent?: string;
}
```
## Other Types
### `ApiKeySource`
```ts theme={null}
type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';
```
### `ConfigScope`
```ts theme={null}
type ConfigScope = 'local' | 'user' | 'project';
```
### `NonNullableUsage`
A version of [`Usage`](#usage) with all nullable fields made non-nullable.
```ts theme={null}
type NonNullableUsage = {
[K in keyof Usage]: NonNullable<Usage[K]>;
}
```
### `Usage`
Token usage statistics (from `@anthropic-ai/sdk`).
```ts theme={null}
type Usage = {
input_tokens: number | null;
output_tokens: number | null;
cache_creation_input_tokens?: number | null;
cache_read_input_tokens?: number | null;
}
```
### `CallToolResult`
MCP tool result type (from `@modelcontextprotocol/sdk/types.js`).
```ts theme={null}
type CallToolResult = {
content: Array<{
type: 'text' | 'image' | 'resource';
// Additional fields vary by type
}>;
isError?: boolean;
}
```
### `AbortError`
Custom error class for abort operations.
```ts theme={null}
class AbortError extends Error {}
```
## See also
* [SDK overview](/en/docs/agent-sdk/overview) - General SDK concepts
* [Python SDK reference](/en/docs/agent-sdk/python) - Python SDK documentation
* [CLI reference](https://code.claude.com/docs/en/cli-reference) - Command-line interface
* [Common workflows](https://code.claude.com/docs/en/common-workflows) - Step-by-step guides
Reference in New Issue View Git Blame Copy Permalink