claude-code-plugins-sdk 0.1.0__tar.gz

claude_code_plugins_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff (lint)
+        run: uv run ruff check .
+
+      - name: Ruff (format)
+        run: uv run ruff format --check .
+
+      - name: Pytest
+        run: uv run pytest -m "not integration"

claude_code_plugins_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

claude_code_plugins_sdk-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.mypy_cache/
+.pyrightcache/
+.tycache/
+.ruff_cache/
+.pytest_cache/

claude_code_plugins_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

claude_code_plugins_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: claude-code-plugins-sdk
+Version: 0.1.0
+Summary: Python SDK for Claude Code plugins and marketplaces
+Project-URL: Repository, https://github.com/doron-cohen/claude-code-plugins-sdk
+Author-email: Doron Cohen <4966182+doron-cohen@users.noreply.github.com>
+License: MIT
+Keywords: anthropic,claude,claude-code,marketplace,plugins,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-frontmatter>=1.1
+Description-Content-Type: text/markdown
+
+# claude-code-plugins-sdk
+
+A Python library for working with Claude Code plugins and marketplaces.
+
+Claude Code has a plugin ecosystem — agents, skills, commands, hooks, MCP servers — but no official Python tooling to work with it. This library lets you load, parse, and validate plugins and marketplaces from disk or from remote sources.
+
+## Install
+
+```bash
+pip install claude-code-plugins-sdk
+```
+
+Requires Python 3.10+.
+
+## What you can do
+
+Load a local marketplace and inspect its plugins:
+
+```python
+from pathlib import Path
+from claude_code_plugins_sdk import load_marketplace
+
+marketplace = load_marketplace(Path("./my-marketplace"))
+
+for plugin in marketplace.plugins:
+    print(plugin.name, plugin.version)
+```
+
+Fetch a marketplace from GitHub:
+
+```python
+from claude_code_plugins_sdk import fetch_marketplace
+
+# GitHub shorthand
+marketplace = fetch_marketplace("anthropics/claude-code")
+
+# Pinned to a tag
+from claude_code_plugins_sdk import GitHubSource
+marketplace = fetch_marketplace(GitHubSource(source="github", repo="anthropics/claude-code", ref="v1.0"))
+
+# Raw URL to a marketplace.json
+marketplace = fetch_marketplace("https://example.com/.claude-plugin/marketplace.json")
+```
+
+Load a plugin directory and read its agents, skills, commands, and hooks:
+
+```python
+from pathlib import Path
+from claude_code_plugins_sdk import load_plugin
+
+plugin = load_plugin(Path("./my-plugin"))
+
+print(plugin.manifest.name)       # plugin name from plugin.json
+print(plugin.agents)              # list of AgentDefinition
+print(plugin.skills)              # list of SkillDefinition
+print(plugin.commands)            # list of CommandDefinition
+print(plugin.hooks)               # HooksConfig or None
+print(plugin.mcp_servers)         # MCPServersConfig or None
+```
+
+Load individual component files directly:
+
+```python
+from claude_code_plugins_sdk import load_agent, load_skill, load_command
+
+agent = load_agent(Path("./agents/reviewer.md"))
+print(agent.name, agent.tools)   # tools is always a list, even though YAML stores it as a comma string
+
+skill = load_skill(Path("./skills/code-review/SKILL.md"))
+command = load_command(Path("./commands/review.md"))
+```
+
+## Plugin structure
+
+A Claude Code plugin is a directory with this layout:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json      # optional manifest
+├── agents/              # *.md files with YAML frontmatter
+├── skills/              # */SKILL.md files
+├── commands/            # *.md files
+├── hooks/
+│   └── hooks.json
+├── .mcp.json
+└── .lsp.json
+```
+
+A marketplace is a directory with `.claude-plugin/marketplace.json` listing plugins and where to find them.
+
+## Development
+
+```bash
+git clone git@github.com:doron-cohen/claude-code-plugins-sdk.git
+cd claude-code-plugins-sdk
+uv sync
+uv run pytest
+```
+
+```bash
+uv run pytest -m integration  # hits real remote marketplaces, needs network
+```

claude_code_plugins_sdk-0.1.0/README.md

@@ -0,0 +1,103 @@
+# claude-code-plugins-sdk
+
+A Python library for working with Claude Code plugins and marketplaces.
+
+Claude Code has a plugin ecosystem — agents, skills, commands, hooks, MCP servers — but no official Python tooling to work with it. This library lets you load, parse, and validate plugins and marketplaces from disk or from remote sources.
+
+## Install
+
+```bash
+pip install claude-code-plugins-sdk
+```
+
+Requires Python 3.10+.
+
+## What you can do
+
+Load a local marketplace and inspect its plugins:
+
+```python
+from pathlib import Path
+from claude_code_plugins_sdk import load_marketplace
+
+marketplace = load_marketplace(Path("./my-marketplace"))
+
+for plugin in marketplace.plugins:
+    print(plugin.name, plugin.version)
+```
+
+Fetch a marketplace from GitHub:
+
+```python
+from claude_code_plugins_sdk import fetch_marketplace
+
+# GitHub shorthand
+marketplace = fetch_marketplace("anthropics/claude-code")
+
+# Pinned to a tag
+from claude_code_plugins_sdk import GitHubSource
+marketplace = fetch_marketplace(GitHubSource(source="github", repo="anthropics/claude-code", ref="v1.0"))
+
+# Raw URL to a marketplace.json
+marketplace = fetch_marketplace("https://example.com/.claude-plugin/marketplace.json")
+```
+
+Load a plugin directory and read its agents, skills, commands, and hooks:
+
+```python
+from pathlib import Path
+from claude_code_plugins_sdk import load_plugin
+
+plugin = load_plugin(Path("./my-plugin"))
+
+print(plugin.manifest.name)       # plugin name from plugin.json
+print(plugin.agents)              # list of AgentDefinition
+print(plugin.skills)              # list of SkillDefinition
+print(plugin.commands)            # list of CommandDefinition
+print(plugin.hooks)               # HooksConfig or None
+print(plugin.mcp_servers)         # MCPServersConfig or None
+```
+
+Load individual component files directly:
+
+```python
+from claude_code_plugins_sdk import load_agent, load_skill, load_command
+
+agent = load_agent(Path("./agents/reviewer.md"))
+print(agent.name, agent.tools)   # tools is always a list, even though YAML stores it as a comma string
+
+skill = load_skill(Path("./skills/code-review/SKILL.md"))
+command = load_command(Path("./commands/review.md"))
+```
+
+## Plugin structure
+
+A Claude Code plugin is a directory with this layout:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json      # optional manifest
+├── agents/              # *.md files with YAML frontmatter
+├── skills/              # */SKILL.md files
+├── commands/            # *.md files
+├── hooks/
+│   └── hooks.json
+├── .mcp.json
+└── .lsp.json
+```
+
+A marketplace is a directory with `.claude-plugin/marketplace.json` listing plugins and where to find them.
+
+## Development
+
+```bash
+git clone git@github.com:doron-cohen/claude-code-plugins-sdk.git
+cd claude-code-plugins-sdk
+uv sync
+uv run pytest
+```
+
+```bash
+uv run pytest -m integration  # hits real remote marketplaces, needs network
+```

