Claude Code Restored Source Tree

Use the client.messages.stream context manager to receive text incrementally as it is generated. Iterate over stream.text_stream to access the incoming text chunks. This is ideal for chat interfaces or terminal UIs where you want to provide immediate feedback to the user.

from anthropic import Anthropic

client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a short release note."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Follow these best practices when implementing error handling for Anthropic API integrations:

• Correlation: Always log the Anthropic request ID when available to allow for correlation of failed requests.
• Logging: Surface response body details in server logs for debugging, but ensure full prompts or secrets are not leaked to end-users.
• Idempotency: Ensure retries are idempotent, particularly for batch polling and file-based workflows.
• Error Distinction: Explicitly distinguish between validation failures (request-specific) and transport failures (network/service-specific) in your logic paths.

When a change affects a CLI command, flag, formatter, or local workflow, use this verification pattern to ensure correctness:

1. Run the narrowest command that hits the specific changed code path.
2. Test nearby flags if the change involved argument parsing or help text.
3. Validate both output and exit behavior (ensure the command exits with the expected status code and produces the expected text).

This pattern is particularly useful for verifying that a restored entrypoint reaches the real CLI path rather than a stub.

bun run version
bun run dev --help

To improve security and reliability, follow the principle of least privilege by providing the smallest possible tool surface required for a task. Avoid giving write-capable tools unless the task explicitly requires edits.

const agent = new Agent({
  model: 'claude-sonnet-4-6',
  systemPrompt: 'Review code and report findings only.',
  allowedTools: ['Read', 'Glob', 'Grep'],
})

The Verify skill is used when a task requires exercising a code change to ensure it works as intended. The goal is to produce a short verification result grounded in actual execution rather than inference.

Workflow

1. Identify the changed surface area.
2. Pick the smallest realistic verification path.
3. Run the relevant command or request flow.
4. Capture the observable result (e.g., exit status, key output, HTTP status, or changed behavior).
5. Report what passed, what was not verified, and any remaining risk.

Rules for Verification

• Do not claim success without running an actual command or process.
• Prefer focused, narrow checks over broad smoke tests.
• If no formal test target exists, use the nearest runnable workflow.
• If environment limits block a check, state this explicitly.
• Include exact commands used to allow for repeatable verification.

Follow these guidelines when building tools for Claude:

Do:

• Keep tool schemas narrow and explicit.
• Validate tool input before execution.
• Return structured, minimal results instead of raw logs.
• Handle authorization and side-effect checks within your application code rather than relying on the model prompt.

Avoid:

• Exposing shell or network primitives unless absolutely necessary.
• Using vague tool names or overly broad schemas.
• Skipping retries and timeout handling for real-world integrations.

When building with the Anthropic Python SDK, follow these practical guidelines:

• Model Selection: Prefer current stable model aliases or exact IDs supported by your application.
• Prompt Caching: Keep long-lived static context at the start of the request to leverage prompt caching.
• Latency: Use streaming for long outputs or latency-sensitive user interfaces.
• Large Jobs: Use the Batches API for large asynchronous processing jobs.
• File Reuse: Use the Files API when the same document or image needs to be referenced across multiple requests.
• Use Cases: This SDK is recommended when you need raw messages.create(...) access, require sync/async Python clients, or are implementing streaming, tool use, batches, or the Files API directly.

Install the SDK using pip. Note that the SDK communicates with a local Claude Code CLI, so the machine running your Python code must have Claude Code installed and authenticated.

pip install claude-agent-sdk

When a question involves information that could be stale, follow this protocol:

1. Prefer the official documentation page over internal memory.
2. Quote the relevant section briefly.
3. Summarize the remaining details.
4. Provide a link to the specific page used as a reference.

To ensure stable agent sessions, follow these best practices:

• Explicitly set the cwd (current working directory).
• Set permission modes deliberately.
• Always close the ClaudeSDKClient within a finally block.
• Surface specific errors to the caller, including CLINotFoundError, connection errors, and permission denials.