diff --git a/README.md b/README.md index 01e8b9b..bed5d83 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Download it and try it out for free! **https://piebald.ai/** > [!important] > **NEW (January 23, 2026): We've added all of Claude Code's ~40 system reminders to this list—see [System Reminders](#system-reminders).** -This repository contains an up-to-date list of all Claude Code's various system prompts and their associated token counts as of **[Claude Code v2.1.144](https://www.npmjs.com/package/@anthropic-ai/claude-code/v/2.1.144) (May 18th, 2026).** It also contains a [**CHANGELOG.md**](./CHANGELOG.md) for the system prompts across 181 versions since v2.0.14. From the team behind [ **Piebald.**](https://piebald.ai/) +This repository contains an up-to-date list of all Claude Code's various system prompts and their associated token counts as of **[Claude Code v2.1.145](https://www.npmjs.com/package/@anthropic-ai/claude-code/v/2.1.145) (May 19th, 2026).** It also contains a [**CHANGELOG.md**](./CHANGELOG.md) for the system prompts across 182 versions since v2.0.14. From the team behind [ **Piebald.**](https://piebald.ai/) **This repository is updated within minutes of each Claude Code release. See the [changelog](./CHANGELOG.md), and follow [@PiebaldAI](https://x.com/PiebaldAI) on X for a summary of the system prompt changes in each release.** @@ -82,13 +82,13 @@ Sub-agents and utilities. - [Agent Prompt: Agent creation architect](./system-prompts/agent-prompt-agent-creation-architect.md) (**1110** tks) - System prompt for creating custom AI agents with detailed specifications. - [Agent Prompt: CLAUDE.md creation](./system-prompts/agent-prompt-claudemd-creation.md) (**384** tks) - System prompt for analyzing codebases and creating CLAUDE.md documentation files. -- [Agent Prompt: Status line setup](./system-prompts/agent-prompt-status-line-setup.md) (**2124** tks) - System prompt for the statusline-setup agent that configures status line display. +- [Agent Prompt: Status line setup](./system-prompts/agent-prompt-status-line-setup.md) (**2433** tks) - System prompt for the statusline-setup agent that configures status line display. #### Slash Commands - [Agent Prompt: /batch slash command](./system-prompts/agent-prompt-batch-slash-command.md) (**1106** tks) - Instructions for orchestrating a large, parallelizable change across a codebase. - [Agent Prompt: /rename auto-generate session name](./system-prompts/agent-prompt-rename-auto-generate-session-name.md) (**103** tks) - Prompt used by /rename (no args) to auto-generate a kebab-case session name from conversation context. -- [Agent Prompt: /review-pr slash command](./system-prompts/agent-prompt-review-pr-slash-command.md) (**211** tks) - System prompt for reviewing GitHub pull requests with code analysis. +- [Agent Prompt: /review-pr slash command](./system-prompts/agent-prompt-review-pr-slash-command.md) (**235** tks) - System prompt for reviewing GitHub pull requests with code analysis. - [Agent Prompt: /schedule slash command](./system-prompts/agent-prompt-schedule-slash-command.md) (**3130** tks) - Guides the user through scheduling, updating, listing, or running remote Claude Code agents on cron triggers via the Anthropic cloud API. - [Agent Prompt: /security-review slash command](./system-prompts/agent-prompt-security-review-slash-command.md) (**2521** tks) - Comprehensive security review prompt for analyzing code changes with focus on exploitable vulnerabilities. @@ -107,7 +107,7 @@ Sub-agents and utilities. - [Agent Prompt: Dream memory pruning](./system-prompts/agent-prompt-dream-memory-pruning.md) (**456** tks) - Instructs an agent to perform a memory pruning pass by deleting stale or invalidated memory files and collapsing duplicates in the memory directory. - [Agent Prompt: General purpose](./system-prompts/agent-prompt-general-purpose.md) (**285** tks) - System prompt for the general-purpose subagent that searches, analyzes, and edits code across a codebase while reporting findings concisely to the caller. - [Agent Prompt: Hook condition evaluator (stop)](./system-prompts/agent-prompt-hook-condition-evaluator-stop.md) (**319** tks) - System prompt for evaluating hook conditions, specifically stop conditions, in Claude Code. -- [Agent Prompt: Managed Agents onboarding flow](./system-prompts/agent-prompt-managed-agents-onboarding-flow.md) (**2613** tks) - Interactive interview script that walks users through configuring a Managed Agent from scratch — selecting tools, skills, files, environment settings — and emits setup and runtime code. +- [Agent Prompt: Managed Agents onboarding flow](./system-prompts/agent-prompt-managed-agents-onboarding-flow.md) (**2663** tks) - Interactive interview script that walks users through configuring a Managed Agent from scratch — selecting tools, skills, files, environment settings — and emits setup and runtime code. - [Agent Prompt: Memory synthesis](./system-prompts/agent-prompt-memory-synthesis.md) (**443** tks) - Subagent that reads persistent memory files and returns a JSON synthesis of only the information relevant to each query, with cited filenames. - [Agent Prompt: Onboarding guide draft share link workflow](./system-prompts/agent-prompt-onboarding-guide-draft-share-link-workflow.md) (**323** tks) - Adds instructions for sharing the draft ONBOARDING.md before review, then updating the same ShareOnboardingGuide link after the user answers the review questions. - [Agent Prompt: Onboarding guide generator](./system-prompts/agent-prompt-onboarding-guide-generator.md) (**1135** tks) - Co-authors a team onboarding guide (ONBOARDING.md) for new Claude Code users by analyzing the creator's usage data, classifying session types, and iterating on the draft collaboratively. @@ -126,7 +126,7 @@ Sub-agents and utilities. The content of various template files embedded in Claude Code. -- [Data: Anthropic CLI](./system-prompts/data-anthropic-cli.md) (**2878** tks) - Reference documentation for the ant CLI covering installation, authentication, command structure, input and output shaping, managed agents workflows, and scripting patterns. +- [Data: Anthropic CLI](./system-prompts/data-anthropic-cli.md) (**2930** tks) - Reference documentation for the ant CLI covering installation, authentication, command structure, input and output shaping, managed agents workflows, and scripting patterns. - [Data: Assistant voice and values template](./system-prompts/data-assistant-voice-and-values-template.md) (**454** tks) - Template content for an assistant.md file describing Claude's voice, values, and communication style. - [Data: Claude API reference — C#](./system-prompts/data-claude-api-reference-c.md) (**4710** tks) - C# SDK reference including installation, client initialization, basic requests, streaming, and tool use. - [Data: Claude API reference — Go](./system-prompts/data-claude-api-reference-go.md) (**4521** tks) - Go SDK reference. @@ -136,30 +136,31 @@ The content of various template files embedded in Claude Code. - [Data: Claude API reference — Ruby](./system-prompts/data-claude-api-reference-ruby.md) (**1094** tks) - Ruby SDK reference including installation, client initialization, basic requests, streaming, and beta tool runner. - [Data: Claude API reference — TypeScript](./system-prompts/data-claude-api-reference-typescript.md) (**3030** tks) - TypeScript SDK reference including installation, client initialization, basic requests, thinking, and multi-turn conversation. - [Data: Claude API reference — cURL](./system-prompts/data-claude-api-reference-curl.md) (**2201** tks) - Raw API reference for Claude API for use with cURL or else Raw HTTP. -- [Data: Claude Platform on AWS reference](./system-prompts/data-claude-platform-on-aws-reference.md) (**1128** tks) - Reference documentation for using the Claude Developer Platform through AWS infrastructure, including AnthropicAWS clients, required region and workspace configuration, SigV4 authentication, and short-term API keys. +- [Data: Claude Platform on AWS reference](./system-prompts/data-claude-platform-on-aws-reference.md) (**1158** tks) - Reference documentation for using the Claude Developer Platform through AWS infrastructure, including AnthropicAWS clients, required region and workspace configuration, SigV4 authentication, and short-term API keys. - [Data: Claude model catalog](./system-prompts/data-claude-model-catalog.md) (**2315** tks) - Catalog of current and legacy Claude models with exact model IDs, aliases, context windows, and pricing. - [Data: Files API reference — Python](./system-prompts/data-files-api-reference-python.md) (**1360** tks) - Python Files API reference including file upload, listing, deletion, and usage in messages. - [Data: Files API reference — TypeScript](./system-prompts/data-files-api-reference-typescript.md) (**797** tks) - TypeScript Files API reference including file upload, listing, deletion, and usage in messages. - [Data: GitHub Actions workflow for @claude mentions](./system-prompts/data-github-actions-workflow-for-claude-mentions.md) (**525** tks) - GitHub Actions workflow template for triggering Claude Code via @claude mentions. - [Data: GitHub App installation PR description](./system-prompts/data-github-app-installation-pr-description.md) (**409** tks) - Template for PR description when installing Claude Code GitHub App integration. - [Data: HTTP error codes reference](./system-prompts/data-http-error-codes-reference.md) (**2399** tks) - Reference for HTTP error codes returned by the Claude API with common causes and handling strategies. -- [Data: Live documentation sources](./system-prompts/data-live-documentation-sources.md) (**3912** tks) - WebFetch URLs for fetching current Claude API and Agent SDK documentation from official sources. +- [Data: Live documentation sources](./system-prompts/data-live-documentation-sources.md) (**4075** tks) - WebFetch URLs for fetching current Claude API and Agent SDK documentation from official sources. - [Data: Managed Agents client patterns](./system-prompts/data-managed-agents-client-patterns.md) (**2685** tks) - Reference guide of common client-side patterns for driving Managed Agent sessions, including stream reconnection, idle-break gating, tool confirmations, interrupts, and custom tools. -- [Data: Managed Agents core concepts](./system-prompts/data-managed-agents-core-concepts.md) (**3741** tks) - Reference documentation for the Managed Agents API covering core concepts (Agents, Sessions, Environments, Containers), lifecycle, versioning, endpoints, and usage patterns. -- [Data: Managed Agents endpoint reference](./system-prompts/data-managed-agents-endpoint-reference.md) (**6548** tks) - Comprehensive reference for Managed Agents API endpoints, SDK methods, request/response schemas, error handling, and rate limits. -- [Data: Managed Agents environments and resources](./system-prompts/data-managed-agents-environments-and-resources.md) (**2950** tks) - Reference documentation covering Managed Agents environments, file resources, GitHub repository mounting, and the Files API with SDK examples. +- [Data: Managed Agents core concepts](./system-prompts/data-managed-agents-core-concepts.md) (**3988** tks) - Reference documentation for the Managed Agents API covering core concepts (Agents, Sessions, Environments, Containers), lifecycle, versioning, endpoints, and usage patterns. +- [Data: Managed Agents endpoint reference](./system-prompts/data-managed-agents-endpoint-reference.md) (**6888** tks) - Comprehensive reference for Managed Agents API endpoints, SDK methods, request/response schemas, error handling, and rate limits. +- [Data: Managed Agents environments and resources](./system-prompts/data-managed-agents-environments-and-resources.md) (**3191** tks) - Reference documentation covering Managed Agents environments, file resources, GitHub repository mounting, and the Files API with SDK examples. - [Data: Managed Agents events and steering](./system-prompts/data-managed-agents-events-and-steering.md) (**2747** tks) - Reference guide for sending and receiving events on managed agent sessions, including streaming, polling, reconnection, message queuing, interrupts, and event payload details. - [Data: Managed Agents memory stores reference](./system-prompts/data-managed-agents-memory-stores-reference.md) (**2780** tks) - Reference documentation for Managed Agents memory stores, including store creation, session attachment, FUSE mounts, memory CRUD, concurrency, versions, redaction, and endpoint paths. - [Data: Managed Agents multiagent sessions](./system-prompts/data-managed-agents-multiagent-sessions.md) (**1839** tks) - Reference documentation for Managed Agents multiagent sessions, including coordinator rosters, threads, session stream events, subagent tool permissions, and pitfalls. - [Data: Managed Agents outcomes](./system-prompts/data-managed-agents-outcomes.md) (**1772** tks) - Reference documentation for Managed Agents outcomes, including user.define_outcome events, rubrics, outcome evaluation events, deliverables, and interaction rules. -- [Data: Managed Agents overview](./system-prompts/data-managed-agents-overview.md) (**2478** tks) - Provides the agent with a comprehensive overview of the Managed Agents API architecture, mandatory agent-then-session flow, beta headers, documentation reading guide, and common pitfalls. +- [Data: Managed Agents overview](./system-prompts/data-managed-agents-overview.md) (**2659** tks) - Provides the agent with a comprehensive overview of the Managed Agents API architecture, mandatory agent-then-session flow, beta headers, documentation reading guide, and common pitfalls. - [Data: Managed Agents reference — Python](./system-prompts/data-managed-agents-reference-python.md) (**2843** tks) - Reference guide for using the Anthropic Python SDK to create and manage agents, sessions, environments, streaming, custom tools, files, and MCP servers. - [Data: Managed Agents reference — TypeScript](./system-prompts/data-managed-agents-reference-typescript.md) (**2825** tks) - Reference guide for using the Anthropic TypeScript SDK to create and manage agents, sessions, environments, streaming, custom tools, file uploads, and MCP server integration. -- [Data: Managed Agents reference — cURL](./system-prompts/data-managed-agents-reference-curl.md) (**2641** tks) - Provides cURL and raw HTTP request examples for the Managed Agents API including environment, agent, and session lifecycle operations. -- [Data: Managed Agents tools and skills](./system-prompts/data-managed-agents-tools-and-skills.md) (**3844** tks) - Reference documentation covering the Managed Agents SDK's tool types (agent toolset, MCP, custom), permission policies, vault credential management, and skills API for building specialized agents. +- [Data: Managed Agents reference — cURL](./system-prompts/data-managed-agents-reference-curl.md) (**2658** tks) - Provides cURL and raw HTTP request examples for the Managed Agents API including environment, agent, and session lifecycle operations. +- [Data: Managed Agents self-hosted sandboxes](./system-prompts/data-managed-agents-self-hosted-sandboxes.md) (**2855** tks) - Reference documentation for running Managed Agents tool execution in self-hosted infrastructure, including environment setup, workers, webhook-driven wake, orchestration, monitoring, credentials, and security responsibilities. +- [Data: Managed Agents tools and skills](./system-prompts/data-managed-agents-tools-and-skills.md) (**4101** tks) - Reference documentation covering the Managed Agents SDK's tool types (agent toolset, MCP, custom), permission policies, vault credential management, and skills API for building specialized agents. - [Data: Managed Agents webhooks](./system-prompts/data-managed-agents-webhooks.md) (**1439** tks) - Reference documentation for Managed Agents webhooks, including endpoint registration, signature verification, payload envelopes, supported event types, delivery behavior, and pitfalls. - [Data: Message Batches API reference — Python](./system-prompts/data-message-batches-api-reference-python.md) (**1635** tks) - Python Batches API reference including batch creation, status polling, and result retrieval at 50% cost. -- [Data: Prompt Caching — Design & Optimization](./system-prompts/data-prompt-caching-design-optimization.md) (**2664** tks) - Document on how to design prompt-building code for effective caching, including placement patterns and anti-patterns. +- [Data: Prompt Caching — Design & Optimization](./system-prompts/data-prompt-caching-design-optimization.md) (**3438** tks) - Document on how to design prompt-building code for effective caching, including placement patterns and anti-patterns. - [Data: Streaming reference — Python](./system-prompts/data-streaming-reference-python.md) (**1660** tks) - Python streaming reference including sync/async streaming and handling different content types. - [Data: Streaming reference — TypeScript](./system-prompts/data-streaming-reference-typescript.md) (**1612** tks) - TypeScript streaming reference including basic streaming and handling different content types. - [Data: Tool use concepts](./system-prompts/data-tool-use-concepts.md) (**4356** tks) - Conceptual foundations of tool use with the Claude API including tool definitions, tool choice, and best practices. @@ -266,7 +267,6 @@ Text for large system reminders. - [System Reminder: Plan file reference](./system-prompts/system-reminder-plan-file-reference.md) (**62** tks) - Reference to an existing plan file. - [System Reminder: Plan mode approval tool enforcement](./system-prompts/system-reminder-plan-mode-approval-tool-enforcement.md) (**236** tks) - Requires plan mode turns to end with either AskUserQuestion for clarification or ExitPlanMode for plan approval, and forbids asking for approval any other way. - [System Reminder: Plan mode is active (5-phase)](./system-prompts/system-reminder-plan-mode-is-active-5-phase.md) (**927** tks) - Enhanced plan mode system reminder with parallel exploration and multi-agent planning. -- [System Reminder: Plan mode is active (iterative)](./system-prompts/system-reminder-plan-mode-is-active-iterative.md) (**936** tks) - Iterative plan mode system reminder for main agent with user interviewing workflow. - [System Reminder: Plan mode is active (subagent)](./system-prompts/system-reminder-plan-mode-is-active-subagent.md) (**307** tks) - Simplified plan mode system reminder for sub agents. - [System Reminder: Plan mode re-entry](./system-prompts/system-reminder-plan-mode-re-entry.md) (**236** tks) - System reminder sent when the user enters Plan mode after having previously exited it either via shift+tab or by approving Claude's plan. - [System Reminder: Previously invoked skills](./system-prompts/system-reminder-previously-invoked-skills.md) (**131** tks) - Restores skills invoked before conversation compaction as context only, warning not to re-execute their setup actions or treat prior inputs as current instructions. @@ -289,7 +289,7 @@ Text for large system reminders. - [Tool Description: Computer](./system-prompts/tool-description-computer.md) (**161** tks) - Main description for the Chrome browser computer automation tool. - [Tool Description: CronCreate](./system-prompts/tool-description-croncreate.md) (**850** tks) - Describes the CronCreate tool for enqueuing one-shot or recurring cron-based jobs with jitter and off-minute scheduling guidance. - [Tool Description: Edit](./system-prompts/tool-description-edit.md) (**202** tks) - Tool for performing exact string replacements in files. -- [Tool Description: EnterPlanMode](./system-prompts/tool-description-enterplanmode.md) (**878** tks) - Tool description for entering plan mode to explore and design implementation approaches. +- [Tool Description: EnterPlanMode](./system-prompts/tool-description-enterplanmode.md) (**881** tks) - Tool description for entering plan mode to explore and design implementation approaches. - [Tool Description: EnterWorktree](./system-prompts/tool-description-enterworktree.md) (**604** tks) - Tool description for the EnterWorktree tool. - [Tool Description: ExitPlanMode](./system-prompts/tool-description-exitplanmode.md) (**417** tks) - Description for the ExitPlanMode tool, which presents a plan dialog for the user to approve. - [Tool Description: ExitWorktree](./system-prompts/tool-description-exitworktree.md) (**527** tks) - Roughly, the reverse of the ExitWorktree. @@ -388,13 +388,22 @@ Built-in skill prompts for specialized tasks. - [Skill: /stuck slash command](./system-prompts/skill-stuck-slash-command.md) (**964** tks) - Diagnozse frozen or slow Claude Code sessions. - [Skill: Agent Design Patterns](./system-prompts/skill-agent-design-patterns.md) (**1974** tks) - Reference guide covering decision heuristics for building agents on the Claude API, including tool surface design, context management, caching strategies, and composing tool calls. - [Skill: Build with Claude API (reference guide)](./system-prompts/skill-build-with-claude-api-reference-guide.md) (**655** tks) - Template for presenting language-specific reference documentation with quick task navigation. -- [Skill: Building LLM-powered applications with Claude](./system-prompts/skill-building-llm-powered-applications-with-claude.md) (**8833** tks) - Guides Claude in building LLM-powered applications using the Anthropic SDK, covering language detection, API surface selection (Claude API vs Managed Agents), model defaults, thinking/effort configuration, and language-specific documentation reading. +- [Skill: Building LLM-powered applications with Claude](./system-prompts/skill-building-llm-powered-applications-with-claude.md) (**8875** tks) - Guides Claude in building LLM-powered applications using the Anthropic SDK, covering language detection, API surface selection (Claude API vs Managed Agents), model defaults, thinking/effort configuration, and language-specific documentation reading. - [Skill: Computer Use MCP](./system-prompts/skill-computer-use-mcp.md) (**1206** tks) - Instructions for using computer-use MCP tools including tool selection tiers, app access tiers, link safety, and financial action restrictions. - [Skill: Create verifier skills](./system-prompts/skill-create-verifier-skills.md) (**2580** tks) - Prompt for creating verifier skills for the Verify agent to automatically verify code changes. - [Skill: Debugging](./system-prompts/skill-debugging.md) (**417** tks) - Instructions for debugging an issue that the user is encountering in the Claude Code session. - [Skill: Dynamic pacing loop execution](./system-prompts/skill-dynamic-pacing-loop-execution.md) (**598** tks) - Step-by-step instructions for executing a dynamic pacing loop that runs tasks, arms persistent monitors for event-gated waits, schedules fallback heartbeat ticks, and handles task notifications. - [Skill: Generate permission allowlist from transcripts](./system-prompts/skill-generate-permission-allowlist-from-transcripts.md) (**2338** tks) - Analyzes session transcripts to extract frequently used read-only tool-call patterns and adds them to the project's .claude/settings.json permission allowlist to reduce permission prompts. - [Skill: Model migration guide](./system-prompts/skill-model-migration-guide.md) (**18833** tks) - Step-by-step instructions for migrating existing code to newer Claude models, covering breaking changes, deprecated parameters, per-SDK syntax, prompt-behavior shifts, and migration checklists. +- [Skill: Run CLI tool example](./system-prompts/skill-run-cli-tool-example.md) (**499** tks) - Example file for the Run app skill showing how to document building, invoking, and testing a CLI tool. +- [Skill: Run Electron desktop GUI app example](./system-prompts/skill-run-electron-desktop-gui-app-example.md) (**4625** tks) - Example file for the Run app skill showing how to launch an Electron desktop app under xvfb and drive it through a Playwright REPL driver. +- [Skill: Run TUI interactive terminal app example](./system-prompts/skill-run-tui-interactive-terminal-app-example.md) (**1004** tks) - Example file for the Run app skill showing how to drive an interactive terminal app with tmux, readiness polling, pane capture, key references, and cleanup. +- [Skill: Run app](./system-prompts/skill-run-app.md) (**999** tks) - Skill for launching and driving the current project's app through its real runtime surface using project-specific run skills or fallback patterns. +- [Skill: Run browser-driven web app example](./system-prompts/skill-run-browser-driven-web-app-example.md) (**1002** tks) - Example file for the Run app skill showing how to start a web dev server, drive it with chromium-cli, capture screenshots, and document app-specific gotchas. +- [Skill: Run library SDK example](./system-prompts/skill-run-library-sdk-example.md) (**653** tks) - Example file for the Run app skill showing how to document building, testing, and smoke-checking a library or SDK at its public package boundary. +- [Skill: Run skill generator](./system-prompts/skill-run-skill-generator.md) (**4681** tks) - Skill for authoring or improving a project-specific run skill that documents verified build, launch, runtime driving, and troubleshooting steps. +- [Skill: Run skill template](./system-prompts/skill-run-skill-template.md) (**1216** tks) - Template file for the Run skill generator showing the frontmatter and section structure for a project-specific run skill. +- [Skill: Run web server API example](./system-prompts/skill-run-web-server-api-example.md) (**890** tks) - Example file for the Run app skill showing how to document a server or API lifecycle with background launch, readiness checks, curl verification, and shutdown. - [Skill: Schedule recurring cron and execute immediately (compact)](./system-prompts/skill-schedule-recurring-cron-and-execute-immediately-compact.md) (**173** tks) - Instructions for creating a recurring cron job, confirming the schedule with the user, and immediately executing the parsed prompt without waiting for the first cron fire. - [Skill: Schedule recurring cron and run immediately](./system-prompts/skill-schedule-recurring-cron-and-run-immediately.md) (**271** tks) - Converts an interval to a cron expression, schedules a recurring task via the cron creation tool, confirms to the user, and immediately executes the task without waiting for the first cron fire. - [Skill: Simplify](./system-prompts/skill-simplify.md) (**937** tks) - Instructions for simplifying code. diff --git a/system-prompts/agent-prompt-managed-agents-onboarding-flow.md b/system-prompts/agent-prompt-managed-agents-onboarding-flow.md index 955d73a..5c35a17 100644 --- a/system-prompts/agent-prompt-managed-agents-onboarding-flow.md +++ b/system-prompts/agent-prompt-managed-agents-onboarding-flow.md @@ -1,7 +1,7 @@ # Managed Agents — Onboarding Flow @@ -13,11 +13,11 @@ Use this when a user wants to set up a Managed Agent from scratch. Three steps: --- -Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you. +Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute (or, with a `self_hosted` environment, your own worker runs the tools — see `shared/managed-agents-self-hosted-sandboxes.md`). You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you. **What you supply:** - **An agent config** — tools, skills, model, system prompt. Reusable and versioned. -- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents. +- **An environment config** — the sandbox your agent's tools execute in (`cloud`: networking, packages; or `self_hosted`: your own infra). Reusable across agents. Each run of the agent is a **session**. diff --git a/system-prompts/agent-prompt-review-pr-slash-command.md b/system-prompts/agent-prompt-review-pr-slash-command.md index b8dd3e1..3530767 100644 --- a/system-prompts/agent-prompt-review-pr-slash-command.md +++ b/system-prompts/agent-prompt-review-pr-slash-command.md @@ -1,7 +1,7 @@ @@ -9,7 +9,7 @@ variables: You are an expert code reviewer. Follow these steps: 1. If no PR number is provided in the args, run `gh pr list` to show open PRs - 2. If a PR number is provided, run `gh pr view ` to get PR details + 2. If a PR number is provided, run `gh pr view --json title,body,author,baseRefName,headRefName,state,additions,deletions,changedFiles,labels` to get PR details 3. Run `gh pr diff ` to get the diff 4. Analyze the changes and provide a thorough code review that includes: - Overview of what the PR does diff --git a/system-prompts/agent-prompt-status-line-setup.md b/system-prompts/agent-prompt-status-line-setup.md index c427cd9..177912f 100644 --- a/system-prompts/agent-prompt-status-line-setup.md +++ b/system-prompts/agent-prompt-status-line-setup.md @@ -1,7 +1,7 @@ # Anthropic CLI (`ant`) @@ -41,7 +41,7 @@ Auth is `ANTHROPIC_API_KEY` from the environment. Override the host with `ANTHRO ant [:] [flags] ``` -Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under `beta:` — the CLI auto-sends the right `anthropic-beta` header, so don't pass it yourself unless overriding with `--beta
`. +Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under `beta:` — the CLI auto-sends the right `anthropic-beta` header, so don't pass it yourself unless overriding with `--beta
`. For self-hosted environments, `ant beta:worker poll/run` and `ant beta:environments:work stats/stop` drive and monitor the work queue — see `shared/managed-agents-self-hosted-sandboxes.md`. ```sh ant models list diff --git a/system-prompts/data-claude-platform-on-aws-reference.md b/system-prompts/data-claude-platform-on-aws-reference.md index e3dd50a..e016bef 100644 --- a/system-prompts/data-claude-platform-on-aws-reference.md +++ b/system-prompts/data-claude-platform-on-aws-reference.md @@ -1,11 +1,11 @@ # Claude Platform on AWS -**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity**: Managed Agents, server-side tools, batches, Files, and every feature in this skill work the same way. Model IDs are the bare first-party strings (`{{OPUS_ID}}`, `{{SONNET_ID}}`) — **no provider prefix**. +**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity**: Managed Agents, server-side tools, batches, Files, and every feature in this skill work the same way (**except self-hosted sandboxes** — `config:{type:"self_hosted"}` is not available here; use `cloud`). Model IDs are the bare first-party strings (`{{OPUS_ID}}`, `{{SONNET_ID}}`) — **no provider prefix**. > **Not the same as Amazon Bedrock.** Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset, `anthropic.`-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem. diff --git a/system-prompts/data-live-documentation-sources.md b/system-prompts/data-live-documentation-sources.md index 865b8af..0299150 100644 --- a/system-prompts/data-live-documentation-sources.md +++ b/system-prompts/data-live-documentation-sources.md @@ -1,7 +1,7 @@ # Live Documentation Sources @@ -90,6 +90,8 @@ Use these when a managed-agents binding, behavior, or wire-level detail isn't co | Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" | | Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" | | Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" | +| Self-Hosted Sandboxes | `https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes.md` | "Extract config:{type:self_hosted}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run/run_one, beta_agent_toolset, ant beta:worker poll/run, webhook-driven wake" | +| Self-Hosted Sandboxes — Security | `https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security.md` | "Extract what the customer owns (hardening, egress, key custody, trust boundaries) vs what Anthropic cannot do" | | Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" | | Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" | | Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" | diff --git a/system-prompts/data-managed-agents-core-concepts.md b/system-prompts/data-managed-agents-core-concepts.md index 2f68cbf..495c155 100644 --- a/system-prompts/data-managed-agents-core-concepts.md +++ b/system-prompts/data-managed-agents-core-concepts.md @@ -1,7 +1,7 @@ # Managed Agents — Core Concepts @@ -237,3 +237,21 @@ session = client.beta.sessions.create( ) ``` +### Updating the agent configuration mid-session + +`sessions.update()` can change `agent.tools`, `agent.mcp_servers` (including permission policies), and `vault_ids` on an **existing** session. This is a **session-local override** — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are **full replacements**; to append one tool, `GET` the session, modify, and `POST` back. The session must be `idle` — interrupt first if running. + +```python +client.beta.sessions.update( + session.id, + agent={ + "tools": [ + {"type": "agent_toolset_20260401"}, + {"type": "mcp_toolset", "mcp_server_name": "linear"}, + ], + "mcp_servers": [{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}], + }, + vault_ids=["vlt_..."], +) +``` + diff --git a/system-prompts/data-managed-agents-endpoint-reference.md b/system-prompts/data-managed-agents-endpoint-reference.md index 069f942..2d16b39 100644 --- a/system-prompts/data-managed-agents-endpoint-reference.md +++ b/system-prompts/data-managed-agents-endpoint-reference.md @@ -1,7 +1,7 @@ # Managed Agents — Endpoint Reference @@ -26,6 +26,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi | Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` | | Agent Versions | `agents.versions.list` | `Agents.Versions.List` | | Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Environment Work (self-hosted) | `environments.work.poller` / `stats` / `stop` | See `shared/managed-agents-self-hosted-sandboxes.md` | | Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | | Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` | | Session Threads | `sessions.threads.list` / `retrieve` / `archive`; `sessions.threads.events.list` / `stream` | `Sessions.Threads.List` / `Get` / `Archive`; `Sessions.Threads.Events.List` / `StreamEvents` | @@ -40,6 +41,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi - Agents and Session Threads have **no delete** — only `archive`. Archive is **permanent**: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both `delete` and `archive`; Session Resources, Files, Skills, and Memories are `delete`-only; Memory Versions have neither — only `redact`. - Session resources use `add` (not `create`). - Go's event stream is `StreamEvents` (not `Stream`). +- The self-hosted worker is **not** under `client.beta.*` — it's `EnvironmentWorker` from `anthropic.lib.environments` / `@anthropic-ai/sdk/helpers/beta/environments`; only `environments.work.poller/stats/stop` are client methods. **Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`). @@ -67,7 +69,7 @@ All resources are under the `beta` namespace. Python and TypeScript share identi | `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) | | `POST` | `/v1/sessions` | CreateSession | Create a new session | | `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details | -| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title | +| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session `metadata`/`title`, or `agent.tools`/`agent.mcp_servers`/`vault_ids` (session-local override; session must be `idle`). See `shared/managed-agents-core.md` → Updating the agent configuration mid-session. | | `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session | | `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session | @@ -111,6 +113,10 @@ Per-subagent event streams in multiagent sessions. See `shared/managed-agents-mu | `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment | | `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. | | `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. | +| `GET` | `/v1/environments/{environment_id}/work/stats` | WorkQueueStats | Self-hosted work-queue depth/pending/workers. `x-api-key` auth. See `shared/managed-agents-self-hosted-sandboxes.md`. | +| `POST` | `/v1/environments/{environment_id}/work/{work_id}/stop` | StopWork | Self-hosted: stop a claimed work item. `x-api-key` auth. | + +For `type: "self_hosted"`, `config` is the bare `{"type": "self_hosted"}` — `networking` and `packages` do not apply. ## Vaults @@ -275,7 +281,7 @@ Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surfa "name": "string (required)", "description": "string (optional)", "config": { - "type": "cloud", + "type": "cloud | self_hosted", "networking": { "type": "unrestricted | limited (union — see SDK types)" }, diff --git a/system-prompts/data-managed-agents-environments-and-resources.md b/system-prompts/data-managed-agents-environments-and-resources.md index 8bf82b1..7b6dd7f 100644 --- a/system-prompts/data-managed-agents-environments-and-resources.md +++ b/system-prompts/data-managed-agents-environments-and-resources.md @@ -1,7 +1,7 @@ # Managed Agents — Environments & Resources @@ -13,21 +13,25 @@ Creating a session requires an `environment_id`. Environments are **reusable con ### Networking -| Network Policy | Description | -| ------------------------------- | ------------------------------------------------------------- | -| `unrestricted` | Full egress (except legal blocklist) | -| `package_managers_and_custom` | Package managers + custom `allowed_hosts` | +| Network Policy | Description | +| ---------------- | ------------------------------------------------------------- | +| `unrestricted` | Full egress (except legal blocklist) | +| `limited` | Deny-by-default; opt in via `allowed_hosts` / `allow_package_managers` / `allow_mcp_servers` | ```json { "networking": { - "type": "package_managers_and_custom", + "type": "limited", + "allow_package_managers": true, + "allow_mcp_servers": true, "allowed_hosts": ["api.example.com"] } } ``` -**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail. +All three `limited` fields are optional. `allow_package_managers` (default `false`) permits PyPI/npm/etc.; `allow_mcp_servers` (default `false`) permits the agent's configured MCP server endpoints without listing them in `allowed_hosts`. + +**MCP caveat:** Under `limited` networking, either set `allow_mcp_servers: true` or add each MCP server domain to `allowed_hosts`. Otherwise the container can't reach them and tools silently fail. ### Creating an environment @@ -43,6 +47,10 @@ const env = await client.beta.environments.create({ }); ``` +### Self-hosted sandboxes + +To run tool execution in **your own infrastructure** instead of Anthropic's, set `config: {type: "self_hosted"}` — the agent loop stays on Anthropic's side, but `bash` / file ops / code execute in a container you control via an outbound-polling worker. The `networking` block does not apply (you control egress). Resource mounting (`file`, `github_repository`) and memory stores behave differently — see `shared/managed-agents-self-hosted-sandboxes.md` for the worker, credentials, and cloud-vs-self-hosted comparison. + ### Environment CRUD | Operation | Method | Path | Notes | diff --git a/system-prompts/data-managed-agents-overview.md b/system-prompts/data-managed-agents-overview.md index d592e00..1e4624c 100644 --- a/system-prompts/data-managed-agents-overview.md +++ b/system-prompts/data-managed-agents-overview.md @@ -1,7 +1,7 @@ # Managed Agents — Overview @@ -22,7 +22,7 @@ If you're about to write `sessions.create()` with `model`, `system`, or `tools` **When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`. -**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. +**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. To change `tools`/`mcp_servers`/`vault_ids` on **one running session** without touching the agent object, use `sessions.update()` — see `shared/managed-agents-core.md` → Updating the agent configuration mid-session. ## Beta Headers @@ -54,6 +54,7 @@ Managed Agents is in beta. The SDK sets required beta headers automatically: | Define an outcome / rubric-graded iterate loop | `shared/managed-agents-outcomes.md` — `user.define_outcome` event, grader, `span.outcome_evaluation_*` events | | Coordinate multiple agents / subagents / threads | `shared/managed-agents-multiagent.md` — `multiagent: {type: "coordinator", agents: [...]}` on the agent, session threads, cross-posted tool confirmations | | Set up environments | `shared/managed-agents-environments.md` + language file | +| Run tool execution in your own infra / VPC (self-hosted sandbox) | `shared/managed-agents-self-hosted-sandboxes.md` — `config:{type:"self_hosted"}`, `ANTHROPIC_ENVIRONMENT_KEY`, `EnvironmentWorker.run()` / `ant beta:worker poll` | | Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) | | Give agents persistent memory across sessions | `shared/managed-agents-memory.md` — memory stores, `memory_store` session resource, preconditions, versions/redact | | Define agents/environments as version-controlled YAML; drive the API from the shell | `shared/anthropic-cli.md` — `ant beta:agents create < agent.yaml`, `--transform`, `@file` inlining | @@ -69,5 +70,5 @@ Managed Agents is in beta. The SDK sets required beta headers automatically: - **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream. - **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. - **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message. -- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type. +- **Environment `config.type` is `"cloud"` or `"self_hosted"`** — `cloud` runs the container on Anthropic's infrastructure; `self_hosted` moves tool execution to your own (see `shared/managed-agents-self-hosted-sandboxes.md`). - **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**. diff --git a/system-prompts/data-managed-agents-reference-curl.md b/system-prompts/data-managed-agents-reference-curl.md index 4c4a7b2..801e8aa 100644 --- a/system-prompts/data-managed-agents-reference-curl.md +++ b/system-prompts/data-managed-agents-reference-curl.md @@ -1,7 +1,7 @@ # Managed Agents — cURL / Raw HTTP @@ -47,7 +47,9 @@ curl -X POST https://api.anthropic.com/v1/environments \ "config": { "type": "cloud", "networking": { - "type": "package_managers_and_custom", + "type": "limited", + "allow_package_managers": true, + "allow_mcp_servers": true, "allowed_hosts": ["api.example.com"] } } diff --git a/system-prompts/data-managed-agents-self-hosted-sandboxes.md b/system-prompts/data-managed-agents-self-hosted-sandboxes.md new file mode 100644 index 0000000..d108dfa --- /dev/null +++ b/system-prompts/data-managed-agents-self-hosted-sandboxes.md @@ -0,0 +1,178 @@ + +# Managed Agents — Self-Hosted Sandboxes + +With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control** — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with `config.type: "cloud"`, where Anthropic runs the container. Connectivity is **outbound-only**: your worker long-polls Anthropic's work queue; Anthropic never dials into your network. + +## Flow + +``` +1. Create environment: config: {type: "self_hosted"} → env_... +2. Generate environment key (Console, on the environment page) → sk-ant-oat01-... as ANTHROPIC_ENVIRONMENT_KEY +3. Run a worker: EnvironmentWorker.run() or ant beta:worker poll +4. Sessions reference environment_id=env_... exactly as for cloud +``` + +## Create the environment + +```python +client = anthropic.Anthropic() + +environment = client.beta.environments.create( + name="self-hosted", config={"type": "self_hosted"} +) +``` + +`{"type": "self_hosted"}` is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side. + +## Run a worker — SDK (primary path) + +`EnvironmentWorker` wraps the poll → dispatch → tool-execute loop. `.run()` is the always-on loop; `.run_one()` / `.runOne()` handles one work item (for webhook-driven wake). + +**Python — always-on:** + +```python +import asyncio +import os +from anthropic import AsyncAnthropic +from anthropic.lib.environments import EnvironmentWorker + + +async def main() -> None: + environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] + environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] + async with AsyncAnthropic(auth_token=environment_key) as client: + await EnvironmentWorker( + client, + environment_id=environment_id, + environment_key=environment_key, + workdir="/workspace", + ).run() + + +asyncio.run(main()) +``` + +**TypeScript — always-on:** + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments"; + +const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; +const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; +const client = new Anthropic({ authToken: environmentKey }); +const ctrl = new AbortController(); +process.once("SIGTERM", () => ctrl.abort()); + +await new EnvironmentWorker({ + client, + environmentId, + environmentKey, + workdir: "/workspace", + signal: ctrl.signal +}).run(); +``` + +**Customizing tools.** `EnvironmentWorker` runs the built-in toolset by default. To add or replace tools, use `AgentToolContext(workdir=, client=, session_id=)` with `beta_agent_toolset(env)` / `betaAgentToolset(env)` and pass the resulting tools to the lower-level `tool_runner()`. Skills attached to the agent are downloaded into `{workdir}/skills//` before tool calls begin (`AgentToolContext` handles this when given `client` and `session_id`). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions. + +> **Runtime deps:** the SDK helpers require `/bin/bash` at that exact path. The TypeScript SDK additionally requires `unzip`, `tar`, and Node.js 22+. These are resolved at fixed paths and do **not** respect `PATH` overrides. + +## Run a worker — `ant` CLI (fixed tools) + +The `ant` CLI ships a worker with the fixed built-in toolset (`bash`, `read`, `write`, `edit`, `glob`, `grep`). Install per `shared/anthropic-cli.md`, then: + +```sh +export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-... +ant beta:worker poll --environment-id env_... --workdir /workspace +``` + +- `--workdir` is the directory tools operate in (default `.`); tool calls are sandboxed to it. +- `--environment-key` overrides the env var. +- `--on-work