Home › LLM apps & agents › Claude Agent SDK CLAUDE.md

Claude Agent SDK CLAUDE.md

CLAUDE.md for building agents with the Claude Agent SDK (Python/TypeScript): options, tools, permissions, and hooks.

Claude Code (CLAUDE.md)LLM apps & agents

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md: Claude Agent SDK app

## Packages
- Python: `claude-agent-sdk` (`from claude_agent_sdk import query, ClaudeSDKClient, ClaudeAgentOptions`). TypeScript: `@anthropic-ai/claude-agent-sdk`. Pin the version; it releases often, so check the changelog before upgrading.
- `ANTHROPIC_API_KEY` (or the configured cloud provider credentials) from env only.

## Building the agent
- One-shot tasks use `query(prompt=..., options=...)`; multi-turn sessions use `ClaudeSDKClient` as an async context manager.
- Configure everything through `ClaudeAgentOptions`: `system_prompt`, `allowed_tools` (explicit list), `disallowed_tools`, `permission_mode`, `cwd`, `max_turns`, `mcp_servers`. Keep options in one `agent/config.py`.
- Least privilege: start with read-only tools (`Read`, `Grep`, `Glob`). Add `Edit`/`Write`/`Bash` only if the task needs them, and scope `cwd` to a workspace directory.
- Never use a bypass-all permission mode in production. Use a `can_use_tool` callback or `PreToolUse` hooks to block dangerous commands (`rm -rf`, `git push`, network writes) and to require approval.
- Custom tools: define with `@tool(name, description, schema)` and expose via `create_sdk_mcp_server(...)`; refer to them as `mcp__<server>__<tool>` in `allowed_tools`.
- Use subagents (`agents=` option) for focused subtasks with their own tools and prompts.

## Handling output
- Iterate messages; handle `AssistantMessage`, tool use, and the final `ResultMessage` (cost, usage, errors). Log `total_cost_usd` and turn counts.
- Catch SDK errors (`CLINotFoundError`, `ProcessError`) and fail clearly.

## Tests
Unit-test tool functions and hooks directly; run full-agent tests only behind a flag (`RUN_AGENT_E2E=1`) because they cost money.