GeulGuard · 글가드

Keep every Korean character.

macOS 베타와 일부 앱에서 한글 조합 중 글자가 사라지는 문제를 우회하는 Swift 기반 두벌식 입력 소스입니다.

왜 글자가 사라지나

한글은 키 하나가 곧 완성 문자로 들어가지 않습니다. macOS 입력기가 marked text(조합 중 문자열)를 앱에 보여 주다가 음절이 끝날 때 확정합니다. 일부 앱과 베타 OS에서는 포커스 이동, 방향키, Delete, 입력 소스 전환 때 이 문자열을 확정하지 않고 취소하거나 다음 조합으로 덮습니다.

글가드는 한글 조합만 담당합니다. 영어는 macOS 기본 ABC 입력 소스로 입력합니다.

1. 한글은 글가드 두벌식, 영어는 ABC를 사용하고 macOS가 입력 소스 전환을 담당합니다.
2. 기본 입력 모드에서는 방향키, Tab, Return, ESC, 단축키 등 조합을 끝내는 이벤트 전에 표시 중인 한글을 먼저 동기적으로 확정합니다.

설치

최신 GitHub Release에서 GeulGuard.pkg를 내려받아 실행합니다. 설치 프로그램은 서명·공증된 Universal Binary를 /Library/Input Methods에 설치하므로 관리자 암호가 필요합니다.

설치 뒤 로그아웃/로그인하고:

1. 시스템 설정 → 키보드 → 텍스트 입력 → 편집
2. +를 눌러 한국어 아래의 글가드 두벌식과 영어 아래의 ABC 추가
3. 메뉴 막대 입력 메뉴에서 글가드 두벌식 선택

메뉴 막대 입력 메뉴 또는 macOS의 입력 소스 전환 단축키로 ABC ↔ 글가드 두벌식을 전환합니다. 단축키는 시스템 설정 → 키보드 → 키보드 단축키 → 입력 소스에서 확인·변경할 수 있습니다. 글가드는 Shift+Space를 한/영 전환으로 가로채지 않습니다. ESC는 조합 중인 한글만 확정하며 입력 소스를 바꾸지 않습니다.

업데이트

업데이트가 설정된 배포본에서는 메뉴 막대의 글가드 아이콘 → 업데이트 확인…으로 새 버전을 확인합니다. 앱이 시작될 때 백그라운드에서 한 번 자동 확인하며 새 버전이 있을 때만 안내합니다. 설정의 앱 시작 시 업데이트 확인에서 끌 수 있습니다. 설치는 사용자 확인과 관리자 인증을 거칩니다.

설치 전에 입력 중인 글자를 확정하고 ABC로 전환하세요. 조합 중인 글자가 남거나 현재 소스가 ABC가 아니면 업데이트를 위한 종료를 막습니다. 설치 후 글가드를 다시 선택하고, 새 버전이 반영되지 않으면 작업 저장 후 로그아웃·로그인하세요. 업데이터가 없는 기존 버전은 업데이트 기능을 포함한 PKG를 한 번 수동 설치해야 합니다. 피드·공개키를 지정하지 않은 개발 빌드에서는 업데이트 메뉴와 설정이 비활성화됩니다. 배포 준비와 검증 절차는 업데이트 배포 문서를 참고하세요.

권장 사용법: ABC + 글가드 두벌식 + Karabiner

영어는 ABC, 한글은 글가드 두벌식, Caps Lock 전환은 Karabiner-Elements가 담당하는 구성을 권장합니다. Karabiner는 선택 사항이며, 없어도 시스템 단축키로 글가드를 사용할 수 있습니다.

1. macOS 입력 소스 설정

• 시스템 설정 → 키보드 → 텍스트 입력 → 편집에서 ABC와 글가드 두벌식을 추가합니다. 두 소스만 사용하면 전환 대상을 예측하기 쉽습니다. 다른 입력 소스가 필요하면 유지해도 되지만, ‘이전 입력 소스’가 항상 ABC/글가드 두벌식인 것은 아닙니다.
• 키보드 → 키보드 단축키 → 입력 소스에서 이전 입력 소스 선택을 Control+Space로 설정합니다. 아래 Karabiner 규칙은 이 단축키를 보냅니다.
• Caps Lock의 ‘길게 눌러 대문자 고정’ 동작은 기본 입력 전환 옵션에 함께 포함됩니다. 대문자 고정 없이 전환만 하려면 아래 규칙을 사용합니다.

글가드는 TICapsLockLanguageSwitchCapable로 macOS 기본 Caps Lock 전환 지원을 선언합니다. Karabiner 없이 기본 전환을 쓰려면 텍스트 입력 → 편집 → 모든 입력 소스에서 Caps Lock 전환 옵션을 켭니다. 0.6.2 이전 버전에는 이 선언이 없습니다. 업데이트 후 옵션이 보이지 않으면 작업을 저장하고 로그아웃·로그인하세요. macOS 27.0에서 ABC와 글가드만 등록한 상태의 옵션 표시·활성화는 설치 후 사용자 스크린샷으로 확인했습니다. Karabiner를 끈 상태의 양방향 전환은 아직 실기 검증하지 않았습니다.

