Build Production AI Agents with the Claude Agent SDK and TypeScript

mkdir claude-agent-project && cd claude-agent-project
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir dist

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc"
  }
}

mkdir src

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  console.log("Starting agent...\n");
 
  for await (const message of query({
    prompt: "What files are in this directory? Give me a summary of the project structure.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 10,
    },
  })) {
    // Handle different message types
    if ("result" in message) {
      console.log("\n--- Agent Result ---");
      console.log(message.result);
    }
  }
}
 
main().catch(console.error);

npx tsx src/index.ts

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  for await (const message of query({
    prompt: "Find all TypeScript files and count the total lines of code.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 15,
    },
  })) {
    switch (message.type) {
      case "assistant":
        // Claude's reasoning or response text
        const textBlocks = message.message.content
          .filter((block: { type: string }) => block.type === "text")
          .map((block: { type: string; text: string }) => block.text);
        if (textBlocks.length > 0) {
          console.log("[Claude]", textBlocks.join(""));
        }
        break;
 
      case "tool_use":
        // Claude is calling a tool
        console.log(`[Tool Call] ${message.name}(${JSON.stringify(message.input).slice(0, 100)}...)`);
        break;
 
      case "tool_result":
        // Tool execution result
        console.log(`[Tool Result] ${message.content?.slice(0, 200)}...`);
        break;
 
      case "result":
        if (message.subtype === "success") {
          console.log("\n✓ Agent completed successfully");
          console.log(message.result);
        } else {
          console.error("\n✗ Agent failed:", message.error);
        }
        break;
    }
  }
}
 
