설치 안내
Hamster 설치하기
Hamster는 무료 오픈소스 Mac 앱이에요. Apple 서명과 공증 없이 GitHub Releases로 배포해서 처음 열 때 승인이 한 번 더 필요해요. 아래 순서대로 따라 하면 돼요.
1. 받기
GitHub Releases에서 최신 zip 파일을 받아요. 같은 페이지에 적힌 SHA-256 값과 내 파일의 값이 같은지 확인하세요.
shasum -a 256 ~/Downloads/Hamster-<버전>.zip값이 다르면 열지 말고 Issues에 알려 주세요. 같으면 zip을 풀어 Hamster.app을 꺼내요.
2. 응용 프로그램 폴더로 옮기기
열기 전에 Hamster.app을 응용 프로그램 폴더로 옮겨요. 받은 폴더에서 바로 열면 macOS가 앱을 임시 읽기 전용 위치로 옮겨 실행해요(App Translocation). 그러면 업데이트가 깨져요.
3. 처음 열기
- Hamster를 한 번 열어요. 열 수 없다는 경고가 뜨면 닫아요.
- 시스템 설정 → 개인정보 보호 및 보안을 열고 보안 항목까지 내려가요. Hamster를 차단했다는 안내 옆에 그래도 열기 버튼이 있어요.
- 그래도 열기를 누르고 Mac 암호를 입력해요.
이 버튼은 열어 보려 한 뒤 1시간 정도만 보여요. 안 보이면 Hamster를 한 번 더 열어요. 처음 한 번만 하면 돼요. Apple 안내
4. AI 도구 연결
메뉴 막대의 Hamster 아이콘에서 AI 연결 → 쓰는 도구 → 훅 설치…를 눌러요. 도구마다 따로 연결해요. Hamster는 아래 파일에 자기 훅만 추가하고, 다른 설정과 훅은 그대로 둬요. 파일이 없으면 새로 만들고, 저장할 때 들여쓰기가 바뀔 수 있어요.
| 도구 | 수정하는 파일 | 훅 이벤트 |
|---|---|---|
| Codex | ~/.codex/hooks.json | UserPromptSubmit Stop Interrupt |
| Claude Code | ~/.claude/settings.json | UserPromptSubmit Stop StopFailure SessionEnd |
| Cursor Agent | ~/.cursor/hooks.json | beforeSubmitPrompt stop sessionEnd |
| Gemini CLI | ~/.gemini/settings.json | BeforeAgent AfterAgent SessionEnd |
| Grok | ~/.grok/hooks/hamster.json | UserPromptSubmit Stop StopFailure StopCancelled SessionEnd Notification |
CODEX_HOME, CLAUDE_CONFIG_DIR, GEMINI_CLI_HOME, GROK_HOME 환경 변수를 설정했다면 그 폴더를 써요. 각 폴더의 hamster 폴더에는 작은 도우미 프로그램(codex-hook-v2, ai-hook-v2 또는 ai-hook-v3)이 복사되고, 훅이 그 프로그램을 가리켜요.
Codex는 설치 뒤 Settings → Hooks에서 Hamster 훅을 승인해야 해요. Claude Code, Gemini CLI, Grok은 새 세션에서 /hooks(Gemini는 /hooks list)로 확인해요. Cursor는 Hooks 설정에서 확인해요. Grok은 Claude Code 훅도 함께 실행하지만, Hamster는 Grok의 신호를 Grok 훅에서만 받아요.
업데이트
앱이 하루에 한두 번 GitHub 릴리스를 확인해요. 새 버전이 있으면 메뉴에 보여 주고, 내가 누를 때만 설치해요. 받은 파일은 서명을 확인한 뒤에만 설치해요.
지우기
- AI 연결 → 도구 → Hamster 훅 제거를 눌러요. 연결한 도구마다 해요. 제거는 Hamster 훅만 지워요.
- 메뉴에서 Hamster를 종료하고, 응용 프로그램의 Hamster.app을 휴지통으로 옮겨요.
- 남은 도우미 프로그램은
~/.codex/hamster같은hamster폴더에서 지울 수 있어요.
개인정보
Hamster는 업데이트 정보를 GitHub에서 가져오는 것 말고는 아무것도 보내지 않아요. 토큰 사용량을 보여 주려고 이 Mac에 남은 AI 도구의 대화 기록에서 토큰 숫자를 읽어요. Claude Code에서 작업을 중단했는지 알아보려고 그 세션 대화 기록의 끝부분에서 중단 표시도 확인해요. 프롬프트와 작업 내용은 저장하거나 보내지 않아요. 소스가 공개되어 있어서 직접 확인할 수 있어요.
문제가 생기면
GitHub Issues에 남겨 주세요. 프롬프트, 코드, 키, 개인정보는 올리지 마세요.