diff --git a/chapters/ai-tools/anthropic-repos.qmd b/chapters/ai-tools/anthropic-repos.qmd new file mode 100644 index 00000000..f9f47dbe --- /dev/null +++ b/chapters/ai-tools/anthropic-repos.qmd @@ -0,0 +1,320 @@ +Anthropic publishes its code under the +[`anthropics`](https://github.com/anthropics) GitHub organization. +The organization held 108 repositories when surveyed +(measured 2026-09-09). +Claude Code itself is not open source, +but its public repository is still useful, +and so are several others. +This section inventories the repositories that matter to us, +says what the two headline repositories actually contain, +and ends with a verdict on each. + +All counts below come from the GitHub API on the survey date +(measured 2026-09-09); +stars and push dates drift daily, +and the license column reports what the API detected. +`none` means the API found no license; +for `claude-code` and `claude-agent-sdk-typescript` that is because +`LICENSE.md` is a proprietary notice rather than a recognized open-source license, +marked `none (proprietary)`, +and for the other `none` rows there is no license file at all. +`not detected` means a license file exists that the API could not classify +(it reports `NOASSERTION`). +A single row can also hide a split: +`skills` has no root license file, so the API reports none, +while its README says four of its skills are source-available. + +#### Which repositories matter to us + +Forks and archived repositories together are 38 of the 108 +(measured 2026-09-09): +forks of infrastructure projects that Anthropic contributes patches to +(`tokio`, `rayon`, `argo-cd`, `httpcore`, `orjson`, `beam`), +and archived companions to research papers +(`hh-rlhf`, `toy-models-of-superposition`, `sleeper-agents-paper`). +Neither group concerns a lab that consumes Claude as a product. +The rest sorts into six groups. + +| Repository | Purpose | Language | Stars | Last push | License | Verdict | +|---|---|---|---|---|---|---| +| `claude-code` | Issue tracker, changelog, and bundled plugins for the Claude Code CLI | Python (plugin scripts) | 144.5k | 2026-09-08 | none (proprietary) | Track issues and read the plugins | +| `claude-code-action` | GitHub Action that runs Claude Code on PRs and issues | TypeScript | 8.8k | 2026-09-08 | MIT | Already in use; read its `examples/` | +| `claude-code-base-action` | Read-only mirror of `base-action/` from the repository above | TypeScript | 974 | 2026-09-08 | MIT | Reference only; do not pin to it | +| `claude-code-security-review` | Security-focused PR review action | Python | 6.2k | 2026-02-11 | MIT | Low priority; superseded by a review prompt | +| `claude-agent-sdk-python` | Python SDK wrapping the Claude Code agent loop | Python | 8.1k | 2026-09-08 | MIT | Useful for scripted agents | +| `claude-agent-sdk-typescript` | Issue tracker and changelog for the TypeScript agent SDK | Shell | 1.7k | 2026-09-08 | none (proprietary) | Track issues only | +| `anthropic-sdk-python` | Raw Messages API client | Python | 3.9k | 2026-09-04 | MIT | Useful for direct API calls | +| `sandbox-runtime` | OS-level sandbox (`srt`) for processes, MCP servers, and agents | TypeScript | 5.2k | 2026-09-07 | Apache-2.0 | Trial on Linux and macOS; alpha on Windows | +| `skills` | Reference Agent Skills plus the `spec/` for the skill format | Python | 175.4k | 2026-09-03 | none | Read the spec; borrow document skills | +| `claude-plugins-official` | Anthropic-curated plugin marketplace | Python | 36.1k | 2026-09-09 | Apache-2.0 | Install from it; see @sec-ai-useful-plugins | +| `claude-plugins-community` | Read-only mirror of the community marketplace | Python | 3.7k | 2026-08-25 | Apache-2.0 | Browse before writing our own | +| `knowledge-work-plugins` | Role-specific plugins built for Claude Cowork | Python | 23.9k | 2026-09-09 | Apache-2.0 | Templates for a lab-role plugin | +| `claude-cookbooks` | Notebook recipes for the Claude API | Jupyter Notebook | 52.6k | 2026-09-03 | MIT | Reference when scripting the API | +| `courses` | Five API and prompting courses | Jupyter Notebook | 22.8k | 2026-08-28 | not detected | Introductory material | +| `prompt-eng-interactive-tutorial` | Nine-chapter prompting tutorial | Jupyter Notebook | 38.1k | 2026-08-28 | none | Introductory material; dated model names | +| `claude-quickstarts` | Starter apps you can deploy (support agent, computer use) | TypeScript | 17.6k | 2026-09-04 | MIT | Skim only | +| `devcontainer-features` | Dev Container feature that installs the CLI | Shell | 302 | 2025-12-16 | MIT | Useful for a GitHub Codespaces setup | +| `claude-code-monitoring-guide` | Telemetry and cost-tracking guide | Markdown | 369 | 2025-07-29 | none | Read once if we meter usage | +| `claude-ai-mcp` | Issue tracker for MCP inside claude.ai | Markdown | 467 | 2026-06-08 | not detected | Search before filing an MCP bug | + +The six groups, and what each is for: + +- **Product trackers.** + `claude-code`, `claude-agent-sdk-typescript`, and `claude-ai-mcp` + exist mainly so users can file issues against a closed product. +- **Automation.** + `claude-code-action`, its mirror, and `claude-code-security-review` + run Claude inside GitHub Actions. +- **Programmatic access.** + The `anthropic-sdk-*` clients (Python, TypeScript, Go, Java, Ruby, C#, PHP) + speak the raw API; + `claude-agent-sdk-python` wraps the whole Claude Code agent loop + and bundles the CLI, + and the TypeScript package does the same from npm, + though its repository here is only a tracker. +- **Extensions.** + `skills`, the two plugin marketplaces, and `knowledge-work-plugins` + hold the skills and plugins the harness loads. +- **Infrastructure.** + `sandbox-runtime`, `devcontainer-features`, and `claude-code-monitoring-guide` + are about where the CLI runs and what it costs. +- **Learning material.** + `claude-cookbooks`, `courses`, `prompt-eng-interactive-tutorial`, + and `claude-quickstarts` teach the API rather than the CLI. + +Two repositories one might look for are not in the organization. +There is no `mcp` repository, +because the Model Context Protocol lives under its own +`modelcontextprotocol` organization, +and the former `dxt` repository (Desktop Extensions) +now redirects to `modelcontextprotocol/mcpb`, +the renamed MCP Bundles format +(measured 2026-09-09). + +#### What the public `claude-code` repository actually contains + +The repository named after Claude Code, +second in the table only to `skills` by stars, +does not contain Claude Code. +The tree at `main` has 333 paths and no `src/` directory +(measured 2026-09-09) [@anthropics_claude_code_repo]. +`LICENSE.md` is a one-line proprietary notice +pointing at Anthropic's commercial terms, +which is why the API reports no license. +The CLI itself ships as a compiled npm package +(and, since the README marked npm installation deprecated, +as a native installer, a Homebrew cask, and a `winget` package; +read 2026-09-09) [@anthropics_claude_code_repo], +and this repository is the public face of that closed product. + +The repository holds five things the lab can use: + +- **`CHANGELOG.md`** is the only authoritative per-release changelog. + It is the file to read when a behavior changes between versions, + and its entries are detailed enough to diagnose regressions + (the entry for 2.1.266, for example, + names the gateway environment variable, `CLAUDE_CODE_USE_GATEWAY`, + that 2.1.265 had started honoring on its own, + and says no configuration change is needed; + read 2026-09-09) [@anthropics_claude_code_changelog]. +- **`plugins/`** holds thirteen first-party plugins + and a `.claude-plugin/marketplace.json` that publishes them + as the `claude-code-plugins` marketplace [@anthropics_claude_code_plugins_readme]. + Several map directly onto lab workflows: + `code-review` (five parallel review agents with confidence scoring), + `pr-review-toolkit` (six specialist review agents, + including a `silent-failure-hunter`), + `commit-commands`, + `hookify` (generates hooks from observed misbehavior), + `ralph-wiggum` (a `Stop`-hook loop that keeps re-running one task), + and `security-guidance` (a `PreToolUse` hook watching nine patterns). + `plugin-dev` is the toolkit for writing more. +- **`examples/`** holds the reference configurations + that the documentation describes in prose: + `settings/` (strict, lax, and bash-sandbox profiles), + `hooks/` (a Bash command validation hook), + `mdm/` (managed settings for macOS and Windows fleets), + and `gateway/` (AWS and GCP gateway setups). +- **`.devcontainer/`** is the container Anthropic uses + for its own sandboxed sessions, + including `init-firewall.sh`, + the allowlist firewall that + @sec-ai-firewall discusses. +- **`.github/workflows/`** is a live example of running the action + against a very large issue tracker: + `claude.yml` (the `@claude` agent), + `claude-issue-triage.yml`, + `claude-dedupe-issues.yml`, + and `auto-close-duplicates.yml`, + with the TypeScript behind them in `scripts/`. + The repository had 12,563 open issues (measured 2026-09-09), + which is why that automation exists. + +So the honest description is +"issue tracker plus plugins plus example configs". +The harness internals are described from the outside in +@sec-ai-harness-construction; +nothing in this repository lets you read them. + +#### `claude-code-action`: modes and what ships with it + +`claude-code-action` is genuinely open source (MIT), +and the whole action is readable: +`src/` holds the entry points, the GitHub client, +an in-process MCP server for file operations, +and the two execution modes; +`test/` has a test file per concern +(comment sanitizing, branch validation, permissions, +public-comment redaction, SSH signing) +[@anthropics_claude_code_action_repo]. + +@sec-ai-claude-code-action-review already explains +that review is a prompt, not a separate action. +The general form of that observation is the mode detector +in `src/modes/detector.ts`, +documented in `docs/experimental.md` +[@anthropics_claude_code_action_experimental]: + +1. If the workflow supplies a `prompt` input, + the action runs in **agent mode**: + it executes the prompt directly on whatever event fired, + which is how scheduled maintenance, + issue triage, and one-shot review work. +2. If there is no `prompt` but the event carries an `@claude` mention, + an assignment, or the trigger label, + it runs in **tag mode**: + it posts a tracking comment with progress checkboxes + and runs an open-ended session that can push code. +3. If neither, it does nothing. + +The `track_progress` input forces tag-mode tracking comments +onto `pull_request` and `issues` events +that would otherwise run in agent mode. +Everything else about behavior is set through `claude_args`, +which passes flags straight to the CLI +(`--max-turns`, `--system-prompt`, and so on), +and through `plugins`, +which installs named marketplace plugins before the run. + +Three other things in the repository are easy to miss: + +- **`examples/`** has eleven copy-paste workflows (measured 2026-09-09): + the three review variants, + plus `claude.yml` (the general `@claude` mention workflow), + `ci-failure-auto-fix.yml`, `test-failure-analysis.yml`, + `issue-deduplication.yml`, `issue-triage.yml`, + `manual-code-analysis.yml`, `agent-approval-check.yml`, + and `claude-wif.yml`, + the workload-identity-federation variant + that avoids storing a long-lived API key. +- **`agent-approval-check/`** is a second, smaller action + that gates a workflow on whether the actor is a recognized agent identity, + with an example identities file. +- **Authentication inputs** cover a direct API key, + a Claude Code OAuth token, + federation (`anthropic_federation_rule_id` plus organization, + workspace, and service-account IDs), + and OIDC to Bedrock, Vertex AI, or Microsoft Foundry. + +The `allowed_non_write_users` input carries its own warning +in `action.yml`: +letting users without write access trigger the action +exposes the run to prompt injection, +and the secret scrubbing it performs is best-effort. +`claude-code-security-review` says the same of itself +in its README and recommends requiring approval for fork PRs +[@anthropics_claude_code_security_review]. +Both are the upstream statement of the caution +in @sec-ai-benefits-hazards. + +#### The extension and SDK repositories, briefly + +`skills` is the reference implementation of the Agent Skills format +that @sec-ai-agent-skills describes. +Its `spec/` directory is the format definition, +`template/` is a starting skill, +and `skills/` holds the examples. +The README states the licensing split plainly: +most skills are Apache-2.0, +while the `docx`, `pdf`, `pptx`, and `xlsx` skills +that power Claude's own document features +are source-available rather than open source +[@anthropics_skills_repo]. +Read a license header before copying one. + +`claude-plugins-official` is the marketplace behind +`/plugin install @claude-plugins-official`, +split into Anthropic-maintained `plugins/` +and partner-submitted `external_plugins/` [@anthropics_claude_plugins_official]. +Its README states a rule that applies to any marketplace we publish: +a plugin's `name` is an immutable slug, +since renaming it breaks every existing install, +and a `renames` map exists for the unavoidable case. +`claude-plugins-community` is a nightly, read-only mirror +of the community submissions that passed security scanning +[@anthropics_claude_plugins_community], +and `knowledge-work-plugins` holds eleven role-specific bundles +built for Claude Cowork (@sec-ai-collaborative-workspaces) +that also load in Claude Code [@anthropics_knowledge_work_plugins]. + +Of the two agent SDKs, +only the Python one is open source. +`claude-agent-sdk-python` bundles the CLI inside the wheel +and exposes `query()` and `ClaudeAgentOptions` +for driving a full agent session from a script +[@anthropics_claude_agent_sdk_python]. +`claude-agent-sdk-typescript` has the same shape as `claude-code`: +a proprietary `LICENSE.md`, a changelog, examples, +and an issue tracker for the npm package +[@anthropics_claude_agent_sdk_typescript]. +The lower-level `anthropic-sdk-python` is the raw API client +(MIT) for anyone who wants the model without the agent loop +[@anthropics_anthropic_sdk_python]. + +`sandbox-runtime` (`srt`) is the sandbox Claude Code uses internally, +released as a beta research preview. +It wraps `sandbox-exec` on macOS and `bubblewrap` on Linux +with a proxy-based network allowlist, +and the headline use case in its README is wrapping a local MCP server +so it can read only the directories you name +[@anthropics_sandbox_runtime]. +Windows support is marked alpha, +through a bundled `srt-win.exe` helper +that runs the process under a dedicated local user account +(measured 2026-09-09), +so Windows users in the lab should treat it as experimental. + +#### Useful to us? + +Yes, selectively, and less for code than for reference. + +- **Adopt now.** + `claude-code-action` is already how our repositories run `@claude` + and review (@sec-ai-claude-code-action-review); + the `examples/` directory and `claude-wif.yml` + are the upgrade path when we move off static API keys. + `claude-plugins-official` is the safe default source for plugins. +- **Read, then borrow.** + The `plugins/` directory in `claude-code` + duplicates several things our own instruction repository does by hand --- + a multi-agent review command, a silent-failure hunter, + a hook generator --- + and a `hookify`-style rule + is a lighter way to encode a "never do X again" correction + than a hand-written hook. + `skills/spec/` is the authority when a skill fails to load. +- **Track, do not depend on.** + `claude-code` and `claude-agent-sdk-typescript` are trackers. + Search their issues before filing; + read `CHANGELOG.md` before blaming a regression on your config. + Pin workflows to `claude-code-action@v1`, never to the base-action mirror. +- **Trial on Linux and macOS.** + `sandbox-runtime` could replace part of the + firewall configuration in @sec-ai-firewall + for macOS and Linux users; + its Windows path is alpha. +- **Skip.** + `claude-code-security-review` has not been pushed since February 2026 + and its job is now a review prompt; + the quickstarts and courses are for API programming, + which is not the lab's main use of Claude. diff --git a/chapters/coding-agents.qmd b/chapters/coding-agents.qmd index 668466d1..e6961909 100644 --- a/chapters/coding-agents.qmd +++ b/chapters/coding-agents.qmd @@ -89,7 +89,7 @@ to [help you code](https://en.wikipedia.org/wiki/AI-assisted_software_developmen {{< include ai-tools/agents-best-practices.qmd >}} -# Firewall and Network Configuration +# Firewall and Network Configuration {#sec-ai-firewall} {{< include ai-tools/agents-firewall-config.qmd >}} @@ -153,6 +153,10 @@ to [help you code](https://en.wikipedia.org/wiki/AI-assisted_software_developmen {{< include ai-tools/claude-code-config-install.qmd >}} +# Anthropic's Public Repositories {#sec-ai-anthropic-repos} + +{{< include ai-tools/anthropic-repos.qmd >}} + # Claude Code Cloud Environments {#sec-ai-claude-cloud-env} {{< include ai-tools/claude-code-cloud-environments.qmd >}} diff --git a/inst/WORDLIST b/inst/WORDLIST index 3a3e13f2..5711b086 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -49,6 +49,7 @@ Cline Cmd CodeCompanion CodeNomad +Codespaces Codestral Codestral's Codex @@ -132,6 +133,7 @@ JFrog JSON JetBrains Jules +Jupyter KV Kanban Karpathy diff --git a/references.bib b/references.bib index 58b3b9f4..b63ab654 100644 --- a/references.bib +++ b/references.bib @@ -727,3 +727,129 @@ @misc{ai_config_readme url = {https://github.com/Morrison-Lab/ai-config}, note = {Accessed 2026-09-09} } + +@misc{anthropics_claude_code_changelog, + title = {anthropics/claude-code: CHANGELOG.md}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Documentation}, + url = {https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md}, + note = {Entry for 2.1.266. Accessed 2026-09-09} +} + +@misc{anthropics_claude_code_repo, + title = {anthropics/claude-code}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-code}, + note = {Proprietary license notice in LICENSE.md. Accessed 2026-09-09} +} + +@misc{anthropics_claude_code_plugins_readme, + title = {Claude Code Plugins}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Documentation}, + url = {https://github.com/anthropics/claude-code/blob/main/plugins/README.md}, + note = {Accessed 2026-09-09} +} + +@misc{anthropics_claude_code_action_repo, + title = {anthropics/claude-code-action}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-code-action}, + note = {MIT License. Accessed 2026-09-09} +} + +@misc{anthropics_claude_code_action_experimental, + title = {Experimental Features}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Documentation}, + url = {https://github.com/anthropics/claude-code-action/blob/main/docs/experimental.md}, + note = {Accessed 2026-09-09} +} + +@misc{anthropics_claude_code_security_review, + title = {anthropics/claude-code-security-review}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-code-security-review}, + note = {MIT License. Accessed 2026-09-09} +} + +@misc{anthropics_skills_repo, + title = {anthropics/skills}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/skills}, + note = {Mixed licensing; see the repository README. Accessed 2026-09-09} +} + +@misc{anthropics_claude_plugins_official, + title = {anthropics/claude-plugins-official}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-plugins-official}, + note = {Apache License 2.0. Accessed 2026-09-09} +} + +@misc{anthropics_claude_plugins_community, + title = {anthropics/claude-plugins-community}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-plugins-community}, + note = {Apache License 2.0. Accessed 2026-09-09} +} + +@misc{anthropics_knowledge_work_plugins, + title = {anthropics/knowledge-work-plugins}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/knowledge-work-plugins}, + note = {Apache License 2.0. Accessed 2026-09-09} +} + +@misc{anthropics_claude_agent_sdk_python, + title = {anthropics/claude-agent-sdk-python}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-agent-sdk-python}, + note = {MIT License. Accessed 2026-09-09} +} + +@misc{anthropics_claude_agent_sdk_typescript, + title = {anthropics/claude-agent-sdk-typescript}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/claude-agent-sdk-typescript}, + note = {Proprietary license notice in LICENSE.md. Accessed 2026-09-09} +} + +@misc{anthropics_anthropic_sdk_python, + title = {anthropics/anthropic-sdk-python}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/anthropic-sdk-python}, + note = {MIT License. Accessed 2026-09-09} +} + +@misc{anthropics_sandbox_runtime, + title = {anthropics/sandbox-runtime}, + author = {{Anthropic}}, + year = {2026}, + howpublished = {Software}, + url = {https://github.com/anthropics/sandbox-runtime}, + note = {Apache License 2.0. Accessed 2026-09-09} +}