claude_code_plugins_sdk-0.1.0/plans/20260221-1851-phase1-sdk.md

@@ -0,0 +1,391 @@
+# Phase 1 SDK — Core Models & Loaders
+
+**Goal:** A working Python library that can load a marketplace file and a plugin directory, validate them against the official Claude Code schema, and expose typed Python objects.
+
+**Scope:** Read-only. No HTTP, no installs, no CLI.
+
+---
+
+## What to build
+
+### 1. Package skeleton
+
+`src/claude_code_plugins_sdk/` with a `src` layout (already scaffolded by uv).
+
+```
+src/claude_code_plugins_sdk/
+├── __init__.py          ← re-export the public API
+├── errors.py            ← LoadError
+├── models/
+│   ├── __init__.py
+│   ├── plugin.py        ← PluginManifest, Author
+│   ├── marketplace.py   ← MarketplaceManifest, PluginEntry, source types
+│   ├── agent.py         ← AgentDefinition
+│   ├── skill.py         ← SkillDefinition
+│   ├── command.py       ← CommandDefinition
+│   ├── hook.py          ← HooksConfig, HookEvent, HookEntry
+│   ├── mcp.py           ← MCPServersConfig
+│   └── lsp.py           ← LSPServersConfig
+├── loaders/
+│   ├── __init__.py
+│   ├── marketplace.py   ← load_marketplace(path)
+│   └── plugin.py        ← load_plugin(path) → Plugin
+└── _plugin.py           ← Plugin dataclass (domain object)
+```
+
+### 2. Models
+
+All models are Pydantic v2 with `model_config = ConfigDict(extra="allow", populate_by_name=True)`.
+Never break on unknown fields — the ecosystem evolves.
+
+#### `plugin.py` — `.claude-plugin/plugin.json`
+
+```python
+class Author(BaseModel):
+    name: str
+    email: str | None = None
+    url: str | None = None
+
+class PluginManifest(BaseModel):
+    name: str
+    version: str | None = None
+    description: str | None = None
+    author: Author | None = None
+    homepage: str | None = None
+    repository: str | None = None
+    license: str | None = None
+    keywords: list[str] = []
+    # component paths — each can be str, list[str], or dict (inline config)
+    commands: str | list[str] | None = None
+    agents: str | list[str] | None = None
+    skills: str | list[str] | None = None
+    hooks: str | list[str] | dict[str, Any] | None = None
+    mcp_servers: str | list[str] | dict[str, Any] | None = Field(None, alias="mcpServers")
+    output_styles: str | list[str] | None = Field(None, alias="outputStyles")
+    lsp_servers: str | list[str] | dict[str, Any] | None = Field(None, alias="lspServers")
+```
+
+#### `marketplace.py` — `.claude-plugin/marketplace.json`
+
+Plugin source is a discriminated union. A plain string is a relative path.
+Object sources are discriminated on the `source` field: `"github"`, `"url"`, `"npm"`, `"pip"`.
+
+```python
+class GitHubSource(BaseModel):
+    source: Literal["github"]
+    repo: str          # "owner/repo"
+    ref: str | None = None
+    sha: str | None = None
+
+class URLSource(BaseModel):
+    source: Literal["url"]
+    url: str           # must end with .git
+    ref: str | None = None
+    sha: str | None = None
+
+class NPMSource(BaseModel):
+    source: Literal["npm"]
+    package: str
+    version: str | None = None
+    registry: str | None = None
+
+class PIPSource(BaseModel):
+    source: Literal["pip"]
+    package: str
+    version: str | None = None
+    registry: str | None = None
+
+PluginSource = Annotated[
+    GitHubSource | URLSource | NPMSource | PIPSource,
+    Field(discriminator="source")
+]
+
+class MarketplaceOwner(BaseModel):
+    name: str
+    email: str | None = None
+
+class MarketplaceMetadata(BaseModel):
+    description: str | None = None
+    version: str | None = None
+    plugin_root: str | None = Field(None, alias="pluginRoot")
+
+class PluginEntry(BaseModel):
+    # source is str (relative path) OR one of the typed source objects
+    name: str
+    source: str | PluginSource
+    description: str | None = None
+    version: str | None = None
+    author: Author | None = None
+    homepage: str | None = None
+    repository: str | None = None
+    license: str | None = None
+    keywords: list[str] = []
+    category: str | None = None
+    tags: list[str] = []
+    strict: bool = True
+    # inline component paths (same as PluginManifest)
+    commands: ...
+    agents: ...
+    hooks: ...
+    mcp_servers: ...
+    lsp_servers: ...
+
+class MarketplaceManifest(BaseModel):
+    schema_url: str | None = Field(None, alias="$schema")
+    name: str
+    version: str | None = None
+    description: str | None = None
+    owner: MarketplaceOwner
+    metadata: MarketplaceMetadata | None = None
+    plugins: list[PluginEntry]
+```
+
+#### `agent.py` — `agents/*.md` frontmatter
+
+The `tools` field is a **comma-separated string** in the YAML, not a list. Parse it in a validator.
+
+```python
+class AgentDefinition(BaseModel):
+    name: str
+    description: str
+    tools: list[str] = []   # stored as "Read, Write, Bash" in YAML
+    color: str | None = None
+    body: str = ""          # markdown body (the agent system prompt)
+
+    @field_validator("tools", mode="before")
+    @classmethod
+    def parse_tools_string(cls, v):
+        if isinstance(v, str):
+            return [t.strip() for t in v.split(",") if t.strip()]
+        return v
+```
+
+#### `skill.py` — `skills/<name>/SKILL.md` frontmatter
+
+```python
+class SkillDefinition(BaseModel):
+    description: str | None = None
+    name: str | None = None
+    disable_model_invocation: bool = Field(False, alias="disable-model-invocation")
+    body: str = ""
+```
+
+#### `command.py` — `commands/*.md` frontmatter
+
+Note: `allowed-tools` is a **YAML list**, not a comma-separated string (opposite of agents).
+
+```python
+class CommandDefinition(BaseModel):
+    name: str | None = None
+    description: str | None = None
+    argument_hint: str | None = Field(None, alias="argument-hint")
+    allowed_tools: list[str] = Field([], alias="allowed-tools")
+    agent: str | None = None
+    body: str = ""
+```
+
+#### `hook.py` — `hooks/hooks.json`
+
+```python
+class HookEntry(BaseModel):
+    type: Literal["command", "prompt", "agent"]
+    command: str | None = None   # for type="command"
+    prompt: str | None = None    # for type="prompt"
+    agent: str | None = None     # for type="agent"
+
+class HookMatcher(BaseModel):
+    matcher: str | None = None
+    hooks: list[HookEntry]
+
+HookEvent = Literal[
+    "PreToolUse", "PostToolUse", "PostToolUseFailure",
+    "SessionStart", "SessionEnd",
+    "SubagentStart", "SubagentStop",
+    "Stop", "Notification",
+    "UserPromptSubmit", "PermissionRequest",
+    "PreCompact", "TaskCompleted", "TeammateIdle",
+]
+
+class HooksConfig(BaseModel):
+    hooks: dict[str, list[HookMatcher]]  # event name → matchers
+```
+
+#### `mcp.py` — `.mcp.json`
+
+```python
+class MCPServerConfig(BaseModel):
+    command: str
+    args: list[str] = []
+    env: dict[str, str] = {}
+    cwd: str | None = None
+
+class MCPServersConfig(BaseModel):
+    mcp_servers: dict[str, MCPServerConfig] = Field({}, alias="mcpServers")
+```
+
+#### `lsp.py` — `.lsp.json`
+
+```python
+class LSPServerConfig(BaseModel):
+    command: str
+    extension_to_language: dict[str, str] = Field({}, alias="extensionToLanguage")
+    args: list[str] = []
+    transport: Literal["stdio", "socket"] = "stdio"
+    env: dict[str, str] = {}
+    # ... other optional fields
+
+LSPServersConfig = dict[str, LSPServerConfig]
+```
+
+### 3. `Plugin` domain object
+
+```python
+@dataclass
+class Plugin:
+    root: Path
+    manifest: PluginManifest | None
+    agents: list[AgentDefinition]
+    commands: list[CommandDefinition]
+    skills: list[SkillDefinition]
+    hooks: HooksConfig | None
+    mcp_servers: MCPServersConfig | None
+    lsp_servers: LSPServersConfig | None
+```
+
+### 4. Loaders
+
+#### `load_marketplace(path: Path) -> MarketplaceManifest`
+
+- If `path` is a file: load it directly as JSON
+- If `path` is a directory: look for `.claude-plugin/marketplace.json` inside it
+- Parse with `json.loads`, validate with `MarketplaceManifest.model_validate(data)`
+- Raise `LoadError` for missing files or JSON parse failures
+- Let `pydantic.ValidationError` bubble up as-is
+
+#### `load_plugin(path: Path) -> Plugin`
+
+- `path` must be a directory (the plugin root)
+- Load `.claude-plugin/plugin.json` if present (optional)
+- Discover agents in `agents/*.md` using `python-frontmatter`
+- Discover commands in `commands/*.md`
+- Discover skills in `skills/*/SKILL.md`
+- Load `hooks/hooks.json` if present
+- Load `.mcp.json` if present
+- Load `.lsp.json` if present
+- Return `Plugin` dataclass
+
+#### `load_agent(path: Path) -> AgentDefinition` / `load_skill(path)` / etc.
+
+Individual loaders for each component — used internally by `load_plugin` but also exposed publicly.
+
+### 5. Public API (`__init__.py`)
+
+```python
+from .loaders.marketplace import load_marketplace
+from .loaders.plugin import load_plugin, load_agent, load_skill, load_command
+from .models import *
+from ._plugin import Plugin
+from .errors import LoadError
+```
+
+### 6. `errors.py`
+
+```python
+class LoadError(Exception):
+    def __init__(self, message: str, path: Path | None = None):
+        self.path = path
+        super().__init__(message)
+```
+
+---
+
+## Tests
+
+Test files mirror the modules. Use `tests/fixtures/` for real example files.
+
+### Fixtures to create
+
+**`tests/fixtures/marketplace/.claude-plugin/marketplace.json`**  
+A full marketplace with one plugin per source type (relative, github, url, npm, pip).
+
+**`tests/fixtures/plugin/.claude-plugin/plugin.json`**  
+A full plugin manifest.
+
+**`tests/fixtures/plugin/agents/reviewer.md`**  
+Agent with `tools` as comma-separated string and a body.
+
+**`tests/fixtures/plugin/skills/code-review/SKILL.md`**  
+Skill with frontmatter.
+
+**`tests/fixtures/plugin/commands/review.md`**  
+Command with `allowed-tools` as a YAML list.
+
+**`tests/fixtures/plugin/hooks/hooks.json`**  
+Hook config with PostToolUse and SessionStart.
+
+**`tests/fixtures/plugin/.mcp.json`**  
+MCP server config.
+
+**`tests/fixtures/plugin/.lsp.json`**  
+LSP server config.
+
+### Test files
+
+- `tests/test_models_marketplace.py` — parse all source types, required field validation
+- `tests/test_models_plugin.py` — parse plugin manifest
+- `tests/test_models_components.py` — agent tools string, command allowed-tools list, skill frontmatter
+- `tests/test_loaders.py` — load_marketplace from file and directory, load_plugin end-to-end
+- `tests/test_errors.py` — LoadError on missing file, ValidationError on bad schema
+
+---
+
+## How to parallelize
+
+These tasks have no dependencies on each other and can be done in parallel:
+
+| Track A | Track B | Track C |
+|---|---|---|
+| `models/plugin.py` | `models/agent.py` | test fixtures (JSON/MD files) |
+| `models/marketplace.py` | `models/skill.py` + `models/command.py` | |
+| `models/hook.py` + `models/mcp.py` + `models/lsp.py` | `errors.py` | |
+
+Then in parallel:
+- `loaders/marketplace.py` (depends on marketplace model)
+- `loaders/plugin.py` + `_plugin.py` (depends on all models)
+
+Finally:
+- `__init__.py` (depends on everything)
+- All test files (can be written alongside their corresponding module)
+
+---
+
+## Validation
+
+```bash
+# run tests
+uv run pytest
+
+# type check
+uvx ty check
+
+# lint
+uv run ruff check src/ tests/
+
+# compare against claude CLI
+claude plugin validate tests/fixtures/marketplace
+claude plugin validate tests/fixtures/plugin
+```
+
+The Claude CLI's `claude plugin validate` command is the ground truth. If our validation rejects something the CLI accepts, we're wrong. If we accept something the CLI rejects, we should add a validator.
+
+---
+
+## Done when
+
+- [ ] `uv run pytest` passes with >90% coverage
+- [ ] `uvx ty check` exits 0
+- [ ] `uv run ruff check src/ tests/` exits 0
+- [ ] `load_marketplace("tests/fixtures/marketplace")` returns a valid `MarketplaceManifest`
+- [ ] `load_plugin("tests/fixtures/plugin")` returns a `Plugin` with agents, skills, etc.
+- [ ] `claude plugin validate tests/fixtures/marketplace` passes
+- [ ] `claude plugin validate tests/fixtures/plugin` passes