Adrafinil: macOS용 AI 코딩 에이전트를 위한 조건부 수면 방지 도구

Adrafinil: macOS용 AI 코딩 에이전트를 위한 조건부 수면 방지 도구

Adrafinil은 Mac이 활성 AI 코딩 에이전트 세션 동안에만 깨어 있도록 설계된 macOS 유틸리티로, 작업이 수행되지 않을 때는 시스템이 정상적으로 수면 모드로 전환될 수 있도록 합니다. 항상 켜져 있는 깨우기 유틸리티와 달리, Adrafinil은 에이전트가 작업 중인 동안에만 클램쉘(clamshell, 덮개 닫힘) 수면을 포함한 수면을 동적으로 차단하며, 세션이 종료되면 자동으로 차단 해제합니다.

에이전트 인식 수면 관리

Adrafinil은 하나 이상의 AI 코딩 에이전트 세션이 활성 어설션(assertion)을 보유하고 있을 때만 시스템이 수면 상태로 들어가는 것을 방지합니다. 세션이 활성 상태가 아닐 때는 Mac의 기본 수면 동작이 그대로 유지됩니다. 이 방식은 실제 시스템 활동과 관계없이 일반적으로 지속적인 깨어 있는 상태를 유지하는 caffeinate나 Amphetamine과 같은 도구와는 다릅니다.

지원되는 에이전트 및 통합

Adrafinil은 9개의 AI 에이전트 훅 시스템과 통합되는 원클릭 설치 프로그램을 제공합니다:

  • Claude Code
  • Codex
  • Cursor
  • Gemini CLI
  • Aider
  • Hermes
  • OpenCode
  • Cline
  • Pi

통합은 에이전트가 작업을 시작할 때 세션 키를 acquire하고, 에이전트가 유휴 상태가 되면 release하도록 호출하는 번들된 CLI를 통해 처리됩니다. 이러한 CLI 호출은 에이전트의 워크플로우를 방해하지 않도록 50ms 미만의 왕복 시간(round-trip)으로 최적화되어 있습니다.

기술 아키텍처 및 보안

클램쉘 수면을 무시하려면 루트 권한이 필요하기 때문에, Adrafinil은 권한이 부여된 공격 표면을 최소화하기 위해 계층형 아키텍처를 사용합니다.

권한 계층

  1. Adrafinil.app: UI, 설정 및 덮개 열림 요약 정보를 처리하는 사용자용 메뉴 바 애플리케이션입니다.
  2. AdrafinilDaemon: 사용자로 실행되는 LaunchAgent입니다. 이 구성 요소는 참조 횟수가 계산되는 어설션 레지스트리를 관리하고, 열 및 덮개 상태를 모니터링하며, CLI 소켓을 처리합니다.
  3. AdrafinilHelper: 루트 레벨의 SMAppService LaunchDaemon입니다. 이는 수면 차단 API에 접근할 수 있는 유일한 구성 요소로, 간단한 setSleepBlocked(Bool) 메서드를 노출합니다. 명령을 실행하기 전에 호출자의 코드 서명 요구 사항을 확인합니다.

수면 차단 메커니즘

Adrafinil은 유휴 수면(idle sleep)을 위해 표준 IOPMAssertion을 사용합니다. 클램쉘 수면을 처리하기 위해 pmset disablesleep 1을 사용합니다. 개발자는 caffeinate에서 사용하는 공개 IOPM 어설션이 덮개가 닫힌 Mac을 깨어 있게 유지하는 데 불충분하다는 점을 언급했습니다. 상태 누출을 방지하기 위해, 헬퍼는 현재 상태를 다시 적용하기 전에 재시작 시 disablesleep을 0으로 재설정합니다.

안전 및 모니터링 기능

하드웨어 손상을 방지하고 시스템 안정성을 보장하기 위해, Adrafinil은 여러 자동화된 안전 장치를 포함합니다:

  • Thermal Cutout (열 차단): 덮개가 닫힌 상태에서 CPU 또는 표면 온도가 미리 정의된 임계값을 초과하면, Mac이 밀폐된 공간(예: 노트북 가방)에서 과열되는 것을 방지하기 위해 모든 어설션을 강제로 해제합니다.
  • Idle Release (유휴 해제): 소유 프로세스가 종료되거나 지정된 시간 동안 CPU 유휴 상태를 유지하면 어설션이 자동으로 해제됩니다.
  • Lid-State Feedback (덮개 상태 피드백): 덮개를 닫을 때 어설션이 유지되고 있음을 확인하기 위해 차임 벨 소리가 울립니다. 덮개를 다시 열면, 사용자는 실행된 작업의 요약, 도달한 최고 온도, 열 차단이 발생했는지 여에 대한 요약을 볼 수 있습니다.

요구 사항 및 설치

Adrafinil은 macOS Tahoe 26.4 (또는 잠재적으로 이전 26.x 버전)가 필요하며, **Xcode 26+**와 Swift 6 strict concurrency를 사용하여 빌드되었습니다. 설치에는 SMAppService를 통해 권한이 부여된 헬퍼를 등록하기 위한 관리자 권한이 필요합니다.

커뮤니티 관점

이 도구는 AI 에이전트 사용자들을 위한 특정 문제를 해결하지만, 일부 커뮤니티 구성원들은 더 간단한 대안을 제하거나 우려 사항을 제기했습니다:

  • 기존 도구: 일부 사용자는 Amphetamine과 같은 앱이 특정 앱이 종료될 때 종료될 수 있거나, pmset을 사용하는 간단한 셸 스크립트가 유사한 결과를 얻을 수 있다고 지적했습니다.
  • 하드웨어 위험: 사용자는 노트북이 백팩 안에서 효과적으로 냉각되지 않는다는 점을 상란시켜, 열 차단 기능의의 중요성을 강조했습니다.
  • 수동적 대안: 한 사용자는 수면 방지를 위해 외부 모니터를 시뮬레이션하기 위해 더미 HDMI/USB-C 플러그를를 사용하라고 제안했지만, 결과가 일관성 없다고 보고했습니다.

"15년 전에도 노트북에서 음악을 듣기 위해 이렇게 했었습니다... 한 가지 주의할 점은, 노트북이 백팩 안에서 냉각되지 않아 결국 과열되어 종료될 것입니다."

CLI 명령 요약

명령 목적
acquire <key> 에이전트 턴이 시작될 때 수면을 차단함
release <key> 에이전트가 유휴 상태가 되면 수면 차단을 해제함
hold --for <time> 백그라운드 작업(예: 배포)을 위한 시간 제한 깨어 있는 상태
mcp stdio 상에서 Model Context Protocol 통신을 활성화함
status 현재 어설션 상태를 확인함

Sources