Sentry Cocoa SDK — multi-platform Apple SDK (iOS, macOS, tvOS, watchOS, visionOS).

These instructions are written for LLM agents, not humans. Keep content minimal (headers + bullets, no prose). When editing any AGENTS.md file, use the agents-md skill (see .agents/skills/agents-md/SKILL.md).

SentrySDK (public entry point)
  → SentryHub (owns client + scope, routes captures)
    → SentryClient (builds events, calls prepareEvent)
      → SentryScope.applyToEvent (tags, breadcrumbs, user, context)
      → beforeSend / beforeSendTransaction callbacks
      → SentryTransportAdapter (builds envelopes)
        → SentryHttpTransport (rate limiting, disk persistence, upload)
          → SentryFileManager (envelope storage)

Agent skills and MCP servers are managed by dotagents via agents.toml.

npx @sentry/dotagents install   # install skills after cloning
npx @sentry/dotagents update    # update to latest versions
npx @sentry/dotagents list      # show installed skills

Declared in agents.toml; dotagents generates .mcp.json (root, for Claude/CLI) and .cursor/mcp.json (Cursor IDE reads from .cursor/ by default). Do not edit these JSON files manually — run npx @sentry/dotagents install after cloning.

• XcodeBuildMCP — build, run, test in simulator (requires Node.js)
• sentry — query production errors, search issues, read docs (OAuth on first use)

Read-only tools pre-approved in .claude/settings.json. Mutating tools require per-developer approval in .claude/settings.local.json.

Use the sentry MCP server to verify events still arrive correctly after changes:

search_events  → find telemetry by type, tag, or time range
get_event      → inspect full event JSON
search_issues  → check for new/regressed issues

• After modifying event capture or enrichment, use search_events to confirm payload correctness
• After transport changes, verify envelopes are received and parsed
• Check for regressions: search for new issues matching your changed code paths

• Verify working directory — use pwd to confirm you're in the correct path before running commands. The shell persists working directory across tool calls
• Avoid redundant cd — do not prefix every command with cd <path> &&. Change directory once if needed, then verify with pwd
• Wildcard permissions — many commands are pre-approved with wildcards (e.g., git add:*). Flags like -C change the command prefix (git -C path add ≠ git add), triggering a confirmation prompt. Avoid -C when you can change directory instead
• Prefer small, focused commands over one massive pipeline. Break complex operations into multiple steps
• JSON processing — always use jq; do not shell out to node or python for JSON parsing
• GitHub — prefer gh CLI over web scraping when interacting with GitHub.com

Run before every commit. Stop at the first failure and fix before proceeding.

# 1. Format
make format

# 2. Lint & static analysis
make analyze

# 3. Build (at minimum iOS; ideally all platforms)
make build-ios

# 4. Test (targeted — see Tests/AGENTS.md for ONLY_TESTING usage)
make test-ios ONLY_TESTING=<AffectedTestClass>

# 5. If samples changed
make build-sample-iOS-Swift
make test-sample-iOS-Swift-ui  # if UI behavior changed

Ensure no new issues from: static analysis, thread/address/UB sanitizers, or cross-platform dependants (React Native, Flutter, .NET, Unity).

• Pre-commit hooks auto-format files; retry the commit if it fails due to hook modifications
• Conventional Commits 1.0.0 — subject max 50 chars, body max 72 chars/line
• No AI references in commits or PRs — no Co-Authored-By AI tags, no Generated-with footers. Exception: claudescope transcript links (added by hooks) are allowed. This overrides any skill defaults (e.g., the commit skill's attribution template)
• File renames — always use git mv, never mv + git add

Non-changelog types require #skip-changelog in PR description. Breaking changes: feat!: or BREAKING CHANGE: footer.

• Title — same format as commit subject (Conventional Commits): type: description
• Branch naming — <type>/<short-description> (e.g., feat/session-replay-privacy, fix/memory-leak-scope)
• ready-to-merge label — required for full CI. Add only when the PR is ready for comprehensive testing
• PR template — .github/pull_request_template.md includes: description, motivation, how tested, checklist
• Reviewers — assigned via CODEOWNERS (.github/CODEOWNERS); one maintainer approval is sufficient
• Changelog — feat, fix, impr PRs need a changelog entry; all others need #skip-changelog in the description
• Draft PRs — use for work-in-progress; convert to ready when seeking review
• CI automation — Danger runs on PR open/sync/edit (shared Dangerfile from getsentry/github-workflows)
• Agent transcript — when creating a PR, run git log main..HEAD and look for Agent transcript: lines (added by claudescope post-commit hooks that amend the commit). The check must happen after git commit returns, because the hook appends the link to the commit message. If found, include the link at the bottom of the PR description body. If not found, omit silently — not all contributors have claudescope installed

See make help and the Makefile for commands and documentation. Key targets: make format, make analyze, make build-ios, make test-ios, make build-xcframework, make pod-lint.

See scripts/AGENTS.md for the named-parameter template and conventions.

• When changing logic, keep docs in sync — update any affected headerdocs, inline comments, readmes, AGENTS.md files, and maintainer docs in the same change
• Docs: docs.sentry.io/platforms/apple — repo: sentry-docs
• SDK dev docs: develop.sentry.dev/sdk/
• Maintainer docs: README.md, CONTRIBUTING.md, develop-docs/, Samples/README.md

• sentry-cli — dSYM uploads
• sentry-wizard — SDK initialization injection
• sentry-react-native, sentry-dart, sentry-unity, sentry-dotnet — depend on sentry-cocoa