> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Agent SDK

> Run @anthropic-ai/claude-agent-sdk against a Mirage workspace via an in-process MCP server exposing execute, read, write, edit, ls, and grep tools.

The [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/) builds agents on Claude. Mirage exposes any `Workspace` to the SDK as an in-process MCP server, so every file and shell operation the agent runs is routed through Mirage instead of the host filesystem.

This is distinct from [Claude Code](/typescript/agents/claude-code), which points the `claude` CLI at a FUSE mountpoint. Use this SDK integration when you build your own agent with the SDK's `query()` and want Mirage tools rather than the built-in file tools.

## Install

`@struktoai/mirage-agents/claude-agent-sdk` is runtime-agnostic. Pair it with `@struktoai/mirage-node` for Node or `@struktoai/mirage-browser` for the browser.

<CodeGroup>
  ```bash Node theme={null}
  pnpm add @struktoai/mirage-agents @struktoai/mirage-node @anthropic-ai/claude-agent-sdk
  ```

  ```bash Browser theme={null}
  pnpm add @struktoai/mirage-agents @struktoai/mirage-browser @anthropic-ai/claude-agent-sdk
  ```
</CodeGroup>

## Usage

`buildOptions` wires a workspace into ready-to-use query options: it registers the Mirage MCP server, restricts the agent to Mirage's tools, and injects a system prompt describing the mounted paths.

```ts theme={null}
import { MountMode, OpsRegistry, RAMResource, Workspace } from '@struktoai/mirage-node'
import { query } from '@anthropic-ai/claude-agent-sdk'
import { buildOptions } from '@struktoai/mirage-agents/claude-agent-sdk'

const ram = new RAMResource()
const ops = new OpsRegistry()
for (const op of ram.ops()) ops.register(op)
const ws = new Workspace({ '/': ram }, { mode: MountMode.WRITE, ops })

for await (const msg of query({
  prompt: "Write /hello.txt with 'hi from mirage', then cat it.",
  options: buildOptions(ws),
})) {
  console.log(msg)
}
```

## Composing with other MCP servers

Use `MirageServer` directly to combine Mirage with other servers:

```ts theme={null}
import { MirageServer, buildSystemPrompt } from '@struktoai/mirage-agents/claude-agent-sdk'

const options = {
  mcpServers: { mirage: MirageServer(ws), github: githubServer },
  allowedTools: ['mcp__mirage__*', 'mcp__github__*'],
  systemPrompt: buildSystemPrompt({ workspace: ws }),
}
```

## Tools

| Tool              | Maps to                                                                      |
| ----------------- | ---------------------------------------------------------------------------- |
| `execute_command` | `Workspace.execute()`, the full shell pipeline (cat, grep, find, pipe, ...). |
| `read`            | Line-paginated file read with `offset` and `limit`.                          |
| `write`           | Create a new file (fails if it already exists).                              |
| `edit`            | Replace a string in an existing file.                                        |
| `ls`              | List a directory.                                                            |
| `grep`            | Recursive `grep -rn` over the workspace.                                     |

## Exports

| Symbol                 | Purpose                                                                        |
| ---------------------- | ------------------------------------------------------------------------------ |
| `MirageServer`         | In-process MCP server exposing the Mirage tools; pass to `options.mcpServers`. |
| `buildOptions`         | Returns ready-to-use query `Options` backed by a workspace.                    |
| `buildSystemPrompt`    | Generates a system prompt that describes mounted paths to the model.           |
| `MIRAGE_SYSTEM_PROMPT` | The default system prompt template.                                            |