anthropic-sdk-typescript: Instructions file for Claude Code

Working in this repository

Context for contributors (human or AI) on how this repository is put together, plus the things reviews most often come back to.

This repository's own rules

The generator writes the rest of this file. Rules about this repository's hand-written code go in this section, and a change anywhere else in the file belongs in the generator.

Overview

• The official TypeScript SDK for the Claude API (@anthropic-ai/sdk). Hand-written helpers, streams, tool runners, credentials, and middleware sit on top of the generated code. The platform clients live in packages/{aws,bedrock,foundry,google-cloud,vertex}-sdk and are released as separate packages.
• src/helpers/ and src/tools/ are hand-written, like src/lib/ and examples/. The generator never touches them.
• packages/ is hand-written too, except for each package's package.json and build files: build, tsc-multi.json, the tsconfig*.json files, vitest.config.mts, and tests/vitest-globals.d.ts.
• stream(), parse(), and toolRunner() in src/resources/beta/messages/messages.ts are hand-written.
• Each package has its own CHANGELOG.md, so a PR adds its line to the changelog of the package it changes.
• Describe a public type change in its doc comment and in its changelog line.

Build, test, lint

• The repository is a single pnpm workspace (pnpm-workspace.yaml). Only the root package.json pins packageManager.
• ./scripts/test runs vitest at the root and then in each platform package. Extra arguments go to the root run only, so ./scripts/test tests/lib/parser.test.ts narrows that run and the platform packages' suites still follow.
• Tests talk to the mock server, a mocked fetch, or recorded fixtures. Tests that do call a real endpoint, such as packages/google-cloud-sdk/tests/live.test.ts, are skipped unless ANTHROPIC_LIVE=1 is set.
• pnpm test:ecosystem runs ecosystem-tests/cli.mts against real runtimes and bundlers, including Deno, Bun, Cloudflare Workers, edge, browsers, and TypeScript 5.0. Mark a project knownFailure only when its fix is already tracked.
• toolUseBlock is kept as a @deprecated alias for toolUse. unrestrictedPaths on the environment worker throws when it's passed, because its old behavior can't be honored at all.
• zod is an optional peer dependency, because callers pass their own zod schemas to the helpers, so the SDK has to use the caller's copy of the library.