Skip to content
프로젝트

Licoy/StrokeMouse has 247 GitHub stars and 17 forks. GitHot measured 0 stars in 24 hours and +6 in 7 days. Last checked 2026-11-15 13:56 UTC. Last push 2026-11-12.

이 수치를 측정하는 방법

What you can do

  • Menu bar app: enable/disable gestures, open settings, quit; icon tints by status (normal / paused / needs permission); optional hide menu bar icon (confirm if Dock is also hidden; reopen via Dock or relaunch to open settings)
  • Gesture library: sidebar by Global / per-app (new gestures inherit the selected scope); search / filter / sort; multi-select batch enable, disable, delete; JSON import/export (skip or force-import duplicates); turn off global gestures in chosen apps from General → Apps Without Global Gestures or each app's sidebar entry
  • Mouse drawing: each gesture can independently use the right, middle, or a side button; only buttons referenced by enabled profiles are monitored; optionally add a left-click secondary action—click the left button once while drawing and only that action runs on release
  • Mouse combinations: hold right and scroll up/down, click left, or drag to scroll; at any display’s top/bottom/left/right edge, right-click or scroll to run an action without drawing, or draw a Right-button gesture that starts at the edge. Configure these under Gestures → Add → Mouse Combinations; app scopes and existing actions apply. Details.

측정된 스타 증가

in 24h
0
in 7 days
+6
in 15 days
업데이트 지연
in 1 month
업데이트 지연

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

소개

macOS 鼠标/触控板手势自定义工具。按住该手势的触发键(默认右键,也可中键 / 侧键)绘制轨迹,匹配后执行快捷键、打开应用、窗口操作、媒体键、Shell / AppleScript 等 | A macOS mouse gesture customization tool. Hold down the trigger key to execute shortcuts, open applications, shell/AppleScript, etc. after matching.

생산성

README_ko.md

Original

English · 简体中文 · 繁體中文 · 한국어 · 日本語 · Русский · Français

StrokeMouse

StrokeMouse

License: AGPL-3.0

macOS용 마우스·트랙패드 제스처 사용자 설정 도구입니다. 마우스 버튼을 누른 채 궤적을 그리거나, 수정 키 하나를 누른 채 트랙패드 그리기를 하거나, 실험적인 여러 손가락 터치 제스처를 사용할 수 있습니다. 일치하면 단축키, 앱 열기, 윈도우 조작, 미디어 키, Shell / AppleScript 등을 실행합니다. 전역 또는 특정 App에만 적용할 수 있고, 제스처 구성은 가져오기/내보내기가 가능하며, 로컬에서 실행되고 메뉴 막대에 상주합니다.

StrokeMouse 소개 영상
▶ 1분 42초 소개 영상 보기 (영상 속 텍스트는 중국어 간체)

화면 미리보기

제스처 구성 목록 제스처 테스트
제스처 구성 목록 제스처 테스트
일반 설정 권한 및 엔진 상태
일반 설정 권한 및 엔진 상태
새 제스처 · 궤적 녹음 앱 범위
새 제스처 · 궤적 녹음 앱 범위

