Agent performance and limits

# In CLI: limit to 15 turns
claude --print --max-turns 15 "Refactor the auth module"

# In TypeScript SDK
const result = await claude({
  prompt: "Refactor the auth module",
  options: { maxTurns: 15 },
});

Main agent (30 turns max)
  └── Review sub-agent (10 turns max)
  └── Tests sub-agent (15 turns max)
       └── Sub-sub-agent? Not recommended.

# In CLI: global session timeout
claude --max-turns 20 "Run the E2E tests"

# In SDK: timeout is managed at the application level
const result = await claude({
  prompt: "Run the full E2E tests",
  options: {
    maxTurns: 20,
    // The SDK waits for the agent to finish
    // Handle the timeout on the application side if needed
  },
});

## Stop criteria
- If you've tried 3 different approaches without success, stop
  and explain what's blocking
- If you re-read the same file more than 2 times, change strategy
- If the same test fails 3 times, flag it as a blocking issue

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  delayMs: number = 2000,
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      console.log(`Attempt ${attempt}/${maxRetries} failed, retrying...`);
      await new Promise((r) => setTimeout(r, delayMs * attempt));
    }
  }
  throw new Error("Unreachable");
}

// Usage
const result = await withRetry(() =>
  claude({
    prompt: "Analyze the logs from the last 24 hours",
    options: { maxTurns: 10 },
  })
);

async function smartRetry(originalPrompt: string): Promise<string> {
  // First attempt with the original prompt
  const first = await claude({
    prompt: originalPrompt,
    options: { maxTurns: 10 },
  });

  // Check the result
  if (isValidResult(first.text)) {
    return first.text;
  }

  // Second attempt with a more detailed prompt
  const second = await claude({
    prompt: `The previous result was unsatisfactory.
      Here's what was missing: ${identifyGaps(first.text)}.
      Start over from scratch with more rigor.
      Original mission: ${originalPrompt}`,
    options: { maxTurns: 15 },
  });

  return second.text;
}

import asyncio
import random
from claude_code_sdk import claude, ClaudeOptions

async def with_backoff(prompt: str, max_retries: int = 5) -> str:
    """Retry with exponential backoff and jitter."""
    for attempt in range(max_retries):
        try:
            result = await claude(
                prompt=prompt,
                options=ClaudeOptions(max_turns=10),
            )
            return result.text
        except Exception as e:
            if "rate_limit" not in str(e) or attempt == max_retries - 1:
                raise
            delay = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limit, retrying in {delay:.1f}s...")
            await asyncio.sleep(delay)
    raise RuntimeError("Maximum retry attempts reached")

import pLimit from "p-limit";

// Maximum 3 agents in parallel
const limit = pLimit(3);

const issues = await getOpenIssues();
const results = await Promise.all(
  issues.map((issue) =>
    limit(() =>
      claude({
        prompt: `Triage issue #${issue.number}: ${issue.title}`,
        options: { maxTurns: 5 },
      })
    )
  )
);

// Budget per agent execution
const MAX_TOKENS_PER_AGENT = 100_000; // ~$0.50 with Sonnet

// Daily budget
const DAILY_TOKEN_BUDGET = 1_000_000; // ~$5.00 with Sonnet

let dailyTokensUsed = 0;

async function budgetedAgent(prompt: string): Promise<string> {
  if (dailyTokensUsed >= DAILY_TOKEN_BUDGET) {
    throw new Error("Daily budget exhausted");
  }

  const result = await claude({
    prompt,
    options: { maxTurns: 10 },
  });

  dailyTokensUsed += result.tokensUsed ?? 0;
  return result.text;
}

interface AgentLog {
  readonly id: string;
  readonly prompt: string;
  readonly startedAt: Date;
  readonly completedAt: Date;
  readonly tokensUsed: number;
  readonly turnsUsed: number;
  readonly result: "success" | "error" | "timeout";
  readonly output: string;
}

async function loggedAgent(prompt: string): Promise<string> {
  const startedAt = new Date();
  const id = crypto.randomUUID();

  try {
    const result = await claude({
      prompt,
      options: { maxTurns: 15 },
    });

    const log: AgentLog = {
      id,
      prompt,
      startedAt,
      completedAt: new Date(),
      tokensUsed: result.tokensUsed ?? 0,
      turnsUsed: result.turnsUsed ?? 0,
      result: "success",
      output: result.text,
    };

    await saveLog(log); // Your logging system
    return result.text;
  } catch (error) {
    const log: AgentLog = {
      id,
      prompt,
      startedAt,
      completedAt: new Date(),
      tokensUsed: 0,
      turnsUsed: 0,
      result: "error",
      output: String(error),
    };
    await saveLog(log);
    throw error;
  }
}

// Alert if an agent costs more than $2
if ((result.tokensUsed ?? 0) > 200_000) {
  await notifySlack(
    "#alerts",
    `Expensive agent detected: ${result.tokensUsed} tokens `
    + `for "${prompt.substring(0, 50)}..."`
  );
}

// Alert if more than 3 failures in 1 hour
const recentErrors = await getRecentErrors(60 * 60 * 1000);
if (recentErrors.length > 3) {
  await notifySlack(
    "#alerts",
    `${recentErrors.length} agent errors in 1h. Check the logs.`
  );
}