Hourglyph
EN

Add your work to the map

Three hooks in your Claude Code settings anonymously record session starts, every message you send and the tokens used per turn — so the map sees real load inside long sessions, not just session starts. It’s opt-in, and removing a few lines turns it off.

1. Install the hooks

Option A: let Claude Code do iteasiest

Copy the prompt and send it to Claude Code. The agent downloads the script and shows it to you, backs up your settings, replaces an older Hourglyph hook if there is one, merges the new entries in and shows you the diff. Claude Code asks for permission before writing files.

Set up the Hourglyph hooks for Claude Code on this machine (https://hourglyph.github.io/setup/).

Goal: anonymously send session starts, the times I send messages, and token counts per turn to the peak-hours map. Message text, answers, code and paths are never sent.

Steps:
1. Download the script and show me its full contents before continuing:
   mkdir -p ~/.claude/hooks && curl -fsSL https://hourglyph.github.io/hook/hourglyph.sh -o ~/.claude/hooks/hourglyph.sh
   (source on GitHub: https://github.com/hourglyph/hourglyph.github.io/blob/main/public/hook/hourglyph.sh). Check that it does nothing but send an event name and four token counts.
2. Read ~/.claude/settings.json (treat a missing file as {}). If it exists, back it up to ~/.claude/settings.json.bak first.
3. Remove any old Hourglyph entries from hooks — commands containing "hourglyph.sh" / "rpc/checkin" — so nothing is duplicated.
4. Merge, don't overwrite: keep every other setting and hook, and append exactly these elements to hooks.SessionStart, hooks.UserPromptSubmit and hooks.Stop (create them if missing):

{
  "SessionStart": [
    {
      "matcher": "startup",
      "hooks": [
        {
          "type": "command",
          "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" session",
          "async": true
        }
      ]
    }
  ],
  "UserPromptSubmit": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" message",
          "async": true
        }
      ]
    }
  ],
  "Stop": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" stop",
          "async": true
        }
      ]
    }
  ]
}

5. Write the file back as valid JSON and re-read it to confirm it parses.
6. Check that curl and awk are available (command -v curl awk).
7. Show me the diff and tell me how to remove everything: delete those three entries from settings.json and the file ~/.claude/hooks/hourglyph.sh — or in one command: curl -fsSL https://hourglyph.github.io/hook/uninstall.sh | sh

Don't change anything else. Data starts flowing with the next new session.

Option B: by hand

Download the script (read the source on GitHub, 65 lines of sh + awk):

mkdir -p ~/.claude/hooks && curl -fsSL https://hourglyph.github.io/hook/hourglyph.sh -o ~/.claude/hooks/hourglyph.sh

Then add the hooks block to ~/.claude/settings.json (or merge it into an existing one). If you had the older hook with rpc/checkin, remove it.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" session",
            "async": true
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" message",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$HOME/.claude/hooks/hourglyph.sh\" stop",
            "async": true
          }
        ]
      }
    ]
  }
}

2. What gets sent

HookWhenWhat is sent
SessionStarta new session starts{"p_event":"session"}
UserPromptSubmityou send a message{"p_event":"message"} — no text
StopClaude finishes a turn4 integers: input, output, cache-write and cache-read tokens

3. Verify

Start claude in a new terminal, send a message, wait a minute and open the map — the message and token counters go up. The /hooks command lists active hooks.

How to turn it off

One command removes only the Hourglyph entries from ~/.claude/settings.json (keeping a backup at settings.json.hourglyph-bak) and deletes the script. Your other hooks and settings stay as they are. Read the source on GitHub.

curl -fsSL https://hourglyph.github.io/hook/uninstall.sh | sh

Needs python3 or node; without them it changes nothing and tells you what to remove by hand.

Or ask Claude Code

Remove the Hourglyph hooks for Claude Code on this machine (https://hourglyph.github.io/setup/).

1. Back up ~/.claude/settings.json to ~/.claude/settings.json.hourglyph-bak.
2. Remove only the Hourglyph entries from hooks — commands containing "hourglyph.sh" / "rpc/checkin". Keep every other hook and setting as is; drop groups and events left empty.
3. Write the file back as valid JSON and re-read it to confirm it parses.
4. Delete ~/.claude/hooks/hourglyph.sh.
5. Show me the diff.

By hand

Delete the three entries mentioning hourglyph.sh from ~/.claude/settings.json and the file ~/.claude/hooks/hourglyph.sh. Data already sent is anonymous and not linked to you.

Notes