Replace search skill with mem-search (#91)
* feat: add mem-search skill with progressive disclosure architecture Add comprehensive mem-search skill for accessing claude-mem's persistent cross-session memory database. Implements progressive disclosure workflow and token-efficient search patterns. Features: - 12 search operations (observations, sessions, prompts, by-type, by-concept, by-file, timelines, etc.) - Progressive disclosure principles to minimize token usage - Anti-patterns documentation to guide LLM behavior - HTTP API integration for all search functionality - Common workflows with composition examples Structure: - SKILL.md: Entry point with temporal trigger patterns - principles/: Progressive disclosure + anti-patterns - operations/: 12 search operation files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add CHANGELOG entry for mem-search skill Document mem-search skill addition in Unreleased section with: - 100% effectiveness compliance metrics - Comparison to previous search skill implementation - Progressive disclosure architecture details - Reference to audit report documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add mem-search skill audit report Add comprehensive audit report validating mem-search skill against Anthropic's official skill-creator documentation. Report includes: - Effectiveness metrics comparison (search vs mem-search) - Critical issues analysis for production readiness - Compliance validation across 6 key dimensions - Reference implementation guidance Result: mem-search achieves 100% compliance vs search's 67% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add comprehensive search architecture analysis document - Document current state of dual search architectures (HTTP API and MCP) - Analyze HTTP endpoints and MCP search server architectures - Identify DRY violations across search implementations - Evaluate the use of curl as the optimal approach for search - Provide architectural recommendations for immediate and long-term improvements - Outline action plan for cleanup, feature parity, DRY refactoring * refactor: Remove deprecated search skill documentation and operations * refactor: Reorganize documentation into public and context directories Changes: - Created docs/public/ for Mintlify documentation (.mdx files) - Created docs/context/ for internal planning and implementation docs - Moved all .mdx files and assets to docs/public/ - Moved all internal .md files to docs/context/ - Added CLAUDE.md to both directories explaining their purpose - Updated docs.json paths to work with new structure Benefits: - Clear separation between user-facing and internal documentation - Easier to maintain Mintlify docs in dedicated directory - Internal context files organized separately 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Enhance session management and continuity in hooks - Updated new-hook.ts to clarify session_id threading and idempotent session creation. - Modified prompts.ts to require claudeSessionId for continuation prompts, ensuring session context is maintained. - Improved SessionStore.ts documentation on createSDKSession to emphasize idempotent behavior and session connection. - Refined SDKAgent.ts to detail continuation prompt logic and its reliance on session.claudeSessionId for unified session handling. --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Alex Newman <thedotmack@gmail.com>
This commit is contained in:
basher83
@@ -0,0 +1,61 @@
|
||||
For tracking costs and tokens in your Agent SDK plugin, you have built-in programmatic access to usage data through the SDK itself[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking).
|
||||
|
||||
## Agent SDK Cost Tracking
|
||||
|
||||
The Claude Agent SDK provides detailed token usage information for each interaction[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking). Here's how to track it:
|
||||
|
||||
**TypeScript:**
|
||||
```typescript
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
|
||||
const result = await query({
|
||||
prompt: "Your task here",
|
||||
options: {
|
||||
onMessage: (message) => {
|
||||
if (message.type === 'assistant' && message.usage) {
|
||||
console.log(`Message ID: ${message.id}`);
|
||||
console.log(`Usage:`, message.usage);
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking)
|
||||
|
||||
The final `result` message contains the total cumulative usage from all steps in the conversation[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking):
|
||||
|
||||
```typescript
|
||||
console.log("Total usage:", result.usage);
|
||||
console.log("Total cost:", result.usage.total_cost_usd);
|
||||
```
|
||||
[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking)
|
||||
|
||||
## Important: Avoid Double-Counting
|
||||
|
||||
When Claude executes tools in parallel, multiple assistant messages may share the same ID and usage data[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking). You should only charge once per unique message ID[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking):
|
||||
|
||||
```typescript
|
||||
const processedMessageIds = new Set<string>();
|
||||
|
||||
onMessage: (message) => {
|
||||
if (message.type === 'assistant' && message.usage) {
|
||||
// Skip if already processed
|
||||
if (processedMessageIds.has(message.id)) {
|
||||
return;
|
||||
}
|
||||
|
||||
processedMessageIds.add(message.id);
|
||||
// Record usage here
|
||||
}
|
||||
}
|
||||
```
|
||||
[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking)
|
||||
|
||||
## Usage Fields
|
||||
|
||||
Each usage object contains[(1)](https://docs.claude.com/en/api/agent-sdk/cost-tracking):
|
||||
- `input_tokens`: Base input tokens processed
|
||||
- `output_tokens`: Tokens generated in the response
|
||||
- `cache_creation_input_tokens`: Tokens used to create cache entries
|
||||
- `cache_read_input_tokens`: Tokens read from cache
|
||||
- `total_cost_usd`: Total cost in USD (only in result message)
|
||||
@@ -0,0 +1,607 @@
|
||||
# Agent Skills
|
||||
|
||||
> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.
|
||||
|
||||
This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Claude Code version 1.0 or later
|
||||
* Basic familiarity with [Claude Code](/en/docs/claude-code/quickstart)
|
||||
|
||||
## What are Agent Skills?
|
||||
|
||||
Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.
|
||||
|
||||
**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them).
|
||||
|
||||
**Benefits**:
|
||||
|
||||
* Extend Claude's capabilities for your specific workflows
|
||||
* Share expertise across your team via git
|
||||
* Reduce repetitive prompting
|
||||
* Compose multiple Skills for complex tasks
|
||||
|
||||
Learn more in the [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
|
||||
|
||||
<Note>
|
||||
For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
|
||||
</Note>
|
||||
|
||||
## Create a Skill
|
||||
|
||||
Skills are stored as directories containing a `SKILL.md` file.
|
||||
|
||||
### Personal Skills
|
||||
|
||||
Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p ~/.claude/skills/my-skill-name
|
||||
```
|
||||
|
||||
**Use personal Skills for**:
|
||||
|
||||
* Your individual workflows and preferences
|
||||
* Experimental Skills you're developing
|
||||
* Personal productivity tools
|
||||
|
||||
### Project Skills
|
||||
|
||||
Project Skills are shared with your team. Store them in `.claude/skills/` within your project:
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p .claude/skills/my-skill-name
|
||||
```
|
||||
|
||||
**Use project Skills for**:
|
||||
|
||||
* Team workflows and conventions
|
||||
* Project-specific expertise
|
||||
* Shared utilities and scripts
|
||||
|
||||
Project Skills are checked into git and automatically available to team members.
|
||||
|
||||
### Plugin Skills
|
||||
|
||||
Skills can also come from [Claude Code plugins](/en/docs/claude-code/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills.
|
||||
|
||||
## Write SKILL.md
|
||||
|
||||
Create a `SKILL.md` file with YAML frontmatter and Markdown content:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: your-skill-name
|
||||
description: Brief description of what this Skill does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
Provide clear, step-by-step guidance for Claude.
|
||||
|
||||
## Examples
|
||||
Show concrete examples of using this Skill.
|
||||
```
|
||||
|
||||
**Field requirements**:
|
||||
|
||||
* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters)
|
||||
* `description`: Brief description of what the Skill does and when to use it (max 1024 characters)
|
||||
|
||||
The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it.
|
||||
|
||||
See the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.
|
||||
|
||||
## Add supporting files
|
||||
|
||||
Create additional files alongside SKILL.md:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (required)
|
||||
├── reference.md (optional documentation)
|
||||
├── examples.md (optional examples)
|
||||
├── scripts/
|
||||
│ └── helper.py (optional utility)
|
||||
└── templates/
|
||||
└── template.txt (optional template)
|
||||
```
|
||||
|
||||
Reference these files from SKILL.md:
|
||||
|
||||
````markdown theme={null}
|
||||
For advanced usage, see [reference.md](reference.md).
|
||||
|
||||
Run the helper script:
|
||||
```bash
|
||||
python scripts/helper.py input.txt
|
||||
```
|
||||
````
|
||||
|
||||
Claude reads these files only when needed, using progressive disclosure to manage context efficiently.
|
||||
|
||||
## Restrict tool access with allowed-tools
|
||||
|
||||
Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: safe-file-reader
|
||||
description: Read files without making changes. Use when you need read-only file access.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Safe File Reader
|
||||
|
||||
This Skill provides read-only file access.
|
||||
|
||||
## Instructions
|
||||
1. Use Read to view file contents
|
||||
2. Use Grep to search within files
|
||||
3. Use Glob to find files by pattern
|
||||
```
|
||||
|
||||
When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:
|
||||
|
||||
* Read-only Skills that shouldn't modify files
|
||||
* Skills with limited scope (e.g., only data analysis, no file writing)
|
||||
* Security-sensitive workflows where you want to restrict capabilities
|
||||
|
||||
If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.
|
||||
|
||||
<Note>
|
||||
`allowed-tools` is only supported for Skills in Claude Code.
|
||||
</Note>
|
||||
|
||||
## View available Skills
|
||||
|
||||
Skills are automatically discovered by Claude from three sources:
|
||||
|
||||
* Personal Skills: `~/.claude/skills/`
|
||||
* Project Skills: `.claude/skills/`
|
||||
* Plugin Skills: bundled with installed plugins
|
||||
|
||||
**To view all available Skills**, ask Claude directly:
|
||||
|
||||
```
|
||||
What Skills are available?
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
List all available Skills
|
||||
```
|
||||
|
||||
This will show all Skills from all sources, including plugin Skills.
|
||||
|
||||
**To inspect a specific Skill**, you can also check the filesystem:
|
||||
|
||||
```bash theme={null}
|
||||
# List personal Skills
|
||||
ls ~/.claude/skills/
|
||||
|
||||
# List project Skills (if in a project directory)
|
||||
ls .claude/skills/
|
||||
|
||||
# View a specific Skill's content
|
||||
cat ~/.claude/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
## Test a Skill
|
||||
|
||||
After creating a Skill, test it by asking questions that match your description.
|
||||
|
||||
**Example**: If your description mentions "PDF files":
|
||||
|
||||
```
|
||||
Can you help me extract text from this PDF?
|
||||
```
|
||||
|
||||
Claude autonomously decides to use your Skill if it matches the request—you don't need to explicitly invoke it. The Skill activates automatically based on the context of your question.
|
||||
|
||||
## Debug a Skill
|
||||
|
||||
If Claude doesn't use your Skill, check these common issues:
|
||||
|
||||
### Make description specific
|
||||
|
||||
**Too vague**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
**Specific**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
Include both what the Skill does and when to use it in the description.
|
||||
|
||||
### Verify file path
|
||||
|
||||
**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`
|
||||
**Project Skills**: `.claude/skills/skill-name/SKILL.md`
|
||||
|
||||
Check the file exists:
|
||||
|
||||
```bash theme={null}
|
||||
# Personal
|
||||
ls ~/.claude/skills/my-skill/SKILL.md
|
||||
|
||||
# Project
|
||||
ls .claude/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
### Check YAML syntax
|
||||
|
||||
Invalid YAML prevents the Skill from loading. Verify the frontmatter:
|
||||
|
||||
```bash theme={null}
|
||||
cat SKILL.md | head -n 10
|
||||
```
|
||||
|
||||
Ensure:
|
||||
|
||||
* Opening `---` on line 1
|
||||
* Closing `---` before Markdown content
|
||||
* Valid YAML syntax (no tabs, correct indentation)
|
||||
|
||||
### View errors
|
||||
|
||||
Run Claude Code with debug mode to see Skill loading errors:
|
||||
|
||||
```bash theme={null}
|
||||
claude --debug
|
||||
```
|
||||
|
||||
## Share Skills with your team
|
||||
|
||||
**Recommended approach**: Distribute Skills through [plugins](/en/docs/claude-code/plugins).
|
||||
|
||||
To share Skills via plugin:
|
||||
|
||||
1. Create a plugin with Skills in the `skills/` directory
|
||||
2. Add the plugin to a marketplace
|
||||
3. Team members install the plugin
|
||||
|
||||
For complete instructions, see [Add Skills to your plugin](/en/docs/claude-code/plugins#add-skills-to-your-plugin).
|
||||
|
||||
You can also share Skills directly through project repositories:
|
||||
|
||||
### Step 1: Add Skill to your project
|
||||
|
||||
Create a project Skill:
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p .claude/skills/team-skill
|
||||
# Create SKILL.md
|
||||
```
|
||||
|
||||
### Step 2: Commit to git
|
||||
|
||||
```bash theme={null}
|
||||
git add .claude/skills/
|
||||
git commit -m "Add team Skill for PDF processing"
|
||||
git push
|
||||
```
|
||||
|
||||
### Step 3: Team members get Skills automatically
|
||||
|
||||
When team members pull the latest changes, Skills are immediately available:
|
||||
|
||||
```bash theme={null}
|
||||
git pull
|
||||
claude # Skills are now available
|
||||
```
|
||||
|
||||
## Update a Skill
|
||||
|
||||
Edit SKILL.md directly:
|
||||
|
||||
```bash theme={null}
|
||||
# Personal Skill
|
||||
code ~/.claude/skills/my-skill/SKILL.md
|
||||
|
||||
# Project Skill
|
||||
code .claude/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.
|
||||
|
||||
## Remove a Skill
|
||||
|
||||
Delete the Skill directory:
|
||||
|
||||
```bash theme={null}
|
||||
# Personal
|
||||
rm -rf ~/.claude/skills/my-skill
|
||||
|
||||
# Project
|
||||
rm -rf .claude/skills/my-skill
|
||||
git commit -m "Remove unused Skill"
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
### Keep Skills focused
|
||||
|
||||
One Skill should address one capability:
|
||||
|
||||
**Focused**:
|
||||
|
||||
* "PDF form filling"
|
||||
* "Excel data analysis"
|
||||
* "Git commit messages"
|
||||
|
||||
**Too broad**:
|
||||
|
||||
* "Document processing" (split into separate Skills)
|
||||
* "Data tools" (split by data type or operation)
|
||||
|
||||
### Write clear descriptions
|
||||
|
||||
Help Claude discover when to use Skills by including specific triggers in your description:
|
||||
|
||||
**Clear**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
|
||||
```
|
||||
|
||||
**Vague**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: For files
|
||||
```
|
||||
|
||||
### Test with your team
|
||||
|
||||
Have teammates use Skills and provide feedback:
|
||||
|
||||
* Does the Skill activate when expected?
|
||||
* Are the instructions clear?
|
||||
* Are there missing examples or edge cases?
|
||||
|
||||
### Document Skill versions
|
||||
|
||||
You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:
|
||||
|
||||
```markdown theme={null}
|
||||
# My Skill
|
||||
|
||||
## Version History
|
||||
- v2.0.0 (2025-10-01): Breaking changes to API
|
||||
- v1.1.0 (2025-09-15): Added new features
|
||||
- v1.0.0 (2025-09-01): Initial release
|
||||
```
|
||||
|
||||
This helps team members understand what changed between versions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Claude doesn't use my Skill
|
||||
|
||||
**Symptom**: You ask a relevant question but Claude doesn't use your Skill.
|
||||
|
||||
**Check**: Is the description specific enough?
|
||||
|
||||
Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.
|
||||
|
||||
**Too generic**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: Helps with data
|
||||
```
|
||||
|
||||
**Specific**:
|
||||
|
||||
```yaml theme={null}
|
||||
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
|
||||
```
|
||||
|
||||
**Check**: Is the YAML valid?
|
||||
|
||||
Run validation to check for syntax errors:
|
||||
|
||||
```bash theme={null}
|
||||
# View frontmatter
|
||||
cat .claude/skills/my-skill/SKILL.md | head -n 15
|
||||
|
||||
# Check for common issues
|
||||
# - Missing opening or closing ---
|
||||
# - Tabs instead of spaces
|
||||
# - Unquoted strings with special characters
|
||||
```
|
||||
|
||||
**Check**: Is the Skill in the correct location?
|
||||
|
||||
```bash theme={null}
|
||||
# Personal Skills
|
||||
ls ~/.claude/skills/*/SKILL.md
|
||||
|
||||
# Project Skills
|
||||
ls .claude/skills/*/SKILL.md
|
||||
```
|
||||
|
||||
### Skill has errors
|
||||
|
||||
**Symptom**: The Skill loads but doesn't work correctly.
|
||||
|
||||
**Check**: Are dependencies available?
|
||||
|
||||
Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.
|
||||
|
||||
**Check**: Do scripts have execute permissions?
|
||||
|
||||
```bash theme={null}
|
||||
chmod +x .claude/skills/my-skill/scripts/*.py
|
||||
```
|
||||
|
||||
**Check**: Are file paths correct?
|
||||
|
||||
Use forward slashes (Unix style) in all paths:
|
||||
|
||||
**Correct**: `scripts/helper.py`
|
||||
**Wrong**: `scripts\helper.py` (Windows style)
|
||||
|
||||
### Multiple Skills conflict
|
||||
|
||||
**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.
|
||||
|
||||
**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.
|
||||
|
||||
Instead of:
|
||||
|
||||
```yaml theme={null}
|
||||
# Skill 1
|
||||
description: For data analysis
|
||||
|
||||
# Skill 2
|
||||
description: For analyzing data
|
||||
```
|
||||
|
||||
Use:
|
||||
|
||||
```yaml theme={null}
|
||||
# Skill 1
|
||||
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
|
||||
|
||||
# Skill 2
|
||||
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple Skill (single file)
|
||||
|
||||
```
|
||||
commit-helper/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: generating-commit-messages
|
||||
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
|
||||
---
|
||||
|
||||
# Generating Commit Messages
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --staged` to see changes
|
||||
2. I'll suggest a commit message with:
|
||||
- Summary under 50 characters
|
||||
- Detailed description
|
||||
- Affected components
|
||||
|
||||
## Best practices
|
||||
|
||||
- Use present tense
|
||||
- Explain what and why, not how
|
||||
```
|
||||
|
||||
### Skill with tool permissions
|
||||
|
||||
```
|
||||
code-reviewer/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Code Reviewer
|
||||
|
||||
## Review checklist
|
||||
|
||||
1. Code organization and structure
|
||||
2. Error handling
|
||||
3. Performance considerations
|
||||
4. Security concerns
|
||||
5. Test coverage
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Read the target files using Read tool
|
||||
2. Search for patterns using Grep
|
||||
3. Find related files using Glob
|
||||
4. Provide detailed feedback on code quality
|
||||
```
|
||||
|
||||
### Multi-file Skill
|
||||
|
||||
```
|
||||
pdf-processing/
|
||||
├── SKILL.md
|
||||
├── FORMS.md
|
||||
├── REFERENCE.md
|
||||
└── scripts/
|
||||
├── fill_form.py
|
||||
└── validate.py
|
||||
```
|
||||
|
||||
**SKILL.md**:
|
||||
|
||||
````yaml theme={null}
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
|
||||
Extract text:
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
|
||||
For form filling, see [FORMS.md](FORMS.md).
|
||||
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
Packages must be installed in your environment:
|
||||
```bash
|
||||
pip install pypdf pdfplumber
|
||||
```
|
||||
````
|
||||
|
||||
<Note>
|
||||
List required packages in the description. Packages must be installed in your environment before Claude can use them.
|
||||
</Note>
|
||||
|
||||
Claude loads additional files only when needed.
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Authoring best practices" icon="lightbulb" href="/en/docs/agents-and-tools/agent-skills/best-practices">
|
||||
Write Skills that Claude can use effectively
|
||||
</Card>
|
||||
|
||||
<Card title="Agent Skills overview" icon="book" href="/en/docs/agents-and-tools/agent-skills/overview">
|
||||
Learn how Skills work across Claude products
|
||||
</Card>
|
||||
|
||||
<Card title="Use Skills in the Agent SDK" icon="cube" href="/en/api/agent-sdk/skills">
|
||||
Use Skills programmatically with TypeScript and Python
|
||||
</Card>
|
||||
|
||||
<Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
|
||||
Create your first Skill
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,31 @@
|
||||
|
||||
|
||||
# Claude Code Hooks Exit Code Cheat Sheet
|
||||
|
||||
## Exit Code Behavior [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
|
||||
- **Exit code 0**: Success. `stdout` is shown to the user in transcript mode, except for `UserPromptSubmit` hook where stdout is injected as context [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
- **Exit code 2**: Blocking error. `stderr` is fed back to Claude to process automatically [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
- **Other exit codes**: Non-blocking error. `stderr` is shown to the user and execution continues [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
|
||||
## Per-Hook Event Behavior [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
|
||||
| Hook Event | Exit Code 2 Behavior |
|
||||
|------------|---------------------|
|
||||
| `PreToolUse` | Blocks the tool call, shows stderr to Claude [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `PostToolUse` | Shows stderr to Claude (tool already ran) [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `Notification` | N/A, shows stderr to user only [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `Stop` | Blocks stoppage, shows stderr to Claude [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `PreCompact` | N/A, shows stderr to user only [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `SessionStart` | N/A, shows stderr to user only [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
| `SessionEnd` | N/A, shows stderr to user only [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output) |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Success**: `process.exit(0)` - Operation completed successfully
|
||||
- **Block & feedback**: `process.exit(2)` - Block operation and give Claude feedback via stderr
|
||||
- **Non-blocking error**: `process.exit(1)` - Show error to user but continue execution
|
||||
|
||||
**Important**: Claude Code does not see stdout if the exit code is 0, except for the `UserPromptSubmit` hook where stdout is injected as context [(1)](https://docs.claude.com/en/docs/claude-code/hooks#hook-output)
|
||||
@@ -0,0 +1,837 @@
|
||||
# Hooks reference
|
||||
|
||||
> This page provides reference documentation for implementing hooks in Claude Code.
|
||||
|
||||
<Tip>
|
||||
For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/docs/claude-code/hooks-guide).
|
||||
</Tip>
|
||||
|
||||
## Configuration
|
||||
|
||||
Claude Code hooks are configured in your [settings files](/en/docs/claude-code/settings):
|
||||
|
||||
* `~/.claude/settings.json` - User settings
|
||||
* `.claude/settings.json` - Project settings
|
||||
* `.claude/settings.local.json` - Local project settings (not committed)
|
||||
* Enterprise managed policy settings
|
||||
|
||||
### Structure
|
||||
|
||||
Hooks are organized by matchers, where each matcher can have multiple hooks:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "ToolPattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "your-command-here"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **matcher**: Pattern to match tool names, case-sensitive (only applicable for
|
||||
`PreToolUse` and `PostToolUse`)
|
||||
* Simple strings match exactly: `Write` matches only the Write tool
|
||||
* Supports regex: `Edit|Write` or `Notebook.*`
|
||||
* Use `*` to match all tools. You can also use empty string (`""`) or leave
|
||||
`matcher` blank.
|
||||
* **hooks**: Array of commands to execute when the pattern matches
|
||||
* `type`: Currently only `"command"` is supported
|
||||
* `command`: The bash command to execute (can use `$CLAUDE_PROJECT_DIR`
|
||||
environment variable)
|
||||
* `timeout`: (Optional) How long a command should run, in seconds, before
|
||||
canceling that specific command.
|
||||
|
||||
For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop`
|
||||
that don't use matchers, you can omit the matcher field:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/prompt-validator.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Project-Specific Hook Scripts
|
||||
|
||||
You can use the environment variable `CLAUDE_PROJECT_DIR` (only available when
|
||||
Claude Code spawns the hook command) to reference scripts stored in your project,
|
||||
ensuring they work regardless of Claude's current directory:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin hooks
|
||||
|
||||
[Plugins](/en/docs/claude-code/plugins) can provide hooks that integrate seamlessly with your user and project hooks. Plugin hooks are automatically merged with your configuration when plugins are enabled.
|
||||
|
||||
**How plugin hooks work**:
|
||||
|
||||
* Plugin hooks are defined in the plugin's `hooks/hooks.json` file or in a file given by a custom path to the `hooks` field.
|
||||
* When a plugin is enabled, its hooks are merged with user and project hooks
|
||||
* Multiple hooks from different sources can respond to the same event
|
||||
* Plugin hooks use the `${CLAUDE_PLUGIN_ROOT}` environment variable to reference plugin files
|
||||
|
||||
**Example plugin hook configuration**:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"description": "Automatic code formatting",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Plugin hooks use the same format as regular hooks with an optional `description` field to explain the hook's purpose.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Plugin hooks run alongside your custom hooks. If multiple hooks match an event, they all execute in parallel.
|
||||
</Note>
|
||||
|
||||
**Environment variables for plugins**:
|
||||
|
||||
* `${CLAUDE_PLUGIN_ROOT}`: Absolute path to the plugin directory
|
||||
* `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)
|
||||
* All standard environment variables are available
|
||||
|
||||
See the [plugin components reference](/en/docs/claude-code/plugins-reference#hooks) for details on creating plugin hooks.
|
||||
|
||||
## Hook Events
|
||||
|
||||
### PreToolUse
|
||||
|
||||
Runs after Claude creates tool parameters and before processing the tool call.
|
||||
|
||||
**Common matchers:**
|
||||
|
||||
* `Task` - Subagent tasks (see [subagents documentation](/en/docs/claude-code/sub-agents))
|
||||
* `Bash` - Shell commands
|
||||
* `Glob` - File pattern matching
|
||||
* `Grep` - Content search
|
||||
* `Read` - File reading
|
||||
* `Edit` - File editing
|
||||
* `Write` - File writing
|
||||
* `WebFetch`, `WebSearch` - Web operations
|
||||
|
||||
### PostToolUse
|
||||
|
||||
Runs immediately after a tool completes successfully.
|
||||
|
||||
Recognizes the same matcher values as PreToolUse.
|
||||
|
||||
### Notification
|
||||
|
||||
Runs when Claude Code sends notifications. Notifications are sent when:
|
||||
|
||||
1. Claude needs your permission to use a tool. Example: "Claude needs your
|
||||
permission to use Bash"
|
||||
2. The prompt input has been idle for at least 60 seconds. "Claude is waiting
|
||||
for your input"
|
||||
|
||||
### UserPromptSubmit
|
||||
|
||||
Runs when the user submits a prompt, before Claude processes it. This allows you
|
||||
to add additional context based on the prompt/conversation, validate prompts, or
|
||||
block certain types of prompts.
|
||||
|
||||
### Stop
|
||||
|
||||
Runs when the main Claude Code agent has finished responding. Does not run if
|
||||
the stoppage occurred due to a user interrupt.
|
||||
|
||||
### SubagentStop
|
||||
|
||||
Runs when a Claude Code subagent (Task tool call) has finished responding.
|
||||
|
||||
### PreCompact
|
||||
|
||||
Runs before Claude Code is about to run a compact operation.
|
||||
|
||||
**Matchers:**
|
||||
|
||||
* `manual` - Invoked from `/compact`
|
||||
* `auto` - Invoked from auto-compact (due to full context window)
|
||||
|
||||
### SessionStart
|
||||
|
||||
Runs when Claude Code starts a new session or resumes an existing session (which
|
||||
currently does start a new session under the hood). Useful for loading in
|
||||
development context like existing issues or recent changes to your codebase.
|
||||
|
||||
**Matchers:**
|
||||
|
||||
* `startup` - Invoked from startup
|
||||
* `resume` - Invoked from `--resume`, `--continue`, or `/resume`
|
||||
* `clear` - Invoked from `/clear`
|
||||
* `compact` - Invoked from auto or manual compact.
|
||||
|
||||
### SessionEnd
|
||||
|
||||
Runs when a Claude Code session ends. Useful for cleanup tasks, logging session
|
||||
statistics, or saving session state.
|
||||
|
||||
The `reason` field in the hook input will be one of:
|
||||
|
||||
* `clear` - Session cleared with /clear command
|
||||
* `logout` - User logged out
|
||||
* `prompt_input_exit` - User exited while prompt input was visible
|
||||
* `other` - Other exit reasons
|
||||
|
||||
## Hook Input
|
||||
|
||||
Hooks receive JSON data via stdin containing session information and
|
||||
event-specific data:
|
||||
|
||||
```typescript theme={null}
|
||||
{
|
||||
// Common fields
|
||||
session_id: string
|
||||
transcript_path: string // Path to conversation JSON
|
||||
cwd: string // The current working directory when the hook is invoked
|
||||
|
||||
// Event-specific fields
|
||||
hook_event_name: string
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### PreToolUse Input
|
||||
|
||||
The exact schema for `tool_input` depends on the tool.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "PreToolUse",
|
||||
"tool_name": "Write",
|
||||
"tool_input": {
|
||||
"file_path": "/path/to/file.txt",
|
||||
"content": "file content"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PostToolUse Input
|
||||
|
||||
The exact schema for `tool_input` and `tool_response` depends on the tool.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "PostToolUse",
|
||||
"tool_name": "Write",
|
||||
"tool_input": {
|
||||
"file_path": "/path/to/file.txt",
|
||||
"content": "file content"
|
||||
},
|
||||
"tool_response": {
|
||||
"filePath": "/path/to/file.txt",
|
||||
"success": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification Input
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "Notification",
|
||||
"message": "Task completed successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### UserPromptSubmit Input
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "UserPromptSubmit",
|
||||
"prompt": "Write a function to calculate the factorial of a number"
|
||||
}
|
||||
```
|
||||
|
||||
### Stop and SubagentStop Input
|
||||
|
||||
`stop_hook_active` is true when Claude Code is already continuing as a result of
|
||||
a stop hook. Check this value or process the transcript to prevent Claude Code
|
||||
from running indefinitely.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "Stop",
|
||||
"stop_hook_active": true
|
||||
}
|
||||
```
|
||||
|
||||
### PreCompact Input
|
||||
|
||||
For `manual`, `custom_instructions` comes from what the user passes into
|
||||
`/compact`. For `auto`, `custom_instructions` is empty.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "PreCompact",
|
||||
"trigger": "manual",
|
||||
"custom_instructions": ""
|
||||
}
|
||||
```
|
||||
|
||||
### SessionStart Input
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "SessionStart",
|
||||
"source": "startup"
|
||||
}
|
||||
```
|
||||
|
||||
### SessionEnd Input
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "SessionEnd",
|
||||
"reason": "exit"
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Output
|
||||
|
||||
There are two ways for hooks to return output back to Claude Code. The output
|
||||
communicates whether to block and any feedback that should be shown to Claude
|
||||
and the user.
|
||||
|
||||
### Simple: Exit Code
|
||||
|
||||
Hooks communicate status through exit codes, stdout, and stderr:
|
||||
|
||||
* **Exit code 0**: Success. `stdout` is shown to the user in transcript mode
|
||||
(CTRL-R), except for `UserPromptSubmit` and `SessionStart`, where stdout is
|
||||
added to the context.
|
||||
* **Exit code 2**: Blocking error. `stderr` is fed back to Claude to process
|
||||
automatically. See per-hook-event behavior below.
|
||||
* **Other exit codes**: Non-blocking error. `stderr` is shown to the user and
|
||||
execution continues.
|
||||
|
||||
<Warning>
|
||||
Reminder: Claude Code does not see stdout if the exit code is 0, except for
|
||||
the `UserPromptSubmit` hook where stdout is injected as context.
|
||||
</Warning>
|
||||
|
||||
#### Exit Code 2 Behavior
|
||||
|
||||
| Hook Event | Behavior |
|
||||
| ------------------ | ------------------------------------------------------------------ |
|
||||
| `PreToolUse` | Blocks the tool call, shows stderr to Claude |
|
||||
| `PostToolUse` | Shows stderr to Claude (tool already ran) |
|
||||
| `Notification` | N/A, shows stderr to user only |
|
||||
| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |
|
||||
| `Stop` | Blocks stoppage, shows stderr to Claude |
|
||||
| `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent |
|
||||
| `PreCompact` | N/A, shows stderr to user only |
|
||||
| `SessionStart` | N/A, shows stderr to user only |
|
||||
| `SessionEnd` | N/A, shows stderr to user only |
|
||||
|
||||
### Advanced: JSON Output
|
||||
|
||||
Hooks can return structured JSON in `stdout` for more sophisticated control:
|
||||
|
||||
#### Common JSON Fields
|
||||
|
||||
All hook types can include these optional fields:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"continue": true, // Whether Claude should continue after hook execution (default: true)
|
||||
"stopReason": "string", // Message shown when continue is false
|
||||
|
||||
"suppressOutput": true, // Hide stdout from transcript mode (default: false)
|
||||
"systemMessage": "string" // Optional warning message shown to the user
|
||||
}
|
||||
```
|
||||
|
||||
If `continue` is false, Claude stops processing after the hooks run.
|
||||
|
||||
* For `PreToolUse`, this is different from `"permissionDecision": "deny"`, which
|
||||
only blocks a specific tool call and provides automatic feedback to Claude.
|
||||
* For `PostToolUse`, this is different from `"decision": "block"`, which
|
||||
provides automated feedback to Claude.
|
||||
* For `UserPromptSubmit`, this prevents the prompt from being processed.
|
||||
* For `Stop` and `SubagentStop`, this takes precedence over any
|
||||
`"decision": "block"` output.
|
||||
* In all cases, `"continue" = false` takes precedence over any
|
||||
`"decision": "block"` output.
|
||||
|
||||
`stopReason` accompanies `continue` with a reason shown to the user, not shown
|
||||
to Claude.
|
||||
|
||||
#### `PreToolUse` Decision Control
|
||||
|
||||
`PreToolUse` hooks can control whether a tool call proceeds.
|
||||
|
||||
* `"allow"` bypasses the permission system. `permissionDecisionReason` is shown
|
||||
to the user but not to Claude.
|
||||
* `"deny"` prevents the tool call from executing. `permissionDecisionReason` is
|
||||
shown to Claude.
|
||||
* `"ask"` asks the user to confirm the tool call in the UI.
|
||||
`permissionDecisionReason` is shown to the user but not to Claude.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "allow" | "deny" | "ask",
|
||||
"permissionDecisionReason": "My reason here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `decision` and `reason` fields are deprecated for PreToolUse hooks.
|
||||
Use `hookSpecificOutput.permissionDecision` and
|
||||
`hookSpecificOutput.permissionDecisionReason` instead. The deprecated fields
|
||||
`"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
|
||||
</Note>
|
||||
|
||||
#### `PostToolUse` Decision Control
|
||||
|
||||
`PostToolUse` hooks can provide feedback to Claude after tool execution.
|
||||
|
||||
* `"block"` automatically prompts Claude with `reason`.
|
||||
* `undefined` does nothing. `reason` is ignored.
|
||||
* `"hookSpecificOutput.additionalContext"` adds context for Claude to consider.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Explanation for decision",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PostToolUse",
|
||||
"additionalContext": "Additional information for Claude"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `UserPromptSubmit` Decision Control
|
||||
|
||||
`UserPromptSubmit` hooks can control whether a user prompt is processed.
|
||||
|
||||
* `"block"` prevents the prompt from being processed. The submitted prompt is
|
||||
erased from context. `"reason"` is shown to the user but not added to context.
|
||||
* `undefined` allows the prompt to proceed normally. `"reason"` is ignored.
|
||||
* `"hookSpecificOutput.additionalContext"` adds the string to the context if not
|
||||
blocked.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Explanation for decision",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "UserPromptSubmit",
|
||||
"additionalContext": "My additional context here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `Stop`/`SubagentStop` Decision Control
|
||||
|
||||
`Stop` and `SubagentStop` hooks can control whether Claude must continue.
|
||||
|
||||
* `"block"` prevents Claude from stopping. You must populate `reason` for Claude
|
||||
to know how to proceed.
|
||||
* `undefined` allows Claude to stop. `reason` is ignored.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Must be provided when Claude is blocked from stopping"
|
||||
}
|
||||
```
|
||||
|
||||
#### `SessionStart` Decision Control
|
||||
|
||||
`SessionStart` hooks allow you to load in context at the start of a session.
|
||||
|
||||
* `"hookSpecificOutput.additionalContext"` adds the string to the context.
|
||||
* Multiple hooks' `additionalContext` values are concatenated.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "My additional context here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `SessionEnd` Decision Control
|
||||
|
||||
`SessionEnd` hooks run when a session ends. They cannot block session termination
|
||||
but can perform cleanup tasks.
|
||||
|
||||
#### Exit Code Example: Bash Command Validation
|
||||
|
||||
```python theme={null}
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
|
||||
# Define validation rules as a list of (regex pattern, message) tuples
|
||||
VALIDATION_RULES = [
|
||||
(
|
||||
r"\bgrep\b(?!.*\|)",
|
||||
"Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
|
||||
),
|
||||
(
|
||||
r"\bfind\s+\S+\s+-name\b",
|
||||
"Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
def validate_command(command: str) -> list[str]:
|
||||
issues = []
|
||||
for pattern, message in VALIDATION_RULES:
|
||||
if re.search(pattern, command):
|
||||
issues.append(message)
|
||||
return issues
|
||||
|
||||
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
tool_name = input_data.get("tool_name", "")
|
||||
tool_input = input_data.get("tool_input", {})
|
||||
command = tool_input.get("command", "")
|
||||
|
||||
if tool_name != "Bash" or not command:
|
||||
sys.exit(1)
|
||||
|
||||
# Validate the command
|
||||
issues = validate_command(command)
|
||||
|
||||
if issues:
|
||||
for message in issues:
|
||||
print(f"• {message}", file=sys.stderr)
|
||||
# Exit code 2 blocks tool call and shows stderr to Claude
|
||||
sys.exit(2)
|
||||
```
|
||||
|
||||
#### JSON Output Example: UserPromptSubmit to Add Context and Validation
|
||||
|
||||
<Note>
|
||||
For `UserPromptSubmit` hooks, you can inject context using either method:
|
||||
|
||||
* Exit code 0 with stdout: Claude sees the context (special case for `UserPromptSubmit`)
|
||||
* JSON output: Provides more control over the behavior
|
||||
</Note>
|
||||
|
||||
```python theme={null}
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import sys
|
||||
import re
|
||||
import datetime
|
||||
|
||||
# Load input from stdin
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
prompt = input_data.get("prompt", "")
|
||||
|
||||
# Check for sensitive patterns
|
||||
sensitive_patterns = [
|
||||
(r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
|
||||
]
|
||||
|
||||
for pattern, message in sensitive_patterns:
|
||||
if re.search(pattern, prompt):
|
||||
# Use JSON output to block with a specific reason
|
||||
output = {
|
||||
"decision": "block",
|
||||
"reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
|
||||
}
|
||||
print(json.dumps(output))
|
||||
sys.exit(0)
|
||||
|
||||
# Add current time to context
|
||||
context = f"Current time: {datetime.datetime.now()}"
|
||||
print(context)
|
||||
|
||||
"""
|
||||
The following is also equivalent:
|
||||
print(json.dumps({
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "UserPromptSubmit",
|
||||
"additionalContext": context,
|
||||
},
|
||||
}))
|
||||
"""
|
||||
|
||||
# Allow the prompt to proceed with the additional context
|
||||
sys.exit(0)
|
||||
```
|
||||
|
||||
#### JSON Output Example: PreToolUse with Approval
|
||||
|
||||
```python theme={null}
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import sys
|
||||
|
||||
# Load input from stdin
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
tool_name = input_data.get("tool_name", "")
|
||||
tool_input = input_data.get("tool_input", {})
|
||||
|
||||
# Example: Auto-approve file reads for documentation files
|
||||
if tool_name == "Read":
|
||||
file_path = tool_input.get("file_path", "")
|
||||
if file_path.endswith((".md", ".mdx", ".txt", ".json")):
|
||||
# Use JSON output to auto-approve the tool call
|
||||
output = {
|
||||
"decision": "approve",
|
||||
"reason": "Documentation file auto-approved",
|
||||
"suppressOutput": True # Don't show in transcript mode
|
||||
}
|
||||
print(json.dumps(output))
|
||||
sys.exit(0)
|
||||
|
||||
# For other cases, let the normal permission flow proceed
|
||||
sys.exit(0)
|
||||
```
|
||||
|
||||
## Working with MCP Tools
|
||||
|
||||
Claude Code hooks work seamlessly with
|
||||
[Model Context Protocol (MCP) tools](/en/docs/claude-code/mcp). When MCP servers
|
||||
provide tools, they appear with a special naming pattern that you can match in
|
||||
your hooks.
|
||||
|
||||
### MCP Tool Naming
|
||||
|
||||
MCP tools follow the pattern `mcp__<server>__<tool>`, for example:
|
||||
|
||||
* `mcp__memory__create_entities` - Memory server's create entities tool
|
||||
* `mcp__filesystem__read_file` - Filesystem server's read file tool
|
||||
* `mcp__github__search_repositories` - GitHub server's search tool
|
||||
|
||||
### Configuring Hooks for MCP Tools
|
||||
|
||||
You can target specific MCP tools or entire MCP servers:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "mcp__memory__.*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "mcp__.*__write.*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/home/user/scripts/validate-mcp-write.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
<Tip>
|
||||
For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/docs/claude-code/hooks-guide#more-examples) in the get started guide.
|
||||
</Tip>
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Disclaimer
|
||||
|
||||
**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on
|
||||
your system automatically. By using hooks, you acknowledge that:
|
||||
|
||||
* You are solely responsible for the commands you configure
|
||||
* Hooks can modify, delete, or access any files your user account can access
|
||||
* Malicious or poorly written hooks can cause data loss or system damage
|
||||
* Anthropic provides no warranty and assumes no liability for any damages
|
||||
resulting from hook usage
|
||||
* You should thoroughly test hooks in a safe environment before production use
|
||||
|
||||
Always review and understand any hook commands before adding them to your
|
||||
configuration.
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
Here are some key practices for writing more secure hooks:
|
||||
|
||||
1. **Validate and sanitize inputs** - Never trust input data blindly
|
||||
2. **Always quote shell variables** - Use `"$VAR"` not `$VAR`
|
||||
3. **Block path traversal** - Check for `..` in file paths
|
||||
4. **Use absolute paths** - Specify full paths for scripts (use
|
||||
"\$CLAUDE\_PROJECT\_DIR" for the project path)
|
||||
5. **Skip sensitive files** - Avoid `.env`, `.git/`, keys, etc.
|
||||
|
||||
### Configuration Safety
|
||||
|
||||
Direct edits to hooks in settings files don't take effect immediately. Claude
|
||||
Code:
|
||||
|
||||
1. Captures a snapshot of hooks at startup
|
||||
2. Uses this snapshot throughout the session
|
||||
3. Warns if hooks are modified externally
|
||||
4. Requires review in `/hooks` menu for changes to apply
|
||||
|
||||
This prevents malicious hook modifications from affecting your current session.
|
||||
|
||||
## Hook Execution Details
|
||||
|
||||
* **Timeout**: 60-second execution limit by default, configurable per command.
|
||||
* A timeout for an individual command does not affect the other commands.
|
||||
* **Parallelization**: All matching hooks run in parallel
|
||||
* **Deduplication**: Multiple identical hook commands are deduplicated automatically
|
||||
* **Environment**: Runs in current directory with Claude Code's environment
|
||||
* The `CLAUDE_PROJECT_DIR` environment variable is available and contains the
|
||||
absolute path to the project root directory (where Claude Code was started)
|
||||
* **Input**: JSON via stdin
|
||||
* **Output**:
|
||||
* PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)
|
||||
* Notification/SessionEnd: Logged to debug only (`--debug`)
|
||||
* UserPromptSubmit/SessionStart: stdout added as context for Claude
|
||||
|
||||
## Debugging
|
||||
|
||||
### Basic Troubleshooting
|
||||
|
||||
If your hooks aren't working:
|
||||
|
||||
1. **Check configuration** - Run `/hooks` to see if your hook is registered
|
||||
2. **Verify syntax** - Ensure your JSON settings are valid
|
||||
3. **Test commands** - Run hook commands manually first
|
||||
4. **Check permissions** - Make sure scripts are executable
|
||||
5. **Review logs** - Use `claude --debug` to see hook execution details
|
||||
|
||||
Common issues:
|
||||
|
||||
* **Quotes not escaped** - Use `\"` inside JSON strings
|
||||
* **Wrong matcher** - Check tool names match exactly (case-sensitive)
|
||||
* **Command not found** - Use full paths for scripts
|
||||
|
||||
### Advanced Debugging
|
||||
|
||||
For complex hook issues:
|
||||
|
||||
1. **Inspect hook execution** - Use `claude --debug` to see detailed hook
|
||||
execution
|
||||
2. **Validate JSON schemas** - Test hook input/output with external tools
|
||||
3. **Check environment variables** - Verify Claude Code's environment is correct
|
||||
4. **Test edge cases** - Try hooks with unusual file paths or inputs
|
||||
5. **Monitor system resources** - Check for resource exhaustion during hook
|
||||
execution
|
||||
6. **Use structured logging** - Implement logging in your hook scripts
|
||||
|
||||
### Debug Output Example
|
||||
|
||||
Use `claude --debug` to see hook execution details:
|
||||
|
||||
```
|
||||
[DEBUG] Executing hooks for PostToolUse:Write
|
||||
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
|
||||
[DEBUG] Found 1 hook matchers in settings
|
||||
[DEBUG] Matched 1 hooks for query "Write"
|
||||
[DEBUG] Found 1 hook commands to execute
|
||||
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
|
||||
[DEBUG] Hook command completed with status 0: <Your stdout>
|
||||
```
|
||||
|
||||
Progress messages appear in transcript mode (Ctrl-R) showing:
|
||||
|
||||
* Which hook is running
|
||||
* Command being executed
|
||||
* Success/failure status
|
||||
* Output or error messages
|
||||
@@ -0,0 +1,391 @@
|
||||
# Plugins
|
||||
|
||||
> Extend Claude Code with custom commands, agents, hooks, and MCP servers through the plugin system.
|
||||
|
||||
<Tip>
|
||||
For complete technical specifications and schemas, see [Plugins reference](/en/docs/claude-code/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).
|
||||
</Tip>
|
||||
|
||||
Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Install plugins from [marketplaces](/en/docs/claude-code/plugin-marketplaces) to add pre-built commands, agents, hooks, and MCP servers, or create your own to automate your workflows.
|
||||
|
||||
## Quickstart
|
||||
|
||||
Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* Claude Code installed on your machine
|
||||
* Basic familiarity with command-line tools
|
||||
|
||||
### Create your first plugin
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the marketplace structure">
|
||||
```bash theme={null}
|
||||
mkdir test-marketplace
|
||||
cd test-marketplace
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the plugin directory">
|
||||
```bash theme={null}
|
||||
mkdir my-first-plugin
|
||||
cd my-first-plugin
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the plugin manifest">
|
||||
```bash Create .claude-plugin/plugin.json theme={null}
|
||||
mkdir .claude-plugin
|
||||
cat > .claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"name": "my-first-plugin",
|
||||
"description": "A simple greeting plugin to learn the basics",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Add a custom command">
|
||||
```bash Create commands/hello.md theme={null}
|
||||
mkdir commands
|
||||
cat > commands/hello.md << 'EOF'
|
||||
---
|
||||
description: Greet the user with a personalized message
|
||||
---
|
||||
|
||||
# Hello Command
|
||||
|
||||
Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.
|
||||
EOF
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the marketplace manifest">
|
||||
```bash Create marketplace.json theme={null}
|
||||
cd ..
|
||||
mkdir .claude-plugin
|
||||
cat > .claude-plugin/marketplace.json << 'EOF'
|
||||
{
|
||||
"name": "test-marketplace",
|
||||
"owner": {
|
||||
"name": "Test User"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-first-plugin",
|
||||
"source": "./my-first-plugin",
|
||||
"description": "My first test plugin"
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Install and test your plugin">
|
||||
```bash Start Claude Code from parent directory theme={null}
|
||||
cd ..
|
||||
claude
|
||||
```
|
||||
|
||||
```shell Add the test marketplace theme={null}
|
||||
/plugin marketplace add ./test-marketplace
|
||||
```
|
||||
|
||||
```shell Install your plugin theme={null}
|
||||
/plugin install my-first-plugin@test-marketplace
|
||||
```
|
||||
|
||||
Select "Install now". You'll then need to restart Claude Code in order to use the new plugin.
|
||||
|
||||
```shell Try your new command theme={null}
|
||||
/hello
|
||||
```
|
||||
|
||||
You'll see Claude use your greeting command! Check `/help` to see your new command listed.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
You've successfully created and tested a plugin with these key components:
|
||||
|
||||
* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata
|
||||
* **Commands directory** (`commands/`) - Contains your custom slash commands
|
||||
* **Test marketplace** - Allows you to test your plugin locally
|
||||
|
||||
### Plugin structure overview
|
||||
|
||||
Your plugin follows this basic structure:
|
||||
|
||||
```
|
||||
my-first-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Plugin metadata
|
||||
├── commands/ # Custom slash commands (optional)
|
||||
│ └── hello.md
|
||||
├── agents/ # Custom agents (optional)
|
||||
│ └── helper.md
|
||||
├── skills/ # Agent Skills (optional)
|
||||
│ └── my-skill/
|
||||
│ └── SKILL.md
|
||||
└── hooks/ # Event handlers (optional)
|
||||
└── hooks.json
|
||||
```
|
||||
|
||||
**Additional components you can add:**
|
||||
|
||||
* **Commands**: Create markdown files in `commands/` directory
|
||||
* **Agents**: Create agent definitions in `agents/` directory
|
||||
* **Skills**: Create `SKILL.md` files in `skills/` directory
|
||||
* **Hooks**: Create `hooks/hooks.json` for event handling
|
||||
* **MCP servers**: Create `.mcp.json` for external tool integration
|
||||
|
||||
<Note>
|
||||
**Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, and MCP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/docs/claude-code/plugins-reference).
|
||||
</Note>
|
||||
|
||||
***
|
||||
|
||||
## Install and manage plugins
|
||||
|
||||
Learn how to discover, install, and manage plugins to extend your Claude Code capabilities.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* Claude Code installed and running
|
||||
* Basic familiarity with command-line interfaces
|
||||
|
||||
### Add marketplaces
|
||||
|
||||
Marketplaces are catalogs of available plugins. Add them to discover and install plugins:
|
||||
|
||||
```shell Add a marketplace theme={null}
|
||||
/plugin marketplace add your-org/claude-plugins
|
||||
```
|
||||
|
||||
```shell Browse available plugins theme={null}
|
||||
/plugin
|
||||
```
|
||||
|
||||
For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).
|
||||
|
||||
### Install plugins
|
||||
|
||||
#### Via interactive menu (recommended for discovery)
|
||||
|
||||
```shell Open the plugin management interface theme={null}
|
||||
/plugin
|
||||
```
|
||||
|
||||
Select "Browse Plugins" to see available options with descriptions, features, and installation options.
|
||||
|
||||
#### Via direct commands (for quick installation)
|
||||
|
||||
```shell Install a specific plugin theme={null}
|
||||
/plugin install formatter@your-org
|
||||
```
|
||||
|
||||
```shell Enable a disabled plugin theme={null}
|
||||
/plugin enable plugin-name@marketplace-name
|
||||
```
|
||||
|
||||
```shell Disable without uninstalling theme={null}
|
||||
/plugin disable plugin-name@marketplace-name
|
||||
```
|
||||
|
||||
```shell Completely remove a plugin theme={null}
|
||||
/plugin uninstall plugin-name@marketplace-name
|
||||
```
|
||||
|
||||
### Verify installation
|
||||
|
||||
After installing a plugin:
|
||||
|
||||
1. **Check available commands**: Run `/help` to see new commands
|
||||
2. **Test plugin features**: Try the plugin's commands and features
|
||||
3. **Review plugin details**: Use `/plugin` → "Manage Plugins" to see what the plugin provides
|
||||
|
||||
## Set up team plugin workflows
|
||||
|
||||
Configure plugins at the repository level to ensure consistent tooling across your team. When team members trust your repository folder, Claude Code automatically installs specified marketplaces and plugins.
|
||||
|
||||
**To set up team plugins:**
|
||||
|
||||
1. Add marketplace and plugin configuration to your repository's `.claude/settings.json`
|
||||
2. Team members trust the repository folder
|
||||
3. Plugins install automatically for all team members
|
||||
|
||||
For complete instructions including configuration examples, marketplace setup, and rollout best practices, see [Configure team marketplaces](/en/docs/claude-code/plugin-marketplaces#how-to-configure-team-marketplaces).
|
||||
|
||||
***
|
||||
|
||||
## Develop more complex plugins
|
||||
|
||||
Once you're comfortable with basic plugins, you can create more sophisticated extensions.
|
||||
|
||||
### Add Skills to your plugin
|
||||
|
||||
Plugins can include [Agent Skills](/en/docs/claude-code/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context.
|
||||
|
||||
To add Skills to your plugin, create a `skills/` directory at your plugin root and add Skill folders with `SKILL.md` files. Plugin Skills are automatically available when the plugin is installed.
|
||||
|
||||
For complete Skill authoring guidance, see [Agent Skills](/en/docs/claude-code/skills).
|
||||
|
||||
### Organize complex plugins
|
||||
|
||||
For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/docs/claude-code/plugins-reference#plugin-directory-structure).
|
||||
|
||||
### Test your plugins locally
|
||||
|
||||
When developing plugins, use a local marketplace to test changes iteratively. This workflow builds on the quickstart pattern and works for plugins of any complexity.
|
||||
|
||||
<Steps>
|
||||
<Step title="Set up your development structure">
|
||||
Organize your plugin and marketplace for testing:
|
||||
|
||||
```bash Create directory structure theme={null}
|
||||
mkdir dev-marketplace
|
||||
cd dev-marketplace
|
||||
mkdir my-plugin
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
```
|
||||
dev-marketplace/
|
||||
├── .claude-plugin/marketplace.json (you'll create this)
|
||||
└── my-plugin/ (your plugin under development)
|
||||
├── .claude-plugin/plugin.json
|
||||
├── commands/
|
||||
├── agents/
|
||||
└── hooks/
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the marketplace manifest">
|
||||
```bash Create marketplace.json theme={null}
|
||||
mkdir .claude-plugin
|
||||
cat > .claude-plugin/marketplace.json << 'EOF'
|
||||
{
|
||||
"name": "dev-marketplace",
|
||||
"owner": {
|
||||
"name": "Developer"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./my-plugin",
|
||||
"description": "Plugin under development"
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Install and test">
|
||||
```bash Start Claude Code from parent directory theme={null}
|
||||
cd ..
|
||||
claude
|
||||
```
|
||||
|
||||
```shell Add your development marketplace theme={null}
|
||||
/plugin marketplace add ./dev-marketplace
|
||||
```
|
||||
|
||||
```shell Install your plugin theme={null}
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
Test your plugin components:
|
||||
|
||||
* Try your commands with `/command-name`
|
||||
* Check that agents appear in `/agents`
|
||||
* Verify hooks work as expected
|
||||
</Step>
|
||||
|
||||
<Step title="Iterate on your plugin">
|
||||
After making changes to your plugin code:
|
||||
|
||||
```shell Uninstall the current version theme={null}
|
||||
/plugin uninstall my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
```shell Reinstall to test changes theme={null}
|
||||
/plugin install my-plugin@dev-marketplace
|
||||
```
|
||||
|
||||
Repeat this cycle as you develop and refine your plugin.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
**For multiple plugins**: Organize plugins in subdirectories like `./plugins/plugin-name` and update your marketplace.json accordingly. See [Plugin sources](/en/docs/claude-code/plugin-marketplaces#plugin-sources) for organization patterns.
|
||||
</Note>
|
||||
|
||||
### Debug plugin issues
|
||||
|
||||
If your plugin isn't working as expected:
|
||||
|
||||
1. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`
|
||||
2. **Test components individually**: Check each command, agent, and hook separately
|
||||
3. **Use validation and debugging tools**: See [Debugging and development tools](/en/docs/claude-code/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques
|
||||
|
||||
### Share your plugins
|
||||
|
||||
When your plugin is ready to share:
|
||||
|
||||
1. **Add documentation**: Include a README.md with installation and usage instructions
|
||||
2. **Version your plugin**: Use semantic versioning in your `plugin.json`
|
||||
3. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation
|
||||
4. **Test with others**: Have team members test the plugin before wider distribution
|
||||
|
||||
<Note>
|
||||
For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/docs/claude-code/plugins-reference).
|
||||
</Note>
|
||||
|
||||
***
|
||||
|
||||
## Next steps
|
||||
|
||||
Now that you understand Claude Code's plugin system, here are suggested paths for different goals:
|
||||
|
||||
### For plugin users
|
||||
|
||||
* **Discover plugins**: Browse community marketplaces for useful tools
|
||||
* **Team adoption**: Set up repository-level plugins for your projects
|
||||
* **Marketplace management**: Learn to manage multiple plugin sources
|
||||
* **Advanced usage**: Explore plugin combinations and workflows
|
||||
|
||||
### For plugin developers
|
||||
|
||||
* **Create your first marketplace**: [Plugin marketplaces guide](/en/docs/claude-code/plugin-marketplaces)
|
||||
* **Advanced components**: Dive deeper into specific plugin components:
|
||||
* [Slash commands](/en/docs/claude-code/slash-commands) - Command development details
|
||||
* [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities
|
||||
* [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities
|
||||
* [Hooks](/en/docs/claude-code/hooks) - Event handling and automation
|
||||
* [MCP](/en/docs/claude-code/mcp) - External tool integration
|
||||
* **Distribution strategies**: Package and share your plugins effectively
|
||||
* **Community contribution**: Consider contributing to community plugin collections
|
||||
|
||||
### For team leads and administrators
|
||||
|
||||
* **Repository configuration**: Set up automatic plugin installation for team projects
|
||||
* **Plugin governance**: Establish guidelines for plugin approval and security review
|
||||
* **Marketplace maintenance**: Create and maintain organization-specific plugin catalogs
|
||||
* **Training and documentation**: Help team members adopt plugin workflows effectively
|
||||
|
||||
## See also
|
||||
|
||||
* [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces) - Creating and managing plugin catalogs
|
||||
* [Slash commands](/en/docs/claude-code/slash-commands) - Understanding custom commands
|
||||
* [Subagents](/en/docs/claude-code/sub-agents) - Creating and using specialized agents
|
||||
* [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities
|
||||
* [Hooks](/en/docs/claude-code/hooks) - Automating workflows with event handlers
|
||||
* [MCP](/en/docs/claude-code/mcp) - Connecting to external tools and services
|
||||
* [Settings](/en/docs/claude-code/settings) - Configuration options for plugins
|
||||
@@ -0,0 +1,218 @@
|
||||
# Models overview
|
||||
|
||||
> Claude is a family of state-of-the-art large language models developed by Anthropic. This guide introduces our models and compares their performance with legacy models.
|
||||
|
||||
export const ModelId = ({children, style = {}}) => {
|
||||
const copiedNotice = 'Copied!';
|
||||
const handleClick = e => {
|
||||
const element = e.currentTarget;
|
||||
const originalText = element.textContent;
|
||||
navigator.clipboard.writeText(children).then(() => {
|
||||
element.textContent = copiedNotice;
|
||||
element.style.backgroundColor = '#d4edda';
|
||||
element.style.color = '#155724';
|
||||
element.style.borderColor = '#c3e6cb';
|
||||
setTimeout(() => {
|
||||
element.textContent = originalText;
|
||||
element.style.backgroundColor = '#f5f5f5';
|
||||
element.style.color = '';
|
||||
element.style.borderColor = 'transparent';
|
||||
}, 2000);
|
||||
}).catch(error => {
|
||||
console.error('Failed to copy:', error);
|
||||
});
|
||||
};
|
||||
const handleMouseEnter = e => {
|
||||
const element = e.currentTarget;
|
||||
const tooltip = element.querySelector('.copy-tooltip');
|
||||
if (tooltip && element.textContent !== copiedNotice) {
|
||||
tooltip.style.opacity = '1';
|
||||
}
|
||||
element.style.backgroundColor = '#e8e8e8';
|
||||
element.style.borderColor = '#d0d0d0';
|
||||
};
|
||||
const handleMouseLeave = e => {
|
||||
const element = e.currentTarget;
|
||||
const tooltip = element.querySelector('.copy-tooltip');
|
||||
if (tooltip) {
|
||||
tooltip.style.opacity = '0';
|
||||
}
|
||||
if (element.textContent !== copiedNotice) {
|
||||
element.style.backgroundColor = '#f5f5f5';
|
||||
element.style.borderColor = 'transparent';
|
||||
}
|
||||
};
|
||||
const defaultStyle = {
|
||||
cursor: 'pointer',
|
||||
position: 'relative',
|
||||
transition: 'all 0.2s ease',
|
||||
display: 'inline-block',
|
||||
userSelect: 'none',
|
||||
backgroundColor: '#f5f5f5',
|
||||
padding: '2px 4px',
|
||||
borderRadius: '4px',
|
||||
fontFamily: 'Monaco, Consolas, "Courier New", monospace',
|
||||
fontSize: '0.9em',
|
||||
border: '1px solid transparent',
|
||||
...style
|
||||
};
|
||||
return <span onClick={handleClick} onMouseEnter={handleMouseEnter} onMouseLeave={handleMouseLeave} style={defaultStyle}>
|
||||
{children}
|
||||
</span>;
|
||||
};
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Claude Sonnet 4.5" icon="star" href="/en/docs/about-claude/models/overview#model-comparison-table">
|
||||
Our best model for complex agents and coding
|
||||
|
||||
* <Icon icon="inbox-in" iconType="thin" /> Text and image input
|
||||
* <Icon icon="inbox-out" iconType="thin" /> Text output
|
||||
* <Icon icon="book" iconType="thin" /> 200k context window (1M context beta available)
|
||||
* <Icon icon="brain" iconType="thin" /> Highest intelligence across most tasks
|
||||
</Card>
|
||||
|
||||
<Card title="Claude Haiku 4.5" icon="rocket-launch" href="/en/docs/about-claude/models/overview#model-comparison-table">
|
||||
Our fastest and most intelligent Haiku model
|
||||
|
||||
* <Icon icon="inbox-in" iconType="thin" /> Text and image input
|
||||
* <Icon icon="inbox-out" iconType="thin" /> Text output
|
||||
* <Icon icon="book" iconType="thin" /> 200k context window
|
||||
* <Icon icon="zap" iconType="thin" /> Lightning-fast speed with extended thinking
|
||||
</Card>
|
||||
|
||||
<Card title="Claude Opus 4.1" icon="trophy" href="/en/docs/about-claude/models/overview#model-comparison-table">
|
||||
Exceptional model for specialized complex tasks
|
||||
|
||||
* <Icon icon="inbox-in" iconType="thin" /> Text and image input
|
||||
* <Icon icon="inbox-out" iconType="thin" /> Text output
|
||||
* <Icon icon="book" iconType="thin" /> 200k context window
|
||||
* <Icon icon="brain" iconType="thin" /> Superior reasoning capabilities
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
***
|
||||
|
||||
## Model names
|
||||
|
||||
| Model | Claude API | AWS Bedrock | GCP Vertex AI |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
|
||||
| Claude Sonnet 4.5 | <ModelId>claude-sonnet-4-5-20250929</ModelId> | <ModelId>anthropic.claude-sonnet-4-5-20250929-v1:0</ModelId> | <ModelId>claude-sonnet-4-5\@20250929</ModelId> |
|
||||
| Claude Sonnet 4 | <ModelId>claude-sonnet-4-20250514</ModelId> | <ModelId>anthropic.claude-sonnet-4-20250514-v1:0</ModelId> | <ModelId>claude-sonnet-4\@20250514</ModelId> |
|
||||
| Claude Sonnet 3.7 | <ModelId>claude-3-7-sonnet-20250219</ModelId> (<ModelId>claude-3-7-sonnet-latest</ModelId>) | <ModelId>anthropic.claude-3-7-sonnet-20250219-v1:0</ModelId> | <ModelId>claude-3-7-sonnet\@20250219</ModelId> |
|
||||
| Claude Haiku 4.5 | <ModelId>claude-haiku-4-5-20251001</ModelId> | <ModelId>anthropic.claude-haiku-4-5-20251001-v1:0</ModelId> | <ModelId>claude-haiku-4-5\@20251001</ModelId> |
|
||||
| Claude Haiku 3.5 | <ModelId>claude-3-5-haiku-20241022</ModelId> (<ModelId>claude-3-5-haiku-latest</ModelId>) | <ModelId>anthropic.claude-3-5-haiku-20241022-v1:0</ModelId> | <ModelId>claude-3-5-haiku\@20241022</ModelId> |
|
||||
| Claude Haiku 3 | <ModelId>claude-3-haiku-20240307</ModelId> | <ModelId>anthropic.claude-3-haiku-20240307-v1:0</ModelId> | <ModelId>claude-3-haiku\@20240307</ModelId> |
|
||||
| Claude Opus 4.1 | <ModelId>claude-opus-4-1-20250805</ModelId> | <ModelId>anthropic.claude-opus-4-1-20250805-v1:0</ModelId> | <ModelId>claude-opus-4-1\@20250805</ModelId> |
|
||||
| Claude Opus 4 | <ModelId>claude-opus-4-20250514</ModelId> | <ModelId>anthropic.claude-opus-4-20250514-v1:0</ModelId> | <ModelId>claude-opus-4\@20250514</ModelId> |
|
||||
|
||||
<Note>Models with the same snapshot date (e.g., 20240620) are identical across all platforms and do not change. The snapshot date in the model name ensures consistency and allows developers to rely on stable performance across different environments.</Note>
|
||||
|
||||
<Note>Starting with **Claude Sonnet 4.5 and all future models**, AWS Bedrock and Google Vertex AI offer two endpoint types: **global endpoints** (dynamic routing for maximum availability) and **regional endpoints** (guaranteed data routing through specific geographic regions). For more information, see the [third-party platform pricing section](/en/docs/about-claude/pricing#third-party-platform-pricing).</Note>
|
||||
|
||||
### Model aliases
|
||||
|
||||
For convenience during development and testing, we offer aliases for our model ids. These aliases automatically point to the most recent snapshot of a given model. When we release new model snapshots, we migrate aliases to point to the newest version of a model, typically within a week of the new release.
|
||||
|
||||
<Tip>
|
||||
While aliases are useful for experimentation, we recommend using specific model versions (e.g., `claude-sonnet-4-5-20250929`) in production applications to ensure consistent behavior.
|
||||
</Tip>
|
||||
|
||||
| Model | Alias | Model ID |
|
||||
| ----------------- | ------------------------------------------- | --------------------------------------------- |
|
||||
| Claude Sonnet 4.5 | <ModelId>claude-sonnet-4-5</ModelId> | <ModelId>claude-sonnet-4-5-20250929</ModelId> |
|
||||
| Claude Sonnet 4 | <ModelId>claude-sonnet-4-0</ModelId> | <ModelId>claude-sonnet-4-20250514</ModelId> |
|
||||
| Claude Sonnet 3.7 | <ModelId>claude-3-7-sonnet-latest</ModelId> | <ModelId>claude-3-7-sonnet-20250219</ModelId> |
|
||||
| Claude Haiku 4.5 | <ModelId>claude-haiku-4-5</ModelId> | <ModelId>claude-haiku-4-5-20251001</ModelId> |
|
||||
| Claude Haiku 3.5 | <ModelId>claude-3-5-haiku-latest</ModelId> | <ModelId>claude-3-5-haiku-20241022</ModelId> |
|
||||
| Claude Opus 4.1 | <ModelId>claude-opus-4-1</ModelId> | <ModelId>claude-opus-4-1-20250805</ModelId> |
|
||||
| Claude Opus 4 | <ModelId>claude-opus-4-0</ModelId> | <ModelId>claude-opus-4-20250514</ModelId> |
|
||||
|
||||
<Note>
|
||||
Aliases are subject to the same rate limits and pricing as the underlying model version they reference.
|
||||
</Note>
|
||||
|
||||
### Model comparison table
|
||||
|
||||
To help you choose the right model for your needs, we've compiled a table comparing the key features and capabilities of each model in the Claude family:
|
||||
|
||||
| Feature | Claude Sonnet 4.5 | Claude Sonnet 4 | Claude Sonnet 3.7 | Claude Opus 4.1 | Claude Opus 4 | Claude Haiku 4.5 | Claude Haiku 3.5 | Claude Haiku 3 |
|
||||
| :-------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
|
||||
| **Description** | Our best model for complex agents and coding | High-performance model | High-performance model with early extended thinking | Exceptional model for specialized complex tasks | Our previous flagship model | Our fastest and most intelligent Haiku model | Our fastest model | Fast and compact model for near-instant responsiveness |
|
||||
| **Strengths** | Highest intelligence across most tasks with exceptional agent and coding capabilities | High intelligence and balanced performance | High intelligence with toggleable extended thinking | Very high intelligence and capability for specialized tasks | Very high intelligence and capability | Near-frontier intelligence at blazing speeds with extended thinking and exceptional cost-efficiency | Intelligence at blazing speeds | Quick and accurate targeted performance |
|
||||
| **Multilingual** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
||||
| **Vision** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
|
||||
| **[Extended thinking](/en/docs/build-with-claude/extended-thinking)** | Yes | Yes | Yes | Yes | Yes | Yes | No | No |
|
||||
| **[Priority Tier](/en/api/service-tiers)** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
|
||||
| **API model name** | <ModelId>claude-sonnet-4-5-20250929</ModelId> | <ModelId>claude-sonnet-4-20250514</ModelId> | <ModelId>claude-3-7-sonnet-20250219</ModelId> | <ModelId>claude-opus-4-1-20250805</ModelId> | <ModelId>claude-opus-4-20250514</ModelId> | <ModelId>claude-haiku-4-5-20251001</ModelId> | <ModelId>claude-3-5-haiku-20241022</ModelId> | <ModelId>claude-3-haiku-20240307</ModelId> |
|
||||
| **Comparative latency** | Fast | Fast | Fast | Moderately Fast | Moderately Fast | Fastest | Fastest | Fast |
|
||||
| **Context window** | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> / <br /> 1M (beta)<sup>1</sup> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> / <br /> 1M (beta)<sup>1</sup> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> | <Tooltip tip="~150K words \ ~215K unicode characters">200K</Tooltip> | <Tooltip tip="~150K words \ ~680K unicode characters">200K</Tooltip> |
|
||||
| **Max output** | <Tooltip tip="~48K words \ 218K unicode characters \ ~100 single spaced pages">64000 tokens</Tooltip> | <Tooltip tip="~48K words \ 218K unicode characters \ ~100 single spaced pages">64000 tokens</Tooltip> | <Tooltip tip="~48K words \ 218K unicode characters \ ~100 single spaced pages">64000 tokens</Tooltip> | <Tooltip tip="~24K words \ 109K unicode characters \ ~50 single spaced pages">32000 tokens</Tooltip> | <Tooltip tip="~24K words \ 109K unicode characters \ ~50 single spaced pages">32000 tokens</Tooltip> | <Tooltip tip="~48K words \ 218K unicode characters \ ~100 single spaced pages">64000 tokens</Tooltip> | <Tooltip tip="~6.2K words \ 28K unicode characters \ ~12-13 single spaced pages">8192 tokens</Tooltip> | <Tooltip tip="~3.1K words \ 14K unicode characters \ ~6-7 single spaced pages">4096 tokens</Tooltip> |
|
||||
| **Reliable knowledge cutoff** | Jan 2025<sup>2</sup> | Jan 2025<sup>2</sup> | Oct 2024<sup>2</sup> | Jan 2025<sup>2</sup> | Jan 2025<sup>2</sup> | Feb 2025 | <sup>3</sup> | <sup>3</sup> |
|
||||
| **Training data cutoff** | Jul 2025 | Mar 2025 | Nov 2024 | Mar 2025 | Mar 2025 | Jul 2025 | Jul 2024 | Aug 2023 |
|
||||
|
||||
*<sup>1 - Claude Sonnet 4.5 and Claude Sonnet 4 support a [1M token context window](/en/docs/build-with-claude/context-windows#1m-token-context-window) when using the `context-1m-2025-08-07` beta header. [Long context pricing](/en/docs/about-claude/pricing#long-context-pricing) applies to requests exceeding 200K tokens.</sup>*
|
||||
|
||||
*<sup>2 - **Reliable knowledge cutoff** indicates the date through which a model's knowledge is most extensive and reliable. **Training data cutoff** is the broader date range of training data used. For example, Claude Sonnet 4.5 was trained on publicly available information through July 2025, but its knowledge is most extensive and reliable through January 2025. For more information, see [Anthropic's Transparency Hub](https://www.anthropic.com/transparency).</sup>*
|
||||
|
||||
*<sup>3 - Some Haiku models have a single training data cutoff date.</sup>*
|
||||
|
||||
<Note>
|
||||
Include the beta header `output-128k-2025-02-19` in your API request to increase the maximum output token length to 128k tokens for Claude Sonnet 3.7.
|
||||
|
||||
We strongly suggest using our [streaming Messages API](/en/docs/build-with-claude/streaming) to avoid timeouts when generating longer outputs.
|
||||
See our guidance on [long requests](/en/api/errors#long-requests) for more details.
|
||||
</Note>
|
||||
|
||||
### Model pricing
|
||||
|
||||
The table below shows the price per million tokens for each model:
|
||||
|
||||
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|
||||
| -------------------------------------------------------------------------- | ----------------- | --------------- | --------------- | ---------------------- | ------------- |
|
||||
| Claude Opus 4.1 | \$15 / MTok | \$18.75 / MTok | \$30 / MTok | \$1.50 / MTok | \$75 / MTok |
|
||||
| Claude Opus 4 | \$15 / MTok | \$18.75 / MTok | \$30 / MTok | \$1.50 / MTok | \$75 / MTok |
|
||||
| Claude Sonnet 4.5 | \$3 / MTok | \$3.75 / MTok | \$6 / MTok | \$0.30 / MTok | \$15 / MTok |
|
||||
| Claude Sonnet 4 | \$3 / MTok | \$3.75 / MTok | \$6 / MTok | \$0.30 / MTok | \$15 / MTok |
|
||||
| Claude Sonnet 3.7 | \$3 / MTok | \$3.75 / MTok | \$6 / MTok | \$0.30 / MTok | \$15 / MTok |
|
||||
| Claude Sonnet 3.5 ([deprecated](/en/docs/about-claude/model-deprecations)) | \$3 / MTok | \$3.75 / MTok | \$6 / MTok | \$0.30 / MTok | \$15 / MTok |
|
||||
| Claude Haiku 4.5 | \$1 / MTok | \$1.25 / MTok | \$2 / MTok | \$0.10 / MTok | \$5 / MTok |
|
||||
| Claude Haiku 3.5 | \$0.80 / MTok | \$1 / MTok | \$1.6 / MTok | \$0.08 / MTok | \$4 / MTok |
|
||||
| Claude Opus 3 ([deprecated](/en/docs/about-claude/model-deprecations)) | \$15 / MTok | \$18.75 / MTok | \$30 / MTok | \$1.50 / MTok | \$75 / MTok |
|
||||
| Claude Haiku 3 | \$0.25 / MTok | \$0.30 / MTok | \$0.50 / MTok | \$0.03 / MTok | \$1.25 / MTok |
|
||||
|
||||
## Prompt and output performance
|
||||
|
||||
Claude 4 models excel in:
|
||||
|
||||
* **Performance**: Top-tier results in reasoning, coding, multilingual tasks, long-context handling, honesty, and image processing. See the [Claude 4 blog post](http://www.anthropic.com/news/claude-4) for more information.
|
||||
* **Engaging responses**: Claude models are ideal for applications that require rich, human-like interactions.
|
||||
|
||||
* If you prefer more concise responses, you can adjust your prompts to guide the model toward the desired output length. Refer to our [prompt engineering guides](/en/docs/build-with-claude/prompt-engineering) for details.
|
||||
* For specific Claude 4 prompting best practices, see our [Claude 4 best practices guide](/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices).
|
||||
* **Output quality**: When migrating from previous model generations to Claude 4, you may notice larger improvements in overall performance.
|
||||
|
||||
## Migrating to Claude 4.5
|
||||
|
||||
If you're currently using Claude 3 models, we recommend migrating to Claude 4.5 to take advantage of improved intelligence and enhanced capabilities. For detailed migration instructions, see [Migrating to Claude 4.5](/en/docs/about-claude/models/migrating-to-claude-4).
|
||||
|
||||
## Get started with Claude
|
||||
|
||||
If you're ready to start exploring what Claude can do for you, let's dive in! Whether you're a developer looking to integrate Claude into your applications or a user wanting to experience the power of AI firsthand, we've got you covered.
|
||||
|
||||
<Note>Looking to chat with Claude? Visit [claude.ai](http://www.claude.ai)!</Note>
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Intro to Claude" icon="check" href="/en/docs/intro-to-claude">
|
||||
Explore Claude’s capabilities and development flow.
|
||||
</Card>
|
||||
|
||||
<Card title="Quickstart" icon="bolt-lightning" href="/en/resources/quickstarts">
|
||||
Learn how to make your first API call in minutes.
|
||||
</Card>
|
||||
|
||||
<Card title="Claude Console" icon="code" href="https://console.anthropic.com">
|
||||
Craft and test powerful prompts directly in your browser.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
If you have any questions or need assistance, don't hesitate to reach out to our [support team](https://support.claude.com/) or consult the [Discord community](https://www.anthropic.com/discord).
|
||||
@@ -0,0 +1,376 @@
|
||||
# Plugins reference
|
||||
|
||||
> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.
|
||||
|
||||
<Tip>
|
||||
For hands-on tutorials and practical usage, see [Plugins](/en/docs/claude-code/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).
|
||||
</Tip>
|
||||
|
||||
This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.
|
||||
|
||||
## Plugin components reference
|
||||
|
||||
This section documents the five types of components that plugins can provide.
|
||||
|
||||
### Commands
|
||||
|
||||
Plugins add custom slash commands that integrate seamlessly with Claude Code's command system.
|
||||
|
||||
**Location**: `commands/` directory in plugin root
|
||||
|
||||
**File format**: Markdown files with frontmatter
|
||||
|
||||
For complete details on plugin command structure, invocation patterns, and features, see [Plugin commands](/en/docs/claude-code/slash-commands#plugin-commands).
|
||||
|
||||
### Agents
|
||||
|
||||
Plugins can provide specialized subagents for specific tasks that Claude can invoke automatically when appropriate.
|
||||
|
||||
**Location**: `agents/` directory in plugin root
|
||||
|
||||
**File format**: Markdown files describing agent capabilities
|
||||
|
||||
**Agent structure**:
|
||||
|
||||
```markdown theme={null}
|
||||
---
|
||||
description: What this agent specializes in
|
||||
capabilities: ["task1", "task2", "task3"]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
Detailed description of the agent's role, expertise, and when Claude should invoke it.
|
||||
|
||||
## Capabilities
|
||||
- Specific task the agent excels at
|
||||
- Another specialized capability
|
||||
- When to use this agent vs others
|
||||
|
||||
## Context and examples
|
||||
Provide examples of when this agent should be used and what kinds of problems it solves.
|
||||
```
|
||||
|
||||
**Integration points**:
|
||||
|
||||
* Agents appear in the `/agents` interface
|
||||
* Claude can invoke agents automatically based on task context
|
||||
* Agents can be invoked manually by users
|
||||
* Plugin agents work alongside built-in Claude agents
|
||||
|
||||
### Skills
|
||||
|
||||
Plugins can provide Agent Skills that extend Claude's capabilities. Skills are model-invoked—Claude autonomously decides when to use them based on the task context.
|
||||
|
||||
**Location**: `skills/` directory in plugin root
|
||||
|
||||
**File format**: Directories containing `SKILL.md` files with frontmatter
|
||||
|
||||
**Skill structure**:
|
||||
|
||||
```
|
||||
skills/
|
||||
├── pdf-processor/
|
||||
│ ├── SKILL.md
|
||||
│ ├── reference.md (optional)
|
||||
│ └── scripts/ (optional)
|
||||
└── code-reviewer/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
**Integration behavior**:
|
||||
|
||||
* Plugin Skills are automatically discovered when the plugin is installed
|
||||
* Claude autonomously invokes Skills based on matching task context
|
||||
* Skills can include supporting files alongside SKILL.md
|
||||
|
||||
For SKILL.md format and complete Skill authoring guidance, see:
|
||||
|
||||
* [Use Skills in Claude Code](/en/docs/claude-code/skills)
|
||||
* [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure)
|
||||
|
||||
### Hooks
|
||||
|
||||
Plugins can provide event handlers that respond to Claude Code events automatically.
|
||||
|
||||
**Location**: `hooks/hooks.json` in plugin root, or inline in plugin.json
|
||||
|
||||
**Format**: JSON configuration with event matchers and actions
|
||||
|
||||
**Hook configuration**:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available events**:
|
||||
|
||||
* `PreToolUse`: Before Claude uses any tool
|
||||
* `PostToolUse`: After Claude uses any tool
|
||||
* `UserPromptSubmit`: When user submits a prompt
|
||||
* `Notification`: When Claude Code sends notifications
|
||||
* `Stop`: When Claude attempts to stop
|
||||
* `SubagentStop`: When a subagent attempts to stop
|
||||
* `SessionStart`: At the beginning of sessions
|
||||
* `SessionEnd`: At the end of sessions
|
||||
* `PreCompact`: Before conversation history is compacted
|
||||
|
||||
**Hook types**:
|
||||
|
||||
* `command`: Execute shell commands or scripts
|
||||
* `validation`: Validate file contents or project state
|
||||
* `notification`: Send alerts or status updates
|
||||
|
||||
### MCP servers
|
||||
|
||||
Plugins can bundle Model Context Protocol (MCP) servers to connect Claude Code with external tools and services.
|
||||
|
||||
**Location**: `.mcp.json` in plugin root, or inline in plugin.json
|
||||
|
||||
**Format**: Standard MCP server configuration
|
||||
|
||||
**MCP server configuration**:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"mcpServers": {
|
||||
"plugin-database": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
|
||||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
|
||||
"env": {
|
||||
"DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
|
||||
}
|
||||
},
|
||||
"plugin-api-client": {
|
||||
"command": "npx",
|
||||
"args": ["@company/mcp-server", "--plugin-mode"],
|
||||
"cwd": "${CLAUDE_PLUGIN_ROOT}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Integration behavior**:
|
||||
|
||||
* Plugin MCP servers start automatically when the plugin is enabled
|
||||
* Servers appear as standard MCP tools in Claude's toolkit
|
||||
* Server capabilities integrate seamlessly with Claude's existing tools
|
||||
* Plugin servers can be configured independently of user MCP servers
|
||||
|
||||
***
|
||||
|
||||
## Plugin manifest schema
|
||||
|
||||
The `plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.
|
||||
|
||||
### Complete schema
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"version": "1.2.0",
|
||||
"description": "Brief plugin description",
|
||||
"author": {
|
||||
"name": "Author Name",
|
||||
"email": "author@example.com",
|
||||
"url": "https://github.com/author"
|
||||
},
|
||||
"homepage": "https://docs.example.com/plugin",
|
||||
"repository": "https://github.com/author/plugin",
|
||||
"license": "MIT",
|
||||
"keywords": ["keyword1", "keyword2"],
|
||||
"commands": ["./custom/commands/special.md"],
|
||||
"agents": "./custom/agents/",
|
||||
"hooks": "./config/hooks.json",
|
||||
"mcpServers": "./mcp-config.json"
|
||||
}
|
||||
```
|
||||
|
||||
### Required fields
|
||||
|
||||
| Field | Type | Description | Example |
|
||||
| :----- | :----- | :---------------------------------------- | :------------------- |
|
||||
| `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` |
|
||||
|
||||
### Metadata fields
|
||||
|
||||
| Field | Type | Description | Example |
|
||||
| :------------ | :----- | :---------------------------------- | :------------------------------------------------- |
|
||||
| `version` | string | Semantic version | `"2.1.0"` |
|
||||
| `description` | string | Brief explanation of plugin purpose | `"Deployment automation tools"` |
|
||||
| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` |
|
||||
| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
|
||||
| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
|
||||
| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
|
||||
| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
|
||||
|
||||
### Component path fields
|
||||
|
||||
| Field | Type | Description | Example |
|
||||
| :----------- | :------------- | :----------------------------------- | :------------------------------------- |
|
||||
| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` |
|
||||
| `agents` | string\|array | Additional agent files | `"./custom/agents/"` |
|
||||
| `hooks` | string\|object | Hook config path or inline config | `"./hooks.json"` |
|
||||
| `mcpServers` | string\|object | MCP config path or inline config | `"./mcp.json"` |
|
||||
|
||||
### Path behavior rules
|
||||
|
||||
**Important**: Custom paths supplement default directories - they don't replace them.
|
||||
|
||||
* If `commands/` exists, it's loaded in addition to custom command paths
|
||||
* All paths must be relative to plugin root and start with `./`
|
||||
* Commands from custom paths use the same naming and namespacing rules
|
||||
* Multiple paths can be specified as arrays for flexibility
|
||||
|
||||
**Path examples**:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"commands": [
|
||||
"./specialized/deploy.md",
|
||||
"./utilities/batch-process.md"
|
||||
],
|
||||
"agents": [
|
||||
"./custom-agents/reviewer.md",
|
||||
"./custom-agents/tester.md"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Environment variables
|
||||
|
||||
**`${CLAUDE_PLUGIN_ROOT}`**: Contains the absolute path to your plugin directory. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Plugin directory structure
|
||||
|
||||
### Standard plugin layout
|
||||
|
||||
A complete plugin follows this structure:
|
||||
|
||||
```
|
||||
enterprise-plugin/
|
||||
├── .claude-plugin/ # Metadata directory
|
||||
│ └── plugin.json # Required: plugin manifest
|
||||
├── commands/ # Default command location
|
||||
│ ├── status.md
|
||||
│ └── logs.md
|
||||
├── agents/ # Default agent location
|
||||
│ ├── security-reviewer.md
|
||||
│ ├── performance-tester.md
|
||||
│ └── compliance-checker.md
|
||||
├── skills/ # Agent Skills
|
||||
│ ├── code-reviewer/
|
||||
│ │ └── SKILL.md
|
||||
│ └── pdf-processor/
|
||||
│ ├── SKILL.md
|
||||
│ └── scripts/
|
||||
├── hooks/ # Hook configurations
|
||||
│ ├── hooks.json # Main hook config
|
||||
│ └── security-hooks.json # Additional hooks
|
||||
├── .mcp.json # MCP server definitions
|
||||
├── scripts/ # Hook and utility scripts
|
||||
│ ├── security-scan.sh
|
||||
│ ├── format-code.py
|
||||
│ └── deploy.js
|
||||
├── LICENSE # License file
|
||||
└── CHANGELOG.md # Version history
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.
|
||||
</Warning>
|
||||
|
||||
### File locations reference
|
||||
|
||||
| Component | Default Location | Purpose |
|
||||
| :-------------- | :--------------------------- | :------------------------------- |
|
||||
| **Manifest** | `.claude-plugin/plugin.json` | Required metadata file |
|
||||
| **Commands** | `commands/` | Slash command markdown files |
|
||||
| **Agents** | `agents/` | Subagent markdown files |
|
||||
| **Skills** | `skills/` | Agent Skills with SKILL.md files |
|
||||
| **Hooks** | `hooks/hooks.json` | Hook configuration |
|
||||
| **MCP servers** | `.mcp.json` | MCP server definitions |
|
||||
|
||||
***
|
||||
|
||||
## Debugging and development tools
|
||||
|
||||
### Debugging commands
|
||||
|
||||
Use `claude --debug` to see plugin loading details:
|
||||
|
||||
```bash theme={null}
|
||||
claude --debug
|
||||
```
|
||||
|
||||
This shows:
|
||||
|
||||
* Which plugins are being loaded
|
||||
* Any errors in plugin manifests
|
||||
* Command, agent, and hook registration
|
||||
* MCP server initialization
|
||||
|
||||
### Common issues
|
||||
|
||||
| Issue | Cause | Solution |
|
||||
| :--------------------- | :------------------------------ | :--------------------------------------------------- |
|
||||
| Plugin not loading | Invalid `plugin.json` | Validate JSON syntax |
|
||||
| Commands not appearing | Wrong directory structure | Ensure `commands/` at root, not in `.claude-plugin/` |
|
||||
| Hooks not firing | Script not executable | Run `chmod +x script.sh` |
|
||||
| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |
|
||||
| Path errors | Absolute paths used | All paths must be relative and start with `./` |
|
||||
|
||||
***
|
||||
|
||||
## Distribution and versioning reference
|
||||
|
||||
### Version management
|
||||
|
||||
Follow semantic versioning for plugin releases:
|
||||
|
||||
```json theme={null}
|
||||
|
||||
## See also
|
||||
|
||||
- [Plugins](/en/docs/claude-code/plugins) - Tutorials and practical usage
|
||||
- [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces) - Creating and managing marketplaces
|
||||
- [Slash commands](/en/docs/claude-code/slash-commands) - Command development details
|
||||
- [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities
|
||||
- [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities
|
||||
- [Hooks](/en/docs/claude-code/hooks) - Event handling and automation
|
||||
- [MCP](/en/docs/claude-code/mcp) - External tool integration
|
||||
- [Settings](/en/docs/claude-code/settings) - Configuration options for plugins
|
||||
```
|
||||
@@ -0,0 +1,295 @@
|
||||
# Streaming Input
|
||||
|
||||
> Understanding the two input modes for Claude Agent SDK and when to use each
|
||||
|
||||
## Overview
|
||||
|
||||
The Claude Agent SDK supports two distinct input modes for interacting with agents:
|
||||
|
||||
* **Streaming Input Mode** (Default & Recommended) - A persistent, interactive session
|
||||
* **Single Message Input** - One-shot queries that use session state and resuming
|
||||
|
||||
This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application.
|
||||
|
||||
## Streaming Input Mode (Recommended)
|
||||
|
||||
Streaming input mode is the **preferred** way to use the Claude Agent SDK. It provides full access to the agent's capabilities and enables rich, interactive experiences.
|
||||
|
||||
It allows the agent to operate as a long lived process that takes in user input, handles interruptions, surfaces permission requests, and handles session management.
|
||||
|
||||
### How It Works
|
||||
|
||||
```mermaid theme={null}
|
||||
%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
|
||||
sequenceDiagram
|
||||
participant App as Your Application
|
||||
participant Agent as Claude Agent
|
||||
participant Tools as Tools/Hooks
|
||||
participant FS as Environment/<br/>File System
|
||||
|
||||
App->>Agent: Initialize with AsyncGenerator
|
||||
activate Agent
|
||||
|
||||
App->>Agent: Yield Message 1
|
||||
Agent->>Tools: Execute tools
|
||||
Tools->>FS: Read files
|
||||
FS-->>Tools: File contents
|
||||
Tools->>FS: Write/Edit files
|
||||
FS-->>Tools: Success/Error
|
||||
Agent-->>App: Stream partial response
|
||||
Agent-->>App: Stream more content...
|
||||
Agent->>App: Complete Message 1
|
||||
|
||||
App->>Agent: Yield Message 2 + Image
|
||||
Agent->>Tools: Process image & execute
|
||||
Tools->>FS: Access filesystem
|
||||
FS-->>Tools: Operation results
|
||||
Agent-->>App: Stream response 2
|
||||
|
||||
App->>Agent: Queue Message 3
|
||||
App->>Agent: Interrupt/Cancel
|
||||
Agent->>App: Handle interruption
|
||||
|
||||
Note over App,Agent: Session stays alive
|
||||
Note over Tools,FS: Persistent file system<br/>state maintained
|
||||
|
||||
deactivate Agent
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Image Uploads" icon="image">
|
||||
Attach images directly to messages for visual analysis and understanding
|
||||
</Card>
|
||||
|
||||
<Card title="Queued Messages" icon="layer-group">
|
||||
Send multiple messages that process sequentially, with ability to interrupt
|
||||
</Card>
|
||||
|
||||
<Card title="Tool Integration" icon="wrench">
|
||||
Full access to all tools and custom MCP servers during the session
|
||||
</Card>
|
||||
|
||||
<Card title="Hooks Support" icon="link">
|
||||
Use lifecycle hooks to customize behavior at various points
|
||||
</Card>
|
||||
|
||||
<Card title="Real-time Feedback" icon="bolt">
|
||||
See responses as they're generated, not just final results
|
||||
</Card>
|
||||
|
||||
<Card title="Context Persistence" icon="database">
|
||||
Maintain conversation context across multiple turns naturally
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Implementation Example
|
||||
|
||||
<CodeGroup>
|
||||
```typescript TypeScript theme={null}
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
import { readFileSync } from "fs";
|
||||
|
||||
async function* generateMessages() {
|
||||
// First message
|
||||
yield {
|
||||
type: "user" as const,
|
||||
message: {
|
||||
role: "user" as const,
|
||||
content: "Analyze this codebase for security issues"
|
||||
}
|
||||
};
|
||||
|
||||
// Wait for conditions or user input
|
||||
await new Promise(resolve => setTimeout(resolve, 2000));
|
||||
|
||||
// Follow-up with image
|
||||
yield {
|
||||
type: "user" as const,
|
||||
message: {
|
||||
role: "user" as const,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: "Review this architecture diagram"
|
||||
},
|
||||
{
|
||||
type: "image",
|
||||
source: {
|
||||
type: "base64",
|
||||
media_type: "image/png",
|
||||
data: readFileSync("diagram.png", "base64")
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Process streaming responses
|
||||
for await (const message of query({
|
||||
prompt: generateMessages(),
|
||||
options: {
|
||||
maxTurns: 10,
|
||||
allowedTools: ["Read", "Grep"]
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```python Python theme={null}
|
||||
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
|
||||
import asyncio
|
||||
import base64
|
||||
|
||||
async def streaming_analysis():
|
||||
async def message_generator():
|
||||
# First message
|
||||
yield {
|
||||
"type": "user",
|
||||
"message": {
|
||||
"role": "user",
|
||||
"content": "Analyze this codebase for security issues"
|
||||
}
|
||||
}
|
||||
|
||||
# Wait for conditions
|
||||
await asyncio.sleep(2)
|
||||
|
||||
# Follow-up with image
|
||||
with open("diagram.png", "rb") as f:
|
||||
image_data = base64.b64encode(f.read()).decode()
|
||||
|
||||
yield {
|
||||
"type": "user",
|
||||
"message": {
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Review this architecture diagram"
|
||||
},
|
||||
{
|
||||
"type": "image",
|
||||
"source": {
|
||||
"type": "base64",
|
||||
"media_type": "image/png",
|
||||
"data": image_data
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
# Use ClaudeSDKClient for streaming input
|
||||
options = ClaudeAgentOptions(
|
||||
max_turns=10,
|
||||
allowed_tools=["Read", "Grep"]
|
||||
)
|
||||
|
||||
async with ClaudeSDKClient(options) as client:
|
||||
# Send streaming input
|
||||
await client.query(message_generator())
|
||||
|
||||
# Process responses
|
||||
async for message in client.receive_response():
|
||||
if isinstance(message, AssistantMessage):
|
||||
for block in message.content:
|
||||
if isinstance(block, TextBlock):
|
||||
print(block.text)
|
||||
|
||||
asyncio.run(streaming_analysis())
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Single Message Input
|
||||
|
||||
Single message input is simpler but more limited.
|
||||
|
||||
### When to Use Single Message Input
|
||||
|
||||
Use single message input when:
|
||||
|
||||
* You need a one-shot response
|
||||
* You do not need image attachments, hooks, etc.
|
||||
* You need to operate in a stateless environment, such as a lambda function
|
||||
|
||||
### Limitations
|
||||
|
||||
<Warning>
|
||||
Single message input mode does **not** support:
|
||||
|
||||
* Direct image attachments in messages
|
||||
* Dynamic message queueing
|
||||
* Real-time interruption
|
||||
* Hook integration
|
||||
* Natural multi-turn conversations
|
||||
</Warning>
|
||||
|
||||
### Implementation Example
|
||||
|
||||
<CodeGroup>
|
||||
```typescript TypeScript theme={null}
|
||||
import { query } from "@anthropic-ai/claude-agent-sdk";
|
||||
|
||||
// Simple one-shot query
|
||||
for await (const message of query({
|
||||
prompt: "Explain the authentication flow",
|
||||
options: {
|
||||
maxTurns: 1,
|
||||
allowedTools: ["Read", "Grep"]
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
|
||||
// Continue conversation with session management
|
||||
for await (const message of query({
|
||||
prompt: "Now explain the authorization process",
|
||||
options: {
|
||||
continue: true,
|
||||
maxTurns: 1
|
||||
}
|
||||
})) {
|
||||
if (message.type === "result") {
|
||||
console.log(message.result);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```python Python theme={null}
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
|
||||
import asyncio
|
||||
|
||||
async def single_message_example():
|
||||
# Simple one-shot query using query() function
|
||||
async for message in query(
|
||||
prompt="Explain the authentication flow",
|
||||
options=ClaudeAgentOptions(
|
||||
max_turns=1,
|
||||
allowed_tools=["Read", "Grep"]
|
||||
)
|
||||
):
|
||||
if isinstance(message, ResultMessage):
|
||||
print(message.result)
|
||||
|
||||
# Continue conversation with session management
|
||||
async for message in query(
|
||||
prompt="Now explain the authorization process",
|
||||
options=ClaudeAgentOptions(
|
||||
continue_conversation=True,
|
||||
max_turns=1
|
||||
)
|
||||
):
|
||||
if isinstance(message, ResultMessage):
|
||||
print(message.result)
|
||||
|
||||
asyncio.run(single_message_example())
|
||||
```
|
||||
</CodeGroup>
|
||||
Reference in New Issue
Block a user