기능

  • 메뉴 막대 상주: 제스처 켜기/끄기, 설정 열기, 종료; 아이콘이 상태(정상 / 일시 정지 / 권한 필요)에 따라 색이 바뀜; 메뉴 막대 아이콘 숨기기 가능(Dock도 숨기면 재확인; 숨긴 뒤에는 Dock을 클릭하거나 앱을 다시 열어 설정으로 진입)
  • 제스처 라이브러리: 사이드바를 전역 / 앱별로 구성(새로 만들 때 범위 미리 채움); 검색 / 필터 / 정렬; 다중 선택 일괄 켜기·끄기·삭제; JSON 가져오기/내보내기(중복 항목은 건너뛰거나 강제 가져오기); 일반 → 전역 제스처를 끈 앱 또는 사이드바의 각 App에서 전역 제스처 끄기
  • 마우스 그리기: 제스처마다 오른쪽, 가운데 또는 측면 버튼을 독립적으로 선택; 활성화된 구성이 쓰는 버튼만 감시; 그리는 중 왼쪽 버튼을 한 번 클릭하면 놓은 뒤 실행되는 보조 동작을 추가로 지정 가능
  • 마우스 조합: 오른쪽 버튼을 누른 채 위 / 아래로 스크롤, 왼쪽 클릭 또는 드래그 스크롤을 하고, 각 디스플레이의 위 / 아래 / 왼쪽 / 오른쪽 가장자리에서 오른쪽 클릭하거나 스크롤해도 그리지 않고 동작을 실행합니다. 가장자리에서 시작하는 오른쪽 버튼 제스처도 그릴 수 있습니다. 제스처 → 추가 → 마우스 조합에서 설정하며 기존 동작과 앱 범위를 그대로 씁니다. 자세히(영어)
  • 마우스 버튼 매핑: 측면 또는 가운데 버튼을 한 번 클릭하면 그리지 않아도 동작이 바로 실행됨(예: 뒤로 측면 버튼 → ⌘[), 보조 키 하나를 함께 눌러야 실행되도록 설정 가능(예: ⌘ + 뒤로 측면 버튼에서만); 같은 버튼을 마우스 그리기에도 쓰면 최소 이동 거리 미만은 클릭, 넘으면 그리기로 처리해 중복 실행되지 않음; 전체 / 앱별 범위를 그대로 따르며 매핑이 없는 앱에서는 버튼 기본 동작 유지
  • 트랙패드 그리기: Fn / Control / Option / Shift / Command 중 하나(기본값 Fn)를 누른 채 포인터를 이동해 그림; 지원되는 추가 수정 키를 누르면 이번 인식이 취소됨
  • 실험적 터치 제스처: 내장 트랙패드는 3–5손가락 탭 / 이중 탭 / 클릭 / 이중 클릭 / 네 방향 스와이프와 2–5손가락 핀치 / 펼치기 / 시계·반시계 회전 등 40종을 지원
  • 터치 제스처 마스터 스위치: 이미 구성한 제스처를 삭제하지 않고 터치 제스처 채널만 끌 수 있음; 비공개 백엔드 장애는 터치 채널만 저하시키고 마우스·트랙패드 그리기는 유지
  • 스크롤 향상: 마우스 휠과 트랙패드 / Magic Mouse의 세로·가로를 따로 반전하고, 일반 휠은 부드러운 스크롤(부드럽게 / 표준 / 민감, 또는 속도·시간·가속 사용자 지정)을 켤 수 있음. 제외 목록은 전면 앱 기준이며 설정은 이 Mac에만 남고 백업 동기화에 들어가지 않음. 다른 스크롤 도구와 함께 쓰면 두 번 처리될 수 있고, 정수 줄만 읽는 앱(일부 게임, VM, 원격 데스크톱)은 제외 목록에 넣는 것이 좋음
  • 제스처별 대상: 트리거를 누른 순간의 전면 앱 또는 포인터 아래 앱을 선택; 일반 윈도우가 있으면 해당 윈도우도 고정하고, 앱 범위 판정과 대상 관련 동작은 항상 그 대상을 재사용
  • 자유 경로 인식: 제스처마다 샘플 1–5개를 기록할 수 있으며(3개 권장), 가장 높은 점수의 샘플로 판정; 호 길이를 따라 탄력적으로 정렬해 획의 방향을 우선, 위치를 보조로 비교하므로 곡선·손떨림·끝부분의 작은 갈고리는 허용하고 반대 방향·좌우 반전·중간에서 끊긴 궤적이나 뚜렷하게 덧그린 궤적은 거부; 일반 설정에서 전역 일치 임계값 조정 가능, 트리거를 누르는 동안 실시간 궤적 HUD와 지금 놓으면 실행될 제스처 표시
  • App 범위: 전역, 또는 설치된 앱에서 아이콘으로 추가(검색 / .app 찾아보기)
  • 다양한 동작: 시스템 명령(Mission Control, 응용 프로그램 윈도우, 이전 / 다음 Space; 연결된 시스템 단축키는 사용자 지정 가능), 단축키(Fn/Globe 단독 또는 다른 키와의 조합 지원, ⌘V 다음 Return처럼 순서대로 누를 후속 키 추가 가능), 앱 열기/전환, URL, 미디어 키, 윈도우 동작, Shell / AppleScript(구문 강조; AppleScript는 잠자기, 화면 잠금, 휴지통 비우기 등 프리셋과 사용자 정의)
  • 사용성: 영어, 중국어 간체, 중국어 번체, 한국어, 일본어, 러시아어, 프랑스어 UI(또는 시스템 언어 따르기), 라이트/다크(시스템 / 강제), 로그인 시 시작, Dock / 메뉴 막대 아이콘 숨기기, Sparkle 앱 내 업데이트(실패 시 GitHub Releases로 대체)

시스템 요구 사항

  • macOS 14 Sonoma 이상
  • Xcode 16+(개발 빌드)
  • 마우스 또는 트랙패드로 그리기 제스처를 수행할 수 있음; 직접 멀티터치는 주로 Mac 내장 트랙패드를 대상으로 함
  • 외장 Magic Trackpad는 best-effort 지원이며 기종이나 시스템 버전에 따라 다를 수 있음

설치

Homebrew(권장)

StrokeMouse 프로젝트가 유지하는 Licoy Homebrew Tap으로 설치합니다.

brew install --cask licoy/tap/strokemouse

StrokeMouse는 앱 내 업데이트도 지원합니다. Homebrew로 강제로 확인하고 업그레이드하려면:

brew upgrade --cask --greedy strokemouse

제거 시 설정은 기본적으로 유지됩니다. 설정도 지우려면 --zap을 추가하세요.

brew uninstall --cask strokemouse
brew uninstall --cask --zap strokemouse

공식 다운로드 페이지에서 해당 아키텍처 DMG를 받을 수도 있습니다. 0.0.40 이후 릴리스는 Apple Developer ID로 서명되고 Apple 공증을 받았습니다. 0.0.39 이하에서 업그레이드할 때는 손쉬운 사용을 한 번 다시 허용하세요. 권한 페이지에서 권한 재설정을 클릭한 뒤 StrokeMouse 스위치를 다시 켜면 됩니다.

권한

권한 용도
손쉬운 사용(Accessibility) 전역 마우스 / 수정 키 / 스크롤 이벤트 감시(CGEventTap), 단축키 주입, 윈도우 AX 조작
자동화(Automation) 선택 사항; AppleScript가 다른 앱을 제어할 때 필요

첫 실행 또는 설정 → 권한에서 앱 내 안내 승인을 사용할 수 있습니다. 시스템 설정을 열고 StrokeMouse를 목록에 끌어다 놓아 스위치를 켭니다. 신뢰되지 않으면 엔진은 감시 중인 척하지 않습니다.

실험적 터치 제스처

터치 제스처는 런타임 dlopen / dlsym으로 Apple의 비공개 MultitouchSupport를 로드하며 해당 프레임워크를 정적으로 링크하지 않습니다. macOS 업데이트 후 동작이 멈출 수 있습니다. 프레임워크, 심볼, 장치 누락이나 장치 시작 실패는 터치 채널 장애로 표시되며, 마우스와 트랙패드 그리기는 계속 사용할 수 있고 가짜 대체나 조용한 재시도는 하지 않습니다.

StrokeMouse는 트랙패드 네이티브 제스처를 가로채지 않으므로 시스템 제스처가 바인딩된 동작과 동시에 일어날 수 있습니다. 유일한 예외는 클릭입니다. 클릭 제스처가 설정된 손가락 수로 트랙패드를 누르면 그 클릭은 제스처가 가져가며 앱에는 전달되지 않습니다. 트랙패드를 물리적으로 누른 터치 시퀀스는 탭이나 스와이프로 인식되지 않습니다. 원시 터치 궤적도 저장하거나 기록하지 않습니다. 활성화된 터치 제스처 구성을 처음 저장·활성화·가져올 때 실험 위험 확인이 표시되며, 이후 마스터 스위치로 구성을 삭제하지 않고 터치 제스처를 일시 중지할 수 있습니다.

지원하는 터치 제스처 40종:

종류 손가락 수 변형 개수
탭 셋 / 넷 / 다섯 한 번, 두 번 6
클릭 셋 / 넷 / 다섯 한 번, 두 번 6
스와이프 셋 / 넷 / 다섯 위, 아래, 왼쪽, 오른쪽 12
확대/축소 둘 / 셋 / 넷 / 다섯 핀치, 펼치기 8
회전 둘 / 셋 / 넷 / 다섯 반시계, 시계 8
합계 40

첫 버전은 두 손가락 탭 / 스와이프, 수정 키 조합, 특정 손가락 식별, 연속 반복 동작, 사용자가 조절하는 인식 임계값을 지원하지 않습니다.

빌드 및 실행

의존성

brew install xcodegen

프로젝트 생성 후 열기

./scripts/generate_project.sh
open StrokeMouse.xcodeproj

또는 Xcode에서 바로 Run(Scheme: StrokeMouse).

CLI 빌드(권장)

저장소의 output/StrokeMouse.app에 고정 경로로 출력해 손쉬운 사용 재승인을 줄입니다.
Debug 표시 이름은 StrokeMouse Dev(Bundle ID com.strokemouse.app.dev)이며, 정식판 StrokeMouse와 손쉬운 사용에서 따로 승인할 수 있습니다.

./scripts/build.sh           # Debug → output/StrokeMouse.app (손쉬운 사용: StrokeMouse Dev)
./scripts/build.sh --open    # 빌드 후 자동으로 열기
./scripts/build.sh --release # Release (표시 이름 / Bundle ID가 정식 패키지와 동일)

릴리스 패키징

아키텍처별로 ZIP, TAR.GZ, DMG를 만들고 서명, entitlements, 산출물 무결성을 검증합니다(기본값은 키체인의 Developer ID Application 신원으로 서명하고, 공증 자격 증명이 있으면 공증까지 수행합니다. 다운로드가 Gatekeeper를 통과하고 Sparkle 업데이트 후에도 손쉬운 사용 권한이 유지됩니다).

# 공증: NOTARY_KEYCHAIN_PROFILE=<xcrun notarytool store-credentials로 저장한 프로필 이름> 추가
SPARKLE_PUBLIC_KEY="..." ARCH=arm64 ./scripts/package-app.sh
SPARKLE_PUBLIC_KEY="..." ARCH=x86_64 ./scripts/package-app.sh

릴리스와 CI secrets는 RELEASING.md / certs/README.md를 보세요.

버전 릴리스는 ./bump.sh -v x.y.z [-p]; 같은 버전을 다시 태그하고 푸시하려면 ./bump.sh -v x.y.z --force.

테스트

xcodebuild -scheme StrokeMouse -configuration Debug test

사용 방법

  1. 앱을 실행하면 메뉴 막대에 마우스 아이콘이 나타납니다
  2. 손쉬운 사용 권한을 부여한 뒤 메뉴 막대에서 제스처를 켭니다
  3. 설정 → 제스처에서 기본 제스처를 보거나 새로 만듭니다
  4. 입력 방식을 고릅니다: 마우스 트리거를 누른 채 그리기, 수정 키 하나를 누른 채 트랙패드 그리기, 또는 구성한 터치 제스처 수행
  5. 일치하면 바인딩된 동작이 실행됩니다

짧은 클릭 vs 제스처: 트리거의 누름/뗌은 엔진이 잠시 가로챕니다. 「최소 스트로크 거리」에 도달하기 전에 떼면 일반 클릭으로 재생되어 컨텍스트 메뉴를 쓸 수 있습니다. 그리기가 시작되면 드래그는 시스템 커서와 궤적 HUD를 움직이지만, 전면 앱은 짝이 맞는 누름/뗌을 받지 않으므로 컨텍스트 메뉴가 열리거나 선택되지 않습니다. 트리거로 설정되지 않은 버튼은 항상 통과합니다. 왼쪽 버튼도 통과하지만, 대상 앱에서 사용할 수 있는 제스처에 보조 동작이 있으면 트리거를 누르고 있는 동안의 왼쪽 클릭은 엔진이 가져가고, 놓은 뒤 일치한 제스처의 보조 동작만 실행됩니다(그 제스처에 보조 동작이 없으면 아무것도 실행하지 않으며, 궤적 없이 클릭만 하면 취소됩니다). 대상 앱에 그 버튼의 마우스 버튼 매핑이 있으면 짧은 클릭은 재생되지 않고 매핑 동작을 실행합니다. 오른쪽 버튼을 누른 채 쓰는 마우스 조합은 보조 동작보다 먼저 휠이나 왼쪽 클릭을 가져가며, 실행된 뒤 오른쪽 버튼을 놓아도 클릭을 재생하거나 궤적을 인식하지 않습니다. 대상 앱에서 오른쪽 버튼 드래그 스크롤을 쓸 수 있으면 짧은 클릭 판정 거리는 「최소 스트로크 거리」 대신 고정된 10포인트입니다. 포인터가 10포인트 이상 움직이기 전에 놓으면 오른쪽 클릭이 재생되고, 스크롤이 시작된 뒤에는 놓아도 클릭을 재생하거나 궤적을 인식하지 않습니다.

트랙패드 그리기: 수정 키 감시는 listen-only이며 키보드 이벤트를 삼키지 않습니다. 짧은 경로는 동작을 실행하지 않습니다. 경로는 시스템 포인터를 따르므로 트랙패드나 마우스로 움직일 수 있습니다. StrokeMouse는 수정 키 자체의 현재 앱 효과를 막지 않습니다.

단축키는 먼저 고정된 앱을 활성화하고, 정확한 윈도우가 잡혀 있으면 그 윈도우도 앞으로 가져오므로 포커스나 Space가 바뀔 수 있습니다. Finder 데스크탑처럼 일반 윈도우가 없는 위치에서도 단축키와 앱 가리기는 실행할 수 있습니다. 닫기, 최소화, 확대/축소, 윈도우 최대화, 전체 화면, 가운데 정렬은 정확한 윈도우가 필요합니다. 짧은 클릭은 대상을 활성화하지 않습니다.

선택한 텍스트를 검색하려면 URL 열기 → 선택한 텍스트 사용을 고르고 https://www.baidu.com/s?wd={0} 같은 템플릿을 입력하세요. 제스처를 실행하면 캡처한 윈도우에서 텍스트를 복사해 클립보드에 남기고, 만들어진 URL을 기본 브라우저로 엽니다.

기본 제스처 예(기본값은 오른쪽 버튼; 제스처마다 다른 버튼을 쓸 수 있음):

제스처 동작
↑ Mission Control (⌃↑)
↓ 응용 프로그램 윈도우 (⌃↓)
↓← 윈도우 최소화
↓→ 윈도우 닫기
↑→ Safari 열기
→← 재생 / 일시 정지
↑← GitHub 열기

구성 파일

경로:

~/Library/Application Support/StrokeMouse/gestures.json

일상적으로는 설정 → 제스처에서 여러 항목을 선택한 뒤 JSON 패키지를 내보내거나 가져옵니다. 전체 라이브러리 백업은 위 파일을 복사하거나 직접 편집하세요(구조는 유효해야 함). 설정에서 Finder에서 보기를 할 수 있습니다.

화면 가장자리 오른쪽 버튼 제스처가 포함된 라이브러리, 내보낸 패키지와 백업은 구성 형식 v7을 사용합니다. 그 밖에는 선택한 텍스트 사용이 v6, 윈도우 최대화가 v5, 시스템 명령과 드래그 스크롤이 v4, Fn 단축키가 v3을 요구하며 나머지 구성은 v2입니다. 기존 형식은 계속 읽을 수 있지만, 이전 버전에서는 더 새로운 형식을 읽을 수 없습니다.

시스템 명령은 Mission Control, 응용 프로그램 윈도우, 이전 / 다음 Space를 지원하며 기본값은 macOS 기본값과 같은 ⌃↑ ⌃↓ ⌃← ⌃→입니다. 동작 편집기에서 다른 단축키를 기록하거나 기본 단축키 복원으로 되돌릴 수 있으며, 시스템 설정과 일치해야 합니다. 편집기는 시스템 설정 › 키보드 › 키보드 단축키 › Mission Control을 읽어 해당 단축키가 꺼져 있거나 여기 설정과 다르면 경고하고, 시스템 단축키 사용으로 그 단축키를 가져올 수 있습니다. StrokeMouse는 시스템 설정을 변경하지 않습니다. 기본 단축키를 쓰는데 시스템 설정에서 꺼져 있으면 아무 일 없이 넘어가지 않고 실행 시 오류를 표시합니다. 응용 프로그램 윈도우는 고정된 앱과 윈도우를 먼저 활성화하고, Mission Control과 Space 전환은 고정된 윈도우를 활성화하지 않고 현재 데스크탑에서 동작합니다. 이들은 개별 명령이며 네이티브 네 손가락 제스처 같은 연속 애니메이션이 아닙니다.

단축키 기록을 시작하기 전에 모든 보조 키를 놓은 뒤, 재생할 순서대로 키를 누르세요. Fn은 실제로 눌러야 하며, 시스템 설정에서 Fn으로 바꾼 키(예: Caps Lock)도 쓸 수 있습니다. Caps Lock은 키를 놓은 뒤에도 켜진 상태로 남을 수 있습니다.

기술 스택

  • Swift / SwiftUI (macOS 14+)
  • 가벼운 MVVM + Service
  • 전역 마우스 / 수정 키 이벤트용 CGEventTap
  • 실험적 터치 제스처를 위한 MultitouchSupport의 런타임 dlopen / dlsym 로드(정적 링크 없음)
  • JSON 구성 유지
  • 로그인 시 시작용 LaunchAtLogin-Modern
  • 서명된 앱 내 업데이트용 Sparkle
  • Xcode 프로젝트용 XcodeGen

라이선스 및 면책

이 프로젝트는 GNU Affero General Public License v3.0 (AGPL-3.0)로 라이선스됩니다.

로컬 유틸리티입니다. 전역 이벤트 감시와 스크립트 동작은 강력합니다. 신뢰하는 Shell / AppleScript만 추가하세요. 작성자는 오용이나 실수로 인한 손해에 대해 책임지지 않습니다.