К основному содержанию
скилл CX Codex

macos-permissions — скилл для Claude Code: диагностика прав TCC

Скилл macos-permissions для Claude Code находит причины сбоев TCC, сетевых алертов и зависших окон Keychain. Помогает при бесконечных диалогах и падении фоновых LaunchAgent.

MIT 152 установок ★ 1 540 обновлён 2026-11-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add daymade/claude-code-skills --skill macos-permissions -a claude-code
Открыть на GitHub

Что делает macos-permissions

Разбирает блокировки Full Disk Access, доступ к камере, микрофону, экрану, автоматизации и Keychain. Инструмент не меняет настройки вслепую: сначала агент вычисляет ответственный процесс через /usr/bin/log. Имя в стандартном окне macOS часто вводит в заблуждение, указывая лишь на исполняемый файл вроде python3.11 или node.

Сверяет записи в TCC.db через SQLite, когда у терминала есть доступ, и помогает справиться с Permission denied из-за SIP. Различает поломки прав после обновлений через uv, смены бинарников и проблемы с одновременным доступом контроллера и цели в Automation. Без предварительно выданного терминалу Full Disk Access прочитать системную базу напрямую не получится.

Какие задачи решает

  • диагностика прав TCC
  • найти ответственный процесс в цепочке запуска
  • устранить повторные запросы Full Disk Access в фоновых LaunchAgent
  • восстановить доступы скриптов после обновления uv или Node.js

Примеры запросов агенту

  • Проверь, почему скрипт на Python не получает доступ к диску
  • Найди в логах TCC ответственный процесс для фонового демона
  • Разберись с зависшим запросом связки ключей Keychain

Как установить macos-permissions

1Через Skills CLI (Vercel)

npx skills add daymade/claude-code-skills --skill macos-permissions -a claude-code

2Вручную: положить файлы

~/.claude/skills/macos-permissions/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/macos-permissions/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о macos-permissions

Как установить macos-permissions в Claude Code?

Выполните команду npx skills add daymade/claude-code-skills --skill macos-permissions -a claude-code.

Что делает macos-permissions?

Скилл расследует отказы прав TCC, сетевых экранов и Keychain в macOS, определяя истинный ответственный процесс по системным логам вместо имени из диалогового окна.

Что нужно для чтения базы TCC.db?

Терминалу требуется разрешение Full Disk Access, иначе системная защита SIP заблокирует прямой запрос к базе данных с ошибкой Permission denied.

Исходный текст

SKILL.md · MIT
---
name: macos-permissions
description: >-
  Diagnoses TCC denials, Local Network access and stuck Keychain dialogs: Full Disk Access,
  Screen Recording, Microphone, Camera, Accessibility, Automation. Use for repeated prompts,
  background-only LaunchAgent/uv failures, broken grants or FDA automation
  (权限弹窗 / 授权了没用 / 完全磁盘访问 / 本地网络权限). Checks requester/grants first.
  Not launchd design (macos-watchdog) or app permission UX (developing-ios-apps).
---

# macOS Permission Dialogs

## Observe and classify the reported problem first

The executing agent preserves the user's symptom: a dialog that cannot be clicked,
typed into or dismissed needs an interaction diagnosis even when it contains a
password field. Do not replace that report with instructions to enter a password.

Read the actual dialog before choosing a subsystem or naming its owner. Use the
host's permitted observation tools; when whole-screen observation is authorized
and permitted, use `capture-screen`'s full-screen route without raising windows.
A refusal to control one protected app neither identifies the unseen dialog nor
proves every observation method is unavailable. Respect the refusal's scope;
never switch tools to bypass a host restriction or GUI lock.

| Observed dialog or failure | Route |
|---|---|
| Confirmed Keychain item access failure, a `login` keychain password, or a blocked Keychain window | Read [Keychain recovery](references/keychain-dialog-recovery.md) |
| Local Network alert, or a local connection/discovery failure specific to one app or background agent | Read [Local Network diagnosis](references/local-network.md); an error string or another process's success does not establish the cause |
| Privacy resource request or a protected operation failing without a visible dialog | Continue with the TCC procedure below |
| Script, Git hook, or application-specific confirmation | Inspect that request through its owning task/tool; do not change TCC or Keychain settings |
| Content or owner still unknown | Keep it unknown; obtain only the missing permitted observation or ask the user for the visible text |

These are operator decisions, not an automatic dialog classifier.

## TCC diagnosis

macOS gates per-app, per-resource access through **TCC** (Transparency, Consent, Control).
TCC records permission decisions in its databases and controls what a process can do.
Several common traps need different fixes:

