Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / repository-plugin-structure

Repository plugin structure

Overview

This repository is the public Claude Code repository and a routing point into two extension systems: marketplace plugins that are now developed elsewhere, and built-in mods whose source still lives here. README.md presents Claude Code as a terminal/IDE/GitHub coding agent, points users to the official docs for install and data usage, embeds demo.gif, and routes plugin readers to plugins/README.md. CHANGELOG.md is the release-note source, while feed.xml publishes the same release stream as Atom entries linked back to the changelog and GitHub release tags. LICENSE.md and SECURITY.md are short policy files: commercial terms govern use, and security reports go through Anthropic's HackerOne form.

Plugin marketplace metadata is centralized in .claude-plugin/marketplace.json. That file defines the claude-code-plugins marketplace, owned by Anthropic, with each listed plugin fetched from https://github.com/anthropics/claude-plugins-official.git via source: "git-subdir", a subpath under plugins/<name>, and ref: "main". The local plugins/README.md explains that new plugin source belongs in claude-plugins-official, not this repository, and documents the expected plugin layout (.claude-plugin/plugin.json, optional commands/, agents/, skills/, hooks/, .mcp.json, and README.md). The marketplace also carries a renames map, currently retiring claude-opus-4-5-migration and mapping ralph-wiggum to ralph-loop.

Mods are the built-in plugin-like extension sources under mods/, with this doc owning only the repository-level entry points and shared declarations. mods/README.md is the routing table for the five built-in mods: sec-default, diff, telemetry, agents-md, and privacy. It explains that each mod is a complete plugin with .claude-plugin/plugin.json, hooks/hooks.json, TypeScript hooks, and tests, and that mod-specific behavior should be read in that mod's own folder rather than here. mods/tsconfig.json gives the common compiler setup for mod hooks and tests: ES2023, bundler module resolution, strict/noUncheckedIndexedAccess, no emit, JSX compiled through h/Fragment, and inclusion of mods/types, every mod's types/…/*.d.ts, hooks, and tests.

The shared plugin API declaration is mods/…/claude-code.d.ts. Its header is the important repository-level contract: it is generated from engine sources, is expected to match the declarations embedded in Claude Code, and should not be hand-edited here. It declares the claude-code module used by hooks (Register, On, EngineInterface, event types, UI types, etc.), claude-code/testing for claude plugin test, and claude-code/shader. It also documents runtime constraints for hook modules: ES modules only, no require, no dynamic import(), no Node or DOM environment, plugin-local imports by declaration, and UI elements resolved from $.ui.resolve(e) instead of globals.

Local development/editor scaffolding is minimal but intentional. .devcontainer/devcontainer.json builds .devcontainer/Dockerfile, runs as node, mounts the workspace and persistent Claude config/history volumes, installs the Claude Code VS Code extension plus ESLint/Prettier/GitLens, and runs .devcontainer/init-firewall.sh at startup. The Dockerfile installs Node 20, git/GitHub CLI/jq/network tools/editors/zsh, git-delta, and a global @anthropic-ai/claude-code package. The firewall script resets iptables/ipset rules, preserves Docker DNS, allows DNS/SSH/localhost/host-network traffic, fetches GitHub CIDRs, resolves a short allowlist (registry.npmjs.org, api.anthropic.com, sentry.io, statsig.com, and VS Code marketplace/update hosts), defaults INPUT/FORWARD/OUTPUT to DROP, and verifies that example.com is blocked while api.github.com is reachable. .vscode/extensions.json recommends ESLint, Prettier, Remote Containers, and GitLens outside the devcontainer. .gitattributes enforces LF endings for all text and shell scripts; .gitignore only ignores .DS_Store at the repository root.

CLAUDE.md is repository guidance for coding agents, focused on GitHub Actions hardening. It does not describe plugin internals, but reviewers changing workflows should keep its constraints in view: Claude-running jobs should use the firewall runner, keep .github/egress-firewall.yaml in enforcing mode, and pass --permission-mode auto with the required model behavior.

Coverage and routing

  • README.md, demo.gif: public repository introduction and top-level route to plugin docs.
  • CHANGELOG.md, feed.xml: release notes and Atom feed; use these to understand shipped user-visible changes, including plugin/mod changes, before drilling into code.
  • LICENSE.md, SECURITY.md: legal and security-reporting policy.
  • CLAUDE.md: agent/workflow safety guidance for this repository.
  • .gitattributes, .gitignore, .vscode/**, .devcontainer/**: repository/editor/container scaffolding that affects local development but not mod behavior.
  • .claude-plugin/**: marketplace metadata for externally hosted official plugins.
  • plugins/**: plugin overview only; actual official plugin source is in anthropics/claude-plugins-official.
  • mods/README.md: index for built-in mods. Route from there into mod-specific docs for mods/sec-default/**, mods/diff/**, mods/telemetry/**, mods/agents-md/**, or mods/privacy/**.
  • mods/tsconfig.json, mods/types/**: shared TypeScript declarations and compiler contract for all built-in mods.

Coupling

  • If .claude-plugin/marketplace.json adds, removes, renames, or repoints a plugin, also update plugins/README.md when the public story changes. The README says official plugins are developed in claude-plugins-official, while the marketplace is what Claude Code actually installs from this repository.
  • If a mod adds a $ noun or depends on another mod's noun, update that mod's types/index.d.ts and ensure mods/tsconfig.json still includes */…/*.d.ts; mods/README.md documents that cross-mod noun contracts are shared through those declaration files, not copied between mods.
  • If mods/…/claude-code.d.ts is stale, regenerate it rather than editing it. mods/README.md names bun scripts/generate-plugin-dts.ts as the path from engine declarations to this generated copy, and mod hook/test typechecking depends on this file matching the embedded engine API.
  • If .devcontainer/init-firewall.sh changes its allowlist or startup behavior, verify .devcontainer/devcontainer.json still grants NET_ADMIN/NET_RAW and runs it as postStartCommand; without those capabilities the container may start but fail to enforce the intended network policy.

Risks

  • mods/…/claude-code.d.ts is a generated API snapshot. If it is manually changed or drifts from the engine declarations, mod hooks and tests can compile against an API that installed Claude Code does not provide.
  • .claude-plugin/marketplace.json installs from remote git-subdir paths on main. If a plugin path, name, or renames entry is wrong, /plugin installs can fail or users can be routed from an old plugin name to the wrong replacement.
  • .devcontainer/init-firewall.sh uses shell text processing around iptables-save, jq, dig, grep, awk, and sed to build firewall rules. If GitHub metadata or DNS output changes shape, the devcontainer startup can fail or block required hosts before the workspace is usable.