anthropics / anthropics/claude-code

macOS: versioned install paths invalidate TCC folder permissions on every auto-update (and mid-session for running sessions)

Open
#88,576 1 comment 0 reactions 0 assignees View on GitHub
area:packaging bug has repro platform:macos
Dominant language
Python
Stars
145k
Forks
23.1k
PR merge metrics
PR metrics pending

Description

## Environment
- Claude Code 2.1.228 → 2.1.238 (native installer, auto-update on)
- macOS Tahoe 26.2, binary at `~/.local/share/claude/versions/`

## Problem
Claude Code installs each auto-update as a new binary at a versioned path (`~/.local/share/claude/versions/2.1.238`, etc.). macOS TCC identifies unsigned/CLI clients by executable path, so **every update is a brand-new TCC client**: the first time the new version touches `~/Documents` (or Downloads, etc.), macOS prompts again, and the user's previous grant — attached to the now-obsolete versioned path — is silently useless.

My `TCC.db` shows the result: 8 separate `kTCCServiceSystemPolicyDocumentsFolder` allow rows for 8 Claude versions in 9 days (2.1.228, .231, .232, .233, .234, .235, .237, .238). From the user's perspective, macOS "keeps forgetting" a permission they've granted repeatedly — it took a TCC.db dive to see why.

## Worse: running sessions lose file access mid-session
A long-running session stays pinned to its old versioned binary while the auto-updater installs newer versions alongside it. In my case a session running 2.1.235 had full Documents access for ~2 hours, then every read/write under `~/Documents` started returning EPERM mid-session (Read tool and child Bash processes alike) shortly after 2.1.238 was installed — with the 2.1.235 allow row still present and `auth_value=2` in TCC.db. Nothing recovers it except restarting onto the new binary and re-granting.

## Impact
- Users on daily auto-updates re-approve Documents/Downloads access roughly per release, or conclude their Mac is broken.
- Long-lived sessions (overnight agents, `--resume` workflows) can silently lose access to files they were mid-way through editing.

## Suggested fix
Give the CLI a stable TCC identity: a signed binary with a consistent designated requirement (so grants survive updates), or a stable launcher path that execs the versioned binary while remaining the TCC-responsible executable. Failing that, the updater could at least warn that folder permissions will re-prompt after update.

Happy to provide the TCC.db excerpts or reproduce on request.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the native installer's versioned binaries under ~/.local/share/claude/versions/ and reproduce an auto-update while accessing ~/Documents. Compare TCC behavior before and after the update, including a session that remains running across the update. Done means folder permissions persist across updates and long-running sessions do not lose access mid-session.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos
Domain
cli, operating-systems, release
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.