| Trap | Symptom | Fix lives in |
|---|---|---|
| **Wrong subject granted** | Dialog names `python3.11`/`2.1.232`/`node`; you granted that but it still prompts | [The attribution trap](#the-attribution-trap) below |
| **Grant doesn't survive** | Worked, then a binary/uv/CLI update → prompt returns | `references/uv-fda-trap.md` |
| **Silent denial** | Feature "unavailable", no dialog, grant looks ON | `references/tcc-mechanics.md` § auth_value |
| **Can't read TCC.db** | `Permission denied` reading the DB; need FDA to diagnose FDA | `references/tcc-mechanics.md` § SIP |

## The attribution trap

### Reproduce the reported denial first

The executing agent first inspects the original protected operation through its task-owned handle and any retained result. Reuse current evidence for the same resource, requester and execution context. Keep a still-running request within its existing deadline; do not launch a replacement while its terminal state is unknown. When current evidence is missing or stale, issue one bounded read through the actual failing requester and context before choosing a permission repair. A file listing, another terminal, SSH access or a foreground run cannot substitute for that operation. Record the path/resource, requester, context and result; this is a diagnostic step, not a mechanical permission classifier.

If that read now succeeds, report **currently accessible; earlier cause unknown** and stop permission changes unless a specific required read still fails. Do not call the cause repaired without evidence of the cause and its correction, or add Full Disk Access, change ACLs, reconnect shared mounts or restart a shared host merely to clear a historical error. If it still fails, follow the attribution checks below; `Operation not permitted` alone does not establish TCC as the cause.

**The name in the dialog does not prove who to grant.** macOS attributes a request to the *responsible*
process in the process tree, but displays the name of the *accessing* executable — and for an
unsigned binary with no bundle (uv-managed python, per-version CLI, node helpers) that display
name is just the last path component, which changes with every version. Granting the displayed
name is the mistake that costs the most rounds.

**Before touching System Settings, inspect the request and any readable grant state:**

```bash
# 1. Who is actually requesting — the responsible process in the attribution chain
/usr/bin/log show --last 30m --predicate 'subsystem == "com.apple.TCC"' --info --debug \
  | grep -E 'from Sub:|responsible=|accessing=' | tail -20

# 2. Grant candidates, if this terminal can read the system database
sudo -n sqlite3 '/Library/Application Support/com.apple.TCC/TCC.db' \
  "select service, client, auth_value from access where service='kTCCServiceSystemPolicyAllFiles' and client like '%<name>%';"
```

Use `from Sub:` to identify a candidate requester, then verify its exact path and a real
protected read before choosing what to authorize. An unreadable TCC.db leaves grant state
unknown; its FDA bootstrap is in `references/tcc-mechanics.md`.
When interpreting preflight logs or an allowed grant row, first load
[Correlate preflight and grant evidence](references/tcc-mechanics.md#correlate-preflight-and-grant-evidence)
before choosing a permission repair.

## Decision tree

| The situation is… | Go to |
|---|---|
| User asks to complete Full Disk Access repair automatically, or a background job needs protected files | `references/automated-full-disk-access.md` (reuse a verified existing grant first; otherwise drive System Settings and read back) |
| Dialog reappears after clicking Allow; or a LaunchAgent / `uv run` job prompts every few minutes | `references/uv-fda-trap.md` (identify the requester; follow the automated repair route before adding a grant) |
| Need the full kTCCService catalog, schema, auth_value/auth_reason semantics, `tccutil` | `references/tcc-mechanics.md` |
| Reading TCC.db gives "Permission denied" | `references/tcc-mechanics.md` § SIP and the FDA bootstrap |
| A granted permission silently stopped working after an update, rebuild or signer change | [Signed-app replacement](references/tcc-mechanics.md#signed-app-replacement-with-an-enabled-but-ineffective-grant); distinguish a stale code requirement from a changed requester before repairing |
| Grant won't stick for Automation / Apple Events | `references/tcc-mechanics.md` — BOTH controller AND target need the grant |

## Core rules (each from a real incident)

- **Dialog name ≠ responsible process.** `from Sub:` in the TCC log is the requester; the title
  is the accessing binary's basename and it drifts with versions. Grant by the real path.
  (2026-09-19: a `uv` FDA dialog showed `python3.11`; authorizing python, changing session type,
  and pinning the version all failed because the requester was `~/.local/bin/uv`.)
- **Match the requester and its code identity.** Path-based clients can lose a grant when
  their executable path changes. Bundle-based clients can also fail at the same path and
  bundle ID when the replacement no longer satisfies the recorded code requirement.
  An enabled switch alone does not establish access; use the signed-app replacement route.
- **"0 hits / can't catch it" is an instrument problem, not a conclusion.** `fs_usage` can emit 0
  bytes on some machines; short-lived processes fall between log time windows; an empty grep file
  looks identical to a real zero. To pin *which operation* triggers a prompt, use in-process
  `sys.addaudithook` to log `open` events aligned to the tccd timestamp — not `fs_usage`.
- **SIP protects the system TCC.db read-only.** You cannot `INSERT`/`UPDATE` a grant from the
  command line — authorization must go through the GUI. `auth_value` is readable, writable is not.
- **After granting, verify the request before considering a restart.** Follow
  [the request lifecycle below](#after-a-grant-or-reset); restart requirements depend on
  the permission and application, not on the presence of an Allow click.

## After a grant or reset

The executing agent checks the original request through its task-owned process/tool handle
and repeats the named protected operation in the same requester and execution context.
These are operator checks; this Skill does not automatically manage process lifecycles.

1. If the original request is still running, keep it alive and wait within its existing
   deadline for its actual result. An Automation/AppleEvent request can complete after Allow
   without restarting its requester. A dismissed dialog or an enabled switch is not success.
2. If a wait expires, inspect the original request's terminal result before retrying. A tool
   wait ending does not itself prove the underlying request ended; keep its state unknown
   when no result is available. A late Allow cannot make an expired request succeed. Once
   the original request has ended, issue one new bounded, read-only query when needed to
   verify access; check for any completed side effect before repeating the business action.
3. If access still fails, check the exact requester, permission and application-specific
   relaunch requirement. Restart only when that requirement or the observed failure makes
   it necessary, and only a task-owned process or an explicitly authorized target whose work
   is preserved. Before terminating another session's process or restarting a shared service,
   verify explicit authorization for that exact operation and preservation of its in-flight
   work. Without both, keep that repair pending while continuing independent diagnosis.
4. After any required relaunch, repeat the protected operation in its real context. Stop
   permission changes when it succeeds; a grant record alone does not prove the job works.

## Scope

This skill owns **permission diagnosis and repair**. It does not own: building an app's
permission-onboarding UX (app-development work, out of scope here), launchd job design (`macos-watchdog`),
or disk cleanup (`macos-cleaner`) — those link here when they hit a TCC wall.

© daymade · MIT · daymade/claude-code-skills

Похожие скиллы

Все скиллы по теме «Безопасность» →
macos-security-bypass yaklang Скилл macos-security-bypass для Claude Code, Codex, Cursor и других AI-редакторов кода с методиками обхода защит macOS. CX Codex +1 3 900установок argent-settings-permissions software-mansion Скилл argent-settings-permissions выдаёт, отзывает и сбрасывает системные разрешения в симуляторе iOS и на Android без открытия экрана настроек. Настраивает доступы перед автотестами до старта приложения. CX Codex +1 25 300установок macos-accessibility martinholovsky Даёт агенту экспертизу по macOS Accessibility API (AXUIElement) для автоматизации настольных приложений. CX Codex +1 314установок macos-forensics W4L33Dx Скилл macos-forensics для Claude Code анализирует артефакты операционной системы при расследовании инцидентов. Разбирает единые логи, события FSEvents, базы TCC и автозагрузку launchd. CX Codex +1 ★ 73звёзд репо agent-desktop-macos vercel-labs Скилл agent-desktop-macos для Claude Code настраивает правила автоматизации графического интерфейса macOS через CLI agent-desktop. Управляет разрешениями TCC и координирует работу с системными меню. CX Codex +1 1 100установок permiso-accessibility-permissions reason-machines Скилл permiso-accessibility-permissions для агентов, который подсказывает, как встроить в macOS-приложение панель с просьбой выдать доступ к универсальному доступу. CX Codex +1 393установок

Из того же набора102

Весь набор →
lark-cli-router Скилл lark-cli-router маршрутизирует задачи для Feishu, Lark и Doubao через встроенные руководства утилиты lark-cli. Помогает безопасно вызывать API документов, встреч, задач и чатов. CX Codex +1 210установок excalidraw-use Скилл excalidraw-use раскладывает готовые картинки по сцене Excalidraw ровной сеткой, снимает слайды Vite-деки в отдельные изображения и читает .excalidraw на битые картинки. CX Codex +1 187установок meme-creator Скилл meme-creator для Claude Code накладывает логотипы, аватары и стикеры на движущиеся объекты в видео и сохраняет результат в MP4 и GIF. Создаёт мемы и реакции из видеоклипов. CX Codex +1 174установок agent-web-search-setup Скилл agent-web-search-setup для Claude Code и других платформ диагностирует и чинит веб-поиск на моделях через прокси и реселлеров. CX Codex +1 162установок tech-selection Скилл tech-selection для Claude Code помогает выбрать или пересмотреть библиотеку, фреймворк, хранилище или архитектуру. Запускается перед тем, как зафиксировать техническое решение. CX Codex +1 151установок report-with-html Скилл report-with-html для Claude Code создаёт автономные визуальные HTML-отчёты, интерактивные дашборды и верстаки для ревью. Запускается по прямому запросу на веб-отчёт или визуализацию данных. CX Codex +1 143установок docs-router Скилл docs-router для Claude Code маршрутизирует задачи по работе с файлами между инструментами пакета Daymade. Определяет нужный обработчик по форматам исходника и результата. CX Codex +1 138установок financial-router Скилл financial-router для Claude Code перенаправляет финансовые задачи к специализированным инструкциям набора. Маршрутизирует работу с рынками США, акциями Китая или авторизацией Gangtise. CX Codex +1 136установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой