Install guide

Install Hamster

Hamster is a free, open source Mac app. It ships through GitHub Releases without Apple signing or notarization, so the first launch needs one extra approval. Follow these steps.

Download from GitHub Source code

1. Download

Get the latest zip from GitHub Releases. Check that the SHA-256 listed on the release page matches your file.

shasum -a 256 ~/Downloads/Hamster-<version>.zip

If the values differ, don’t open it. Tell us in Issues. If they match, unzip it to get Hamster.app.

2. Move it to Applications

Move Hamster.app to your Applications folder before you open it. If you open it from Downloads, macOS runs it from a temporary read-only location (app translocation), and updates break.

3. Open it the first time

Open Hamster once. When macOS warns that it can’t open the app, close the warning.
Open System Settings → Privacy & Security and scroll to Security. Next to the note that Hamster was blocked, there is an Open Anyway button.
Click Open Anyway and enter your Mac password.

The button shows for about an hour after you try to open the app. If it’s gone, open Hamster again. You only do this once. Apple’s guide

4. Connect an AI tool

From the Hamster icon in the menu bar, choose AI Connection → your tool → Install … Hooks…. Connect each tool separately. Hamster adds only its own hooks to the files below and leaves your other settings and hooks alone. It creates the file if it’s missing, and saving may change the indentation.

Tool	File it edits	Hook events
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`

If you set CODEX_HOME, CLAUDE_CONFIG_DIR, GEMINI_CLI_HOME or GROK_HOME, Hamster uses that folder instead. Each folder also gets a hamster folder with a small helper program (codex-hook-v2, ai-hook-v2 or ai-hook-v3) that the hooks point to.

For Codex, approve the Hamster hooks in Settings → Hooks after installing. For Claude Code, Gemini CLI and Grok, open a new session and check /hooks (/hooks list in Gemini). For Cursor, check the Hooks settings. Grok also runs Claude Code hooks, but Hamster takes Grok’s signals only from the Grok hook.

Updates

The app checks the GitHub release once or twice a day. If there’s a new version, it shows up in the menu, and it installs only when you click it. Downloads are checked with a signature before they’re installed.

Removing Hamster

Choose AI Connection → your tool → Remove Hamster Hooks. Do this for each tool you connected. It removes only Hamster’s hooks.
Quit Hamster from its menu, then move Hamster.app from Applications to the Trash.
You can delete the leftover helper from the hamster folder, such as ~/.codex/hamster.

Privacy

Hamster sends nothing except fetching the update information from GitHub. To show token usage it reads the token counts from your AI tools’ records on this Mac. To notice when you stop a Claude Code turn, it also checks the end of that session’s transcript for the interrupt marker. It never stores or sends your prompts or your work. The source is public, so you can check for yourself.

Something wrong?

Open an issue on GitHub Issues. Please don’t post prompts, code, keys or personal information.