2. Caps Lock을 입력 전환 전용으로 사용

1. Karabiner-Elements 공식 사이트에서 설치하고 앱이 안내하는 macOS 권한·드라이버 설정을 완료합니다.
2. Karabiner → Complex Modifications → Add your own rule을 엽니다.
3. Caps Lock 규칙 JSON 전체를 붙여 넣고 저장합니다.
4. 규칙이 활성화되어 있고 Devices에서 사용하는 키보드가 활성화되어 있는지 확인합니다.

규칙은 Caps Lock을 Control+Space 한 번으로 바꿉니다. repeat: false로 길게 눌렀을 때의 반복 전환을 막으며, 다른 수정키와 함께 눌러도 입력 전환을 보냅니다. 기존 Caps Lock 규칙과 충돌하면 어느 규칙을 유지할지 먼저 정하세요. Karabiner가 실행 중이고 해당 키보드를 처리할 때 적용되며, 로그인 전 화면에는 이 설정이 그대로 적용된다고 가정하지 마세요. 대문자는 Shift로 입력합니다.

에이전트에게 설치 맡기기

다음 요청을 저장소에 접근할 수 있는 코딩 에이전트에게 전달하세요.

이 저장소의 AGENTS.md와 docs/agent-setup.md를 읽고 글가드를 권장 구성으로 설치해 줘. 영어 ABC와 한글 글가드 두벌식을 함께 쓰고, Caps Lock은 카라비너로 입력 전환만 하게 해 줘. 기존 설정을 백업하고, 가능한 설치·설정을 진행한 뒤 직접 해야 하는 인증·권한 승인·로그아웃 단계와 실제 검증 결과를 알려 줘.

설치 절차·설정 보존·복구·검증 기준은 에이전트 설치 가이드에 있습니다. 관리자 인증과 macOS 권한 승인은 사용자 조작이 필요할 수 있습니다.

설정 근거: Apple 입력 소스 안내, Karabiner 반복 억제, 수정키 처리.

현재 범위

• 현재는 표준 두벌식 및 복합 모음/겹받침 지원
• 조합 단위 Backspace
• macOS 기본 ABC 입력 소스와 함께 사용
• 커서 이동·포커스 변경 전 강제 확정
• Electron/Chromium 호환 marked text 표시

한자 변환, 글가드 자체 Caps Lock 전환, 앱별 모드 기억은 현재 포함하지 않습니다. Caps Lock 전환은 위 Karabiner 설정으로 구성할 수 있습니다. 다른 자판 배열과 조합 옵션의 진행 항목은 ROADMAP.md에서 관리합니다.

메뉴 막대의 글가드 아이콘에서 설정…을 열면 연속 자음의 쌍자음 조합을 켜거나 끌 수 있습니다. 켜면 ㄱㄱ → ㄲ, 끄면 ㄱㄱ → ㄱㄱ으로 입력됩니다. Shift로 직접 입력하는 쌍자음과 겹받침 조합에는 영향을 주지 않습니다.

[실험실] 텔레그램 Enter 전송 보정은 기본으로 꺼져 있습니다. 켜면 텔레그램(ru.keepcoder.Telegram)에서 조합 중인 글자를 marked text 대신 일반 문서 텍스트로 입력하고, 다음 자모마다 그 글자를 교체합니다. 텔레그램은 Enter를 처리하기 전에 marked text 여부를 검사하므로, 이 방식에서는 조합 중에도 첫 Enter가 전송으로 처리됩니다. 텔레그램에서는 조합 밑줄이 표시되지 않고, 실행 취소 단위가 자모나 음절마다 나뉠 수 있습니다. 설정을 끄거나 다른 앱에서는 기존 marked text를 사용합니다. 이 설정은 텔레그램 앱 전체에 적용되므로 검색창과 이름 수정 등 다른 입력란에도 영향을 줍니다. 확인한 범위는 호환성 기록을 참고하세요.

조사 근거와 원인/한계 분석은 docs/research.md에 정리되어 있습니다.

개인정보

키 입력은 현재 포커스된 앱으로 전달하기 위해 메모리에서만 처리합니다. 네트워크 연결은 업데이트 확인·다운로드에만 사용하며, 키 입력을 기록하거나 전송하지 않습니다. 접근성 권한을 사용하지 않습니다. 선택 구성인 Karabiner-Elements는 키를 재매핑하기 위한 별도의 macOS 권한과 드라이버를 사용합니다. 글가드 자체의 권한과 구분하세요.

Contributing

버그 재현 사례, 호환성 결과, 코드 기여를 환영합니다. 시작하기 전에 CONTRIBUTING.md를 확인해 주세요.

License

GeulGuard is available under the MIT License.