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

# Claude Agent SDK setup guide

> Build AI agents that can read files, run commands, and edit code using the Claude Agent SDK and Trigger.dev.

The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) gives you the same tools, agent loop, and context management that power Claude Code. Combined with Trigger.dev, you get durable execution, automatic retries, and full observability for your agents.

## Setup

<Note>
  This guide assumes you are working with an existing [Trigger.dev](https://trigger.dev) project.
  Follow our [quickstart](/quick-start) to get set up if you don't have a project yet.
</Note>

<Steps>
  <Step title="Install the Claude Agent SDK">
    ```bash npm theme={"theme":"css-variables"}
    npm install @anthropic-ai/claude-agent-sdk
    ```
  </Step>

  <Step title="Configure trigger.config.ts">
    Add the SDK to the `external` array so it's not bundled:

    ```ts trigger.config.ts theme={"theme":"css-variables"}
    import { defineConfig } from "@trigger.dev/sdk";

    export default defineConfig({
      project: process.env.TRIGGER_PROJECT_REF!,
      build: {
        external: ["@anthropic-ai/claude-agent-sdk"],
      },
      machine: "small-2x",
    });
    ```

    <Note>
      Adding packages to `external` prevents them from being bundled, which is necessary for the Claude
      Agent SDK. See the [build configuration docs](/config/config-file#external) for more details.
    </Note>
  </Step>

  <Step title="Set your API key">
    Add your Anthropic API key to your environment variables. The SDK reads it automatically.

    ```bash theme={"theme":"css-variables"}
    ANTHROPIC_API_KEY=sk-ant-...
    ```

    You can set this in the [Trigger.dev dashboard](https://cloud.trigger.dev) under **Environment Variables**, or in your `.env` file for local development.
  </Step>

  <Step title="Create your first agent task">
    This example creates a task where Claude generates code in an empty workspace. The agent will create files based on your prompt:

    ```ts trigger/claude-agent.ts theme={"theme":"css-variables"}
    import { query } from "@anthropic-ai/claude-agent-sdk";
    import { schemaTask, logger } from "@trigger.dev/sdk";
    import { mkdtemp, rm, readdir } from "node:fs/promises";
    import { tmpdir } from "node:os";
    import { join } from "node:path";
    import { z } from "zod";

    export const codeGenerator = schemaTask({
      id: "code-generator",
      schema: z.object({
        prompt: z.string(),
      }),
      run: async ({ prompt }, { signal }) => {
        const abortController = new AbortController();
        signal.addEventListener("abort", () => abortController.abort());

        // Create an empty workspace for the agent
        // The agent will create files here based on the prompt
        const workDir = await mkdtemp(join(tmpdir(), "claude-agent-"));
        logger.info("Created workspace", { workDir });

        try {
          const result = query({
            prompt,
            options: {
              model: "claude-sonnet-4-20250514",
              abortController,
              cwd: workDir,
              maxTurns: 10,
              permissionMode: "acceptEdits",
              allowedTools: ["Read", "Edit", "Write", "Glob"],
            },
          });

          for await (const message of result) {
            logger.info("Agent message", { type: message.type });
          }

          // See what files Claude created
          const files = await readdir(workDir, { recursive: true });
          logger.info("Files created", { files });

          return { filesCreated: files };
        } finally {
          await rm(workDir, { recursive: true, force: true });
        }
      },
    });
    ```
  </Step>

  <Step title="Run the dev server">
    ```bash theme={"theme":"css-variables"}
    npx trigger.dev@latest dev
    ```
  </Step>

  <Step title="Test your agent">
    Go to the Trigger.dev dashboard, find your `code-generator` task, and trigger it with a test payload:

    ```json theme={"theme":"css-variables"}
    {
      "prompt": "Create a Node.js project with a fibonacci.ts file containing a function to calculate fibonacci numbers, and a fibonacci.test.ts file with tests."
    }
    ```
  </Step>
</Steps>

## How it works

The `query()` function runs Claude in an agentic loop where it can:

1. **Read files** - Explore codebases with `Read`, `Grep`, and `Glob` tools
2. **Edit files** - Modify code with `Edit` and `Write` tools
3. **Run commands** - Execute shell commands with `Bash` tool (if enabled)
4. **Think step by step** - Use extended thinking for complex problems

The agent continues until it completes the task or reaches `maxTurns`.

### Permission modes

| Mode                  | What it does                                          |
| --------------------- | ----------------------------------------------------- |
| `"default"`           | Asks for approval on potentially dangerous operations |
| `"acceptEdits"`       | Auto-approves file operations, asks for bash/network  |
| `"bypassPermissions"` | Skips all safety checks (not recommended)             |

### Available tools

```ts theme={"theme":"css-variables"}
allowedTools: [
  "Task", // Planning and task management
  "Glob", // Find files by pattern
  "Grep", // Search file contents
  "Read", // Read file contents
  "Edit", // Edit existing files
  "Write", // Create new files
  "Bash", // Run shell commands
  "TodoRead", // Read todo list
  "TodoWrite", // Update todo list
];
```

## GitHub repo

<Card title="View the Claude Agent SDK + Trigger.dev example" icon="GitHub" href="https://github.com/triggerdotdev/examples/tree/main/claude-agent-sdk-trigger">
  A complete example with two agent patterns: basic safe code generation and advanced with bash
  execution.
</Card>

## Example projects using the Claude Agent SDK

<CardGroup cols={2}>
  <Card title="Claude changelog generator" icon="scroll" href="/guides/example-projects/claude-changelog-generator">
    Generate changelogs from git commits using custom MCP tools.
  </Card>

  <Card title="Claude GitHub wiki agent" icon="book" href="/guides/example-projects/claude-github-wiki">
    Analyze repositories and answer questions with real-time streaming.
  </Card>
</CardGroup>

## Learn more

* [Claude Agent SDK docs](https://platform.claude.com/docs/en/agent-sdk/overview) – Official Anthropic documentation
* [Trigger.dev Realtime](/realtime/overview) – Stream agent progress to your frontend
* [Waitpoints](/wait) – Add human-in-the-loop approval steps