BackgroundComputerUse — macOS background computer-use API

BackgroundComputerUse

macOS에서 네이티브 앱·브라우저·멀티 윈도우 작업을 백그라운드로 제어하는 local computer-use API.

Overview

actuallyepic/background-computer-use는 Swift 기반의 macOS 컴퓨터 사용 런타임이다. 루프백 HTTP API와 직접 Swift API를 함께 제공하며, Accessibility / Screen Recording / window-event 계층을 이용해 앱 상태를 읽고 클릭·스크롤·타이핑·키 입력·윈도우 이동을 수행한다.

핵심 차별점은 사용자 포인터를 점거하지 않는다는 점이다. 이전 세대 CUA가 화면을 장악하는 방식이라면, 이 프로젝트는 백그라운드-first 실행과 멀티 윈도우 데스크톱 워크플로우를 강조한다.

What it does

• 루프백 HTTP API로 로컬 macOS agent runtime 제공
• GET /v1/bootstrap로 권한/초기화 상태와 런타임 URL 확인
• GET /v1/routes로 self-documenting API 카탈로그 제공
• list_apps, list_windows, get_window_state로 상태 읽기
• click, scroll, type_text, press_key, set_value, drag, resize, set_window_frame 등 액션 수행
• Window state 재읽기와 screenshot 기반 검증을 권장
• Swift Package로 직접 임베딩 가능

Why it matters

• macOS CUA를 단순 브라우저 자동화가 아니라 네이티브 앱 제어 레이어로 확장한다
• Claude Code / Codex / 기타 AI 클라이언트와 결합하기 좋은 구조다
• “화면을 빼앗지 않는” background-first UX에 가깝다
• OpenAI Codex Computer Use plugin과의 기능적 parity를 명시한다

Runtime notes

• ./script/start.sh로 빌드, 서명, 설치, 런타임 부트스트랩까지 처리
• 앱은 ~/Applications/BackgroundComputerUse.app에 설치
• runtime manifest는 $TMPDIR/background-computer-use/runtime-manifest.json에 저장
• 접근성 / 화면 기록 권한이 필요하므로 서명된 앱 번들로 실행해야 함

Repo facts

• GitHub: https://github.com/actuallyepic/background-computer-use
• Stars: 212
• Forks: 23
• Open issues: 0
• Default branch: main
• Language: Swift
• License: MIT

Related Notes

• 2026-04-27-macos-cua-repos-comparison — macOS CUA 오픈소스 비교
• 2026-03-25-claude-code-computer-use — Claude Code computer use 기능
• 2026-04-28-trycua-cua-ai-agent-os-sandbox — OS 레벨 샌드박스형 CUA
• moc-ai-agents — AI Agents MOC

Source

• GitHub: https://github.com/actuallyepic/background-computer-use
• Raw README cache: raw/articles/github-actuallyepic-background-computer-use-readme.md