Flow는 Google Tasks의 특정 목록을 읽어 macOS 화면 상단에 “지금 할 일”을 작게 띄워주는 네이티브 오버레이 앱입니다.
화면을 계속 바꾸지 않아도 현재 집중할 task가 메뉴바 근처에 남아 있게 만드는 것이 목표입니다. 기본 설정은 Google Tasks의 TODAY TASK 목록을 사용합니다.
Flow는 Google Tasks에서 가져온 task 중 사용자가 선택한 항목과 오늘 해당 task에 집중한 시간을 HH:MM 형식으로 macOS 메뉴바 근처에 작게 표시합니다. 여러 모니터에서는 각 화면에 오버레이를 띄우고, MacBook 노치가 있는 화면에서는 노치 바로 아래 중앙에 배치합니다.
상단 오버레이를 클릭하면 Google Tasks의 미완료 task가 원래 정렬 순서대로 드롭다운에 표시됩니다. 드롭다운에는 Today HH:MM / 24:00 요약도 함께 표시되어 하루 중 기록된 몰입 시간을 바로 확인할 수 있습니다.
앱 시작 시와 드롭다운을 열 때만 Google Tasks를 갱신하므로 백그라운드 polling을 하지 않습니다. OAuth 토큰은 macOS Keychain에 저장하고, 날짜별 시간 기록, 로그인 자동 실행, 오른쪽 클릭 종료, 수동 시간 보정을 지원합니다.
- macOS 13 이상
- Swift 컴파일러가 포함된 Xcode Command Line Tools
- Google 계정
- Google Cloud 프로젝트와 Desktop OAuth client
- Google Tasks API 활성화
Xcode Command Line Tools가 없다면 먼저 설치합니다.
xcode-select --install프로젝트 폴더에서 빌드 스크립트를 실행합니다.
./build_native.sh빌드 결과는 아래 위치에 설치됩니다.
/Applications/Flow.app
실행:
open /Applications/Flow.appFlow는 사용자의 Google Tasks를 읽기 위해 Google OAuth 인증이 필요합니다. 앱은 https://www.googleapis.com/auth/tasks.readonly 범위만 요청하므로 task를 읽을 수만 있고 수정하거나 삭제하지 않습니다.
- Google Cloud Console에서 프로젝트를 만듭니다.
Google Tasks API를 활성화합니다.- OAuth consent screen을 설정합니다.
- 앱이 테스트 상태라면
Test users에 본인 Gmail을 추가합니다. - Credentials에서
OAuth client ID를 만듭니다. - Application type은
Desktop app으로 선택합니다. - 내려받은 JSON 파일 이름을
credentials.json으로 바꿉니다. - 아래 폴더에 넣습니다.
~/Library/Application Support/Flow/credentials.json
처음 실행하면 브라우저가 열리고 Google 로그인을 한 번 요청합니다. 인증이 완료되면 토큰은 Keychain에 저장됩니다.
- Task Left Click: List open
- Task Right Click: Terminate
- List Click: Select Current Task
Pause/Resume: Pause or resume Current Task Time-10m,+10m,+30m: Adjust Today's Current Task TimeReset: Reset Today's Current Task Time
설정 파일:
~/Library/Application Support/Flow/config.json
기본 설정:
{
"fallback_text": "Google Tasks 연결 필요",
"max_visible_tasks": 10,
"task_list": "TODAY TASK"
}설정 항목:
task_list: 읽을 Google Tasks 목록 이름fallback_text: 표시할 task가 없거나 초기 상태일 때 사용할 문구max_visible_tasks: 드롭다운에 한 번에 보이는 최대 task 수. 초과분은 스크롤됩니다.
설정을 수정한 뒤 앱을 재실행하면 반영됩니다.
- 앱 실행 직후 한 번 갱신
- 드롭다운을 열 때 한 번 갱신
- 오류 발생 후 자동 재시도 없음
이 방식은 API 사용량을 줄이고, 사용자가 task를 고르려는 순간에만 최신 목록을 가져오기 위한 선택입니다.
일반 설정과 OAuth 앱 식별 파일은 Application Support에 저장됩니다.
~/Library/Application Support/Flow/config.json
~/Library/Application Support/Flow/credentials.json
~/Library/Application Support/Flow/time_tracking.json
Google OAuth access token과 refresh token은 파일이 아니라 macOS Keychain에 저장됩니다.
Keychain을 쓰는 이유:
- 토큰 파일이 일반 파일로 노출될 위험을 줄입니다.
- macOS가 앱/사용자 권한 기반으로 민감 정보를 보호합니다.
- 앱을 업데이트해도 인증 상태를 유지하기 쉽습니다.
- 인증을 초기화할 때 Keychain 항목만 지우면 됩니다.
자동 실행 켜기:
./install_login_item.sh자동 실행 끄기:
./uninstall_login_item.sh자동 실행은 아래 LaunchAgent를 사용합니다.
~/Library/LaunchAgents/local.flow.plist
Google 계정을 다시 연결하고 싶으면:
./reset_auth.sh
open /Applications/Flow.app이 스크립트는 Keychain에 저장된 Flow OAuth 토큰을 삭제합니다. credentials.json은 삭제하지 않습니다.
Flow.swift # macOS 네이티브 앱 본체
FlowIcon.png # 앱 아이콘 원본 이미지
build_native.sh # Swift 컴파일, icns 생성, /Applications 설치
install_login_item.sh # 로그인 자동 실행 등록
uninstall_login_item.sh # 로그인 자동 실행 제거
reset_auth.sh # Keychain OAuth 토큰 초기화
README.md # 프로젝트 문서
외부 런타임 의존성은 없습니다. Swift/AppKit으로 Google OAuth, Tasks API 호출, 오버레이 UI를 직접 처리합니다.
build_native.sh는 다음 작업을 수행합니다.
Flow.swift를 Swift 컴파일러로 빌드합니다.FlowIcon.png를 여러 해상도의 iconset으로 변환합니다.FlowIcon.icns를 앱 번들에 포함합니다.Info.plist에 bundle id, 앱 이름, 아이콘, 버전을 기록합니다.- 완성된 앱을
/Applications/Flow.app에 설치합니다.
현재 bundle id:
local.flow
credentials.json 없음:
~/Library/Application Support/Flow/credentials.json 위치에 Google OAuth Desktop client JSON을 넣었는지 확인합니다.
Access blocked:
OAuth consent screen이 테스트 상태라면 Test users에 로그인하려는 Gmail을 추가해야 합니다.
목록 이름 확인 필요:
config.json의 task_list 값이 Google Tasks 화면의 목록 이름과 정확히 같은지 확인합니다.
Tasks API 오류:
Google Cloud Console에서 Google Tasks API가 활성화되어 있는지 확인합니다.
앱을 다시 실행해도 새 창이 안 뜸: 중복 실행 방지가 정상 동작한 것입니다. 기존 상단 task를 오른쪽 클릭해서 종료한 뒤 다시 실행합니다.