main().catch(console.error);

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function refactorAgent(targetFile: string, instruction: string) {
  for await (const message of query({
    prompt: `Refactor the file ${targetFile}: ${instruction}`,
    options: {
      allowedTools: ["Read", "Edit", "Glob", "Grep"],
      permissionMode: "acceptEdits", // Auto-approve file changes
      maxTurns: 20,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}
 
// Usage
const result = await refactorAgent(
  "src/utils.ts",
  "Extract all helper functions into separate modules based on their domain"
);
console.log(result);

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk/mcp";
 
// Define custom tools
const analyticsServer = createSdkMcpServer({
  name: "analytics",
  version: "1.0.0",
  tools: [
    tool(
      "get_page_views",
      "Get page view analytics for a given URL path and date range",
      {
        type: "object",
        properties: {
          path: { type: "string", description: "URL path (e.g., /blog/my-post)" },
          startDate: { type: "string", description: "Start date (YYYY-MM-DD)" },
          endDate: { type: "string", description: "End date (YYYY-MM-DD)" },
        },
        required: ["path", "startDate", "endDate"],
      },
      async ({ path, startDate, endDate }) => {
        // Your actual analytics API call here
        const response = await fetch(
          `https://api.analytics.example.com/views?path=${path}&start=${startDate}&end=${endDate}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
    tool(
      "get_top_pages",
      "Get the top N most visited pages",
      {
        type: "object",
        properties: {
          limit: { type: "number", description: "Number of pages to return" },
          period: { type: "string", enum: ["day", "week", "month"], description: "Time period" },
        },
        required: ["limit", "period"],
      },
      async ({ limit, period }) => {
        const response = await fetch(
          `https://api.analytics.example.com/top?limit=${limit}&period=${period}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
  ],
});
 
// Use with streaming input (required for MCP servers)
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "What are the top 10 most visited pages this month? Then analyze the trend for the #1 page over the last 30 days.",
    },
  };
}
 
for await (const message of query({
  prompt: generateMessages(),
  options: {
    mcpServers: {
      analytics: analyticsServer,
    },
    allowedTools: [
      "mcp__analytics__get_page_views",
      "mcp__analytics__get_top_pages",
    ],
    maxTurns: 10,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "List open issues labeled 'bug' and summarize the most critical ones.",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
        },
      },
    },
    allowedTools: ["mcp__github__*"], // Wildcard: allow all GitHub tools
    maxTurns: 15,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

options: {
  mcpServers: {
    "remote-api": {
      type: "sse",
      url: "https://mcp.example.com/sse",
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
    },
  },
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
const CODE_REVIEW_PROMPT = `You are a senior code reviewer specializing in TypeScript and React.
 
Your review process:
1. Read the changed files
2. Check for bugs, security issues, and performance problems
3. Verify TypeScript types are correct and complete
4. Ensure React best practices (hooks rules, key props, memo usage)
5. Provide a structured review with severity levels
 
Output format:
- 🔴 Critical: Must fix before merge
- 🟡 Warning: Should fix, but not blocking
- 🟢 Suggestion: Nice to have improvements
 
Be specific. Reference line numbers. Suggest fixes with code.`;
 
async function reviewCode(diffOrPath: string) {
  for await (const message of query({
    prompt: `Review this code:\n\n${diffOrPath}`,
    options: {
      systemPrompt: CODE_REVIEW_PROMPT,
      allowedTools: ["Read", "Glob", "Grep"],
      maxTurns: 25,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Analyze this project's test coverage, then write tests for any uncovered functions in src/utils/.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task"],
    agents: {
      "test-analyzer": {
        description: "Analyzes test coverage and identifies untested code paths",
        tools: ["Bash", "Read", "Glob", "Grep"],
        prompt: "You are a test coverage analyst. Run coverage tools, parse reports, and identify untested functions.",
        model: "haiku", // Use a faster model for analysis
      },
      "test-writer": {
        description: "Writes comprehensive unit tests for TypeScript functions",
        tools: ["Read", "Write", "Edit", "Glob"],
        prompt: "You are a test engineer. Write thorough unit tests using Vitest with proper mocking and edge case coverage.",
        model: "sonnet",
      },
    },
    maxTurns: 30,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Migrate all JavaScript files to TypeScript with proper types.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
 
    // Turn limits
    maxTurns: 50,           // Maximum tool calls before stopping
 
    // Cost controls
    maxBudgetUsd: 2.0,      // Stop if cost exceeds $2.00
 
    // Model selection
    model: "claude-sonnet-4-5-20250929",  // Use a specific model
 
    // Tool restrictions
    disallowedTools: ["WebSearch", "WebFetch"],  // Block specific tools
 
    // Working directory
    cwd: "/path/to/project",
 
    // Environment variables available to Bash tool
    env: {
      NODE_ENV: "development",
      DATABASE_URL: process.env.DATABASE_URL!,
    },
 
    // Permission mode
    permissionMode: "acceptEdits",
  },
})) {
  // Process messages
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Clean up and optimize the codebase.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
    canUseTool: async (toolName, input) => {
      // Block any destructive bash commands
      if (toolName === "Bash") {
        const command = (input as { command: string }).command;
        const dangerous = ["rm -rf", "DROP TABLE", "git push --force"];
        if (dangerous.some((d) => command.includes(d))) {
          return { allowed: false, reason: "Destructive commands are not permitted" };
        }
      }
 
      // Block writes to critical files
      if (toolName === "Write" || toolName === "Edit") {
        const filePath = (input as { file_path: string }).file_path;
        const protected_paths = [".env", "package-lock.json", "prisma/schema.prisma"];
        if (protected_paths.some((p) => filePath.includes(p))) {
          return { allowed: false, reason: `Cannot modify protected file: ${filePath}` };
        }
      }
 
      return { allowed: true };
    },
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

// src/review-bot.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
interface ReviewResult {
  summary: string;
  issues: Array<{
    severity: "critical" | "warning" | "suggestion";
    file: string;
    line?: number;
    message: string;
    suggestion?: string;
  }>;
  score: number;
}
 
const REVIEW_SYSTEM_PROMPT = `You are an expert code reviewer. Analyze git diffs and provide structured feedback.
 
Rules:
- Focus on bugs, security vulnerabilities, and performance issues
- Check for TypeScript type safety
- Verify error handling is comprehensive
- Look for potential race conditions in async code
- Suggest improvements only when they provide clear value
 
Always end your review with a JSON block in this exact format:
\`\`\`json
{
  "summary": "One paragraph summary",
  "issues": [
    {
      "severity": "critical|warning|suggestion",
      "file": "path/to/file.ts",
      "line": 42,
      "message": "Description of the issue",
      "suggestion": "How to fix it"
    }
  ],
  "score": 85
}
\`\`\`
 
Score: 0-100 where 100 is perfect code.`;
 
async function reviewPullRequest(baseBranch: string = "main"): Promise<ReviewResult | null> {
  let result: string | null = null;
 
  for await (const message of query({
    prompt: `Review the current git diff against ${baseBranch}.
Read the changed files for full context, then provide a structured code review.`,
    options: {
      systemPrompt: REVIEW_SYSTEM_PROMPT,
      allowedTools: ["Bash", "Read", "Glob", "Grep"],
      maxTurns: 30,
      maxBudgetUsd: 1.0,
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message && message.subtype === "success") {
      result = message.result;
    }
  }
 
  if (!result) return null;
 
  // Extract JSON from the result
  const jsonMatch = result.match(/```json\n([\s\S]*?)\n```/);
  if (jsonMatch) {
    return JSON.parse(jsonMatch[1]) as ReviewResult;
  }
 
  return null;
}
 
// Run the review
async function main() {
  console.log("Starting code review...\n");
 
  const review = await reviewPullRequest();
 
  if (review) {
    console.log(`\nReview Score: ${review.score}/100`);
    console.log(`Summary: ${review.summary}\n`);
 
    for (const issue of review.issues) {
      const icon =
        issue.severity === "critical" ? "🔴" :
        issue.severity === "warning" ? "🟡" : "🟢";
      console.log(`${icon} [${issue.file}${issue.line ? `:${issue.line}` : ""}] ${issue.message}`);
      if (issue.suggestion) {
        console.log(`   Fix: ${issue.suggestion}`);
      }
    }
  }
}
 
main().catch(console.error);

npx tsx src/review-bot.ts

import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
 
async function interactiveSession() {
  await using session = unstable_v2_createSession({
    model: "claude-sonnet-4-5-20250929",
  });
 
  // First turn
  await session.send("Hello! What TypeScript project am I in?");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
 
  // Second turn — session remembers context
  await session.send("Now list the main dependencies from package.json");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
}
 
interactiveSession().catch(console.error);

// src/test-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function testAgent() {
  const tests = [
    {
      name: "Basic file listing",
      prompt: "List the files in the current directory",
      tools: ["Glob"],
      expectResult: true,
    },
    {
      name: "Code analysis",
      prompt: "Read package.json and tell me the project name",
      tools: ["Read"],
      expectResult: true,
    },
  ];
 
  for (const test of tests) {
    console.log(`\nTest: ${test.name}`);
    let gotResult = false;
 
    for await (const message of query({
      prompt: test.prompt,
      options: {
        allowedTools: test.tools,
        maxTurns: 5,
      },
    })) {
      if ("result" in message) {
        gotResult = true;
        console.log(`  ✓ Result: ${message.result.slice(0, 100)}...`);
      }
    }
 
    if (gotResult === test.expectResult) {
      console.log(`  ✓ PASSED`);
    } else {
      console.log(`  ✗ FAILED`);
    }
  }
}
 
testAgent().catch(console.error);

npm install -g @anthropic-ai/claude-code
claude --version  # Verify installation

// Ensure the tools you need are in the allowed list
options: {
  allowedTools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"],
  permissionMode: "acceptEdits",
}

options: {
  maxTurns: 20,        // Stop after 20 tool calls
  maxBudgetUsd: 0.50,  // Stop if cost exceeds $0.50
}

# Test the MCP server directly
npx -y @modelcontextprotocol/server-github