Skip to content

feat(#27489): add cloud-synced CLAUDE.md client#27687

Open
samuelarogbonlo wants to merge 1 commit intoanthropics:mainfrom
samuelarogbonlo:sam/cloud-synced
Open

feat(#27489): add cloud-synced CLAUDE.md client#27687
samuelarogbonlo wants to merge 1 commit intoanthropics:mainfrom
samuelarogbonlo:sam/cloud-synced

Conversation

@samuelarogbonlo
Copy link

Client-side reference implementation for cloud-synced global instructions (CLAUDE.md) tied to the user's Anthropic account. This enables persisting user-level instructions across sessions and devices (CLI, VS Code, mobile, web).

This closes #27489. The features here include:

  • Bidirectional sync runtime — session-start sync with review-on-change gate (cloud changes require explicit user confirmation before injection)
  • Stale-while-revalidate provider — <1ms cache hits for 95% of sessions, zero latency for non-cloud users
  • 7 CLI commandsclaude instructions sync enable/disable/status/push/pull/history/restore
  • Security hardened — HMAC-signed sync state, prompt-safety framing, OAuth scope isolation, 256KB response limit with fail-closed error handling, 0o600 file permissions, atomic writes

Key design decisions

  • Cloud config sits below local in precedence (Layer 5 of 7) — machine-specific overrides always win
  • Cloud changes never auto-applyreview-required gate blocks injection until user confirms
  • Non-cloud users see zero behavior change — triple-gate check with zero I/O
  • Three-way merge for conflicts, not last-write-wins

Files

Module File Purpose
Types src/config/cloud-config-types.ts Branded types, discriminated unions, interfaces
Cache src/config/cloud-config-cache.ts Atomic writes, HMAC signing, 0o600 permissions
Fetcher src/config/cloud-config-fetcher.ts HTTP client, ETag conditionals, size limits
Provider src/config/cloud-config-provider.ts Stale-while-revalidate, scope enforcement
Sync src/config/cloud-config-sync.ts Session sync decision tree (8 result variants)
API src/config/cloud-config-api.ts Full typed API contract with Result<T>
Imports src/config/cloud-import-resolver.ts Circular detection, max depth 8
CLI src/commands/instructions-sync.ts 7 subcommands via Commander.js
Conflict src/commands/conflict-resolver.ts Keep/Take/Merge/Diff interactive UI
Format src/commands/cli-format.ts LCS diff, ANSI formatting, NO_COLOR support

What's NOT included (requires Anthropic infra)

  • Server-side API endpoints and storage (DynamoDB + S3)
  • Integration into existing prompt assembly pipeline
  • Cache warming on claude auth login
  • Enterprise managed-settings controls
  • Environment variable handling (CLAUDE_CODE_SIMPLE, CLAUDE_CODE_NO_CLOUD)

@samuelarogbonlo
Copy link
Author

@joncutrer FYI

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Global CLAUDE.md instructions should persist across Claude Code for Cloud sessions (desktop + mobile)

1 participant