Origin story: spotted a Windows gist that wires Claude Code into system notifications↗ , written in PowerShell, useless on a Mac. Rewrote it for macOS, then added a Bark↗ channel — when a long job finishes and you’ve wandered off, the phone in your pocket should be the one that pings.

1. The shape of it

Claude Code’s hook system exposes a set of lifecycle events. For “notify me”, you only need two:

• Stop — the model finished its turn. Time to ring the bell.
• Notification — the model wants confirmation or input (permission prompts, questions). More urgent.

The hook command receives JSON on stdin: cwd (project path), transcript_path (full JSONL conversation), and Notification events also carry a message.

Design choices:

• Single Python file — macOS ships python3 by default, so no jq / curl JSON-escaping ceremony.
• Local toast prefers terminal-notifier — use it if installed (clickable, supports group dedup); fall back to osascript otherwise. Zero install required.
• Bark is opt-in — only fires when BARK_KEY is set. Failures are silent; the hook’s exit code stays clean.
• No chmod — see the “gotchas” section below. The script isn’t executable; we invoke it as python3 path/to/notify.py.

2. The script: ~/.claude/hooks/notify.py

#!/usr/bin/env python3
"""Claude Code notification hook for macOS.

Local toast (osascript or terminal-notifier) + optional Bark push.

Usage: notify.py <Stop|Notification|...>

Reads JSON from stdin (Claude Code hook payload):
  cwd               -> current working directory
  transcript_path   -> path to JSONL transcript (Stop event)
  message           -> notification message (Notification event)

Environment variables (all optional):
  BARK_KEY            Bark device key. If unset, Bark push is skipped.
  BARK_SERVER         Bark server (default: https://api.day.app).
  BARK_GROUP          Notification group (default: ClaudeCode).
  BARK_SOUND          Notification sound (default: minuet).
  BARK_ICON           Custom icon URL.
  BARK_STOP_LEVEL     Level for Stop events (default: passive).
  BARK_NOTIFY_LEVEL   Level for Notification events (default: timeSensitive).
                      Valid: active | timeSensitive | passive | critical.
  CLAUDE_NOTIFY_OFF   If set to "1", suppress all notifications.
"""
from __future__ import annotations

import json
import os
import shutil
import subprocess
import sys
import urllib.request
from pathlib import Path

TITLE_PREFIX = "ClaudeCode"
MAX_BODY_LEN = 200


def read_stdin_json() -> dict:
    try:
        raw = sys.stdin.read()
    except Exception:
        return {}
    if not raw.strip():
        return {}
    try:
        return json.loads(raw)
    except Exception:
        return {}


def last_assistant_text(transcript_path: str) -> str:
    p = Path(transcript_path)
    if not p.is_file():
        return ""
    try:
        with p.open("r", encoding="utf-8", errors="replace") as f:
            lines = f.readlines()[-30:]
    except Exception:
        return ""
    for line in reversed(lines):
        try:
            entry = json.loads(line)
        except Exception:
            continue
        msg = entry.get("message") or {}
        if msg.get("role") != "assistant":
            continue
        content = msg.get("content")
        text = ""
        if isinstance(content, str):
            text = content
        elif isinstance(content, list):
            for block in content:
                if isinstance(block, dict) and block.get("type") == "text":
                    t = block.get("text", "")
                    if t.strip():
                        text = t
                        break
        if text.strip():
            return text
    return ""


def truncate(s: str, n: int) -> str:
    s = (s or "").strip()
    if len(s) <= n:
        return s
    return s[: n - 1] + "…"


def send_mac_notification(title: str, body: str) -> None:
    tn = shutil.which("terminal-notifier")
    if tn:
        try:
            subprocess.run(
                [tn, "-title", title, "-message", body,
                 "-sound", "Glass", "-group", "claude-code", "-ignoreDnD"],
                check=False, timeout=5,
                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            )
            return
        except Exception:
            pass

    def esc(s: str) -> str:
        return s.replace("\\", "\\\\").replace('"', '\\"')

    script = (
        f'display notification "{esc(body)}" '
        f'with title "{esc(title)}" sound name "Glass"'
    )
    try:
        subprocess.run(
            ["osascript", "-e", script],
            check=False, timeout=5,
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
        )
    except Exception:
        pass


def send_bark_push(title: str, body: str, event: str) -> None:
    key = os.environ.get("BARK_KEY", "").strip()
    if not key:
        return

    server = os.environ.get("BARK_SERVER", "https://api.day.app").rstrip("/")

    if event == "Notification":
        level = os.environ.get("BARK_NOTIFY_LEVEL", "timeSensitive")
    elif event == "Stop":
        level = os.environ.get("BARK_STOP_LEVEL", "passive")
    else:
        level = "active"

    payload = {
        "title": title,
        "body": body or " ",
        "group": os.environ.get("BARK_GROUP", "ClaudeCode"),
        "level": level,
        "sound": os.environ.get("BARK_SOUND", "minuet"),
    }
    if icon := os.environ.get("BARK_ICON", "").strip():
        payload["icon"] = icon

    try:
        req = urllib.request.Request(
            f"{server}/{key}",
            data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
            method="POST",
            headers={"Content-Type": "application/json; charset=utf-8"},
        )
        with urllib.request.urlopen(req, timeout=5) as r:
            r.read()
    except Exception:
        pass


def main() -> int:
    if os.environ.get("CLAUDE_NOTIFY_OFF") == "1":
        return 0

    event = sys.argv[1] if len(sys.argv) > 1 else "Stop"
    data = read_stdin_json()

    cwd = data.get("cwd") or ""
    project = os.path.basename(cwd) if cwd else ""

    if event == "Stop":
        title = f"{TITLE_PREFIX} - {project}" if project else TITLE_PREFIX
        body = ""
        transcript = data.get("transcript_path") or ""
        if transcript:
            body = last_assistant_text(transcript)
        if not body.strip():
            body = "Task completed, please review results."
    elif event == "Notification":
        title = f"{TITLE_PREFIX} - Needs Attention"
        if project:
            title = f"{title} - {project}"
        body = (data.get("message") or "").strip() \
            or "Claude is waiting for your input or approval."
    else:
        title = TITLE_PREFIX
        body = f"Event received: {event}"

    body = truncate(body, MAX_BODY_LEN)

    send_mac_notification(title, body)
    send_bark_push(title, body, event)
    return 0


if __name__ == "__main__":
    sys.exit(main())

A few details worth flagging:

• Walking the transcript backwards — read the last 30 JSONL lines, iterate in reverse, take the first entry where role == "assistant" with non-empty text. The content field can be either a string or an array depending on SDK version; both shapes are handled.
• Truncation uses … — a single ellipsis character, not three ASCII dots. Saves two bytes for actual prose.
• Bark level differs by event — Stop defaults to passive (silent, just lands in the push list), Notification defaults to timeSensitive (pierces Focus mode). Long jobs finishing shouldn’t shriek; mid-task confirmations must.
• Silent failure — Bark unreachable, osascript erroring, transcript missing — all caught and swallowed. A hook should never wedge the model.

3. Wiring it into ~/.claude/settings.json

Merge this block into settings.json, preserving your existing env / permissions / enabledPlugins etc.:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/.claude/hooks/notify.py Notification",
            "timeout": 15
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/.claude/hooks/notify.py Stop",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

matcher: "" is “match anything” — Stop and Notification don’t have sub-matchers anyway. The timeout: 15 seconds is a backstop; timing out doesn’t break the main flow.

4. Enabling Bark

Bark is a long-running iOS push tool. The free key comes from day.app↗ . Install the app and the home screen shows a URL like https://api.day.app/abc123xyz/ — the middle slug is your device key.

Drop it into the env block of settings.json (hooks inherit env from there):

"env": {
  "BARK_KEY": "abc123xyz"
}

Quick reference for the optional knobs:

5. Verification

With BARK_KEY set, fire a manual Notification simulation:

BARK_KEY=your_key echo '{"cwd":"/tmp","message":"test"}' \
  | python3 ~/.claude/hooks/notify.py Notification

Expected:

1. A macOS toast pops in the top-right corner.
2. A Bark notification arrives on your phone, grouped under ClaudeCode, level timeSensitive.

To preview local-only behavior, just unset BARK_KEY for the call.

6. Gotchas

Hook not firing? The Claude Code settings watcher only watches directories that already had a settings file at session start. If .claude/ was created mid-session, edits may not reload. Open the /hooks menu once (forces a reload), or restart the Claude Code session.

chmod denied in your permissions? My settings include Bash(chmod:*) in permissions.deny, so the script can’t be chmod +x’d. Fix: invoke via python3 path/to/notify.py so the executable bit is irrelevant. Bonus — it’s more explicit and removes a hidden piece of state.

Body too long? The script caps at MAX_BODY_LEN = 200 (199 chars + …). macOS Notification Center will truncate too, but capping early avoids ugly mid-JSON breakage on the Bark side.

Want to dial it back? Stop fires every turn — easy to find noisy. Two ways out:

• The Bark side already uses BARK_STOP_LEVEL = passive — silent push, lands in the list only.
• For local silence on Stop too: add if event == "Stop": return to the top of send_mac_notification. Five-line change.

7. Where to take it next

Saving these for future me:

• Telegram / Lark / Slack — rename send_bark_push to send_remote_push, dispatch on a REMOTE_KIND env var. Bark is just one of many.
• Sharper Notification copy — currently I just pass through whatever message the model sent. Could branch on tool_name (if hook payload starts including it) for sharper titles.
• Debounce a burst — multiple Stop events within 5s collapsed into one. Right now every turn rings.
• Stats — append a line to ~/.claude/hooks/notify.log per fire. A week’s worth of “how many turns ran, how often the model got blocked on input” tells you something interesting.

You set this up once and forget about it. When the model finishes a turn or stalls waiting for input, a soft chime in the top-right and a buzz in your pocket — long jobs can finally run while you make a coffee.

Rendering verification for T11e. The callout shortcode has four supported types — note / tip / warn / danger — wired up in layouts/partials/icon.html and styled in assets/css/components.css. Any other type falls back to an icon-less shell, so this page only exercises the four real ones.

1. All four types, with title

2. Without title

3. Nested markdown

Self-check list

• The four types use distinct colors (grey / green / amber / vermilion)
• All four icon partials resolve — no empty <div class="callout-icon">
• Variants with a title show <p class="callout-title"> in bold
• Nested markdown renders correctly (bold / link / inline code)
• All four types remain readable in dark mode

Rendering verification for T11f. The pullquote shortcode was added in E8; it emits <blockquote class="pullquote"> and is styled by prose.css. This page covers both shapes — with and without an author — and one nested-markdown case.

1. With author

The truly brave dare to face a bleak life head-on. — Lu Xun

2. Without author

“Good enough” is not the ceiling of taste — it is the ticket of admission.

3. Inner with markdown

Good writing precedes style , and precedes tooling. — An editor

Self-check list

• Both shapes adopt prose pullquote styling (large quote glyph / centered or left-aligned / font-size larger than body)
• With-author variant renders <cite>— Lu Xun</cite> at a smaller size
• Without-author variant emits no empty <cite>
• Nested markdown renders correctly (bold / link / inline code)
• Borders and text remain readable in dark mode

Rendering verification for T11g. The gallery shortcode itself only emits a placeholder div; the shortcode_gallery partial fetches the JSON at runtime, hands it to justifiedGallery for layout, and to lightGallery for the overlay. Fixture: /data/smoke/gallery.json — three placehold.co images.

1. A single gallery

Self-check list

• Browser Network panel: /data/smoke/gallery.json returns 200
• CDN injection: jQuery / justifiedGallery / lightGallery (+ thumbnail / zoom plugins) all load
• DOM: #gallery-1 is replaced at runtime with three <a><img></a> items, laid out on one row by justifiedGallery
• Clicking any thumbnail opens the lightGallery overlay with arrow navigation across all three images
• The overlay caption shows the subHtml block (“Smoke fixture #1/2/3”)
• Background and controls are readable in dark mode
• No lightGallery / justifiedGallery errors in the console

Rendering verification for T11h. The include shortcode runs readFile | safeHTML, dropping a project-root-relative file’s contents into the page as raw HTML. Fixture: assets/snippets/hello.html — a small heading / list / link snippet.

1. Including an HTML snippet

The block below is pulled in via the include shortcode:

Self-check list

• The block above renders as HTML — not as source (no visible <section> tag characters)
• The “Inkstone include fixture” heading is rendered as <h3>
• The three list items render as <li>, with inner <code> adopting the site inline-code style
• The “example.com” link in the final item is a real link, with target="_blank" on hover
• Hugo build emits no readFile error

Rendering verification for T11i. The include-code shortcode reads a file via readFile, wraps it in a fenced code block, and runs it through markdownify so Chroma applies syntax highlighting. This page exercises two languages — python and yaml — switched via the language= parameter.

1. Python (assets/snippets/hello.py)

def gcd(a: int, b: int) -> int:
    """Return the greatest common divisor of a and b."""
    while b:
        a, b = b, a % b
    return a


if __name__ == "__main__":
    print(gcd(12, 18))

2. YAML (assets/snippets/config.yaml)

server:
  host: 0.0.0.0
  port: 8080

logging:
  level: info
  format: json

features:
  - search
  - rss
  - sitemap

Self-check list

• Both blocks render as <pre><code class="language-..."> rather than as raw source
• Python block: keywords like def / if __name__ are colored by Chroma; docstring is colored too
• YAML block: keys, strings, and numbers are colored per YAML rules (no fallback to plain text)
• Line-height / font-size / background match every other fenced code block on the site
• Both blocks remain readable in dark mode (syntax / background contrast holds)
• Hugo build emits no readFile error

Rendering verification for T11d. Demonstrates the three common scenarios where the tab shortcode combines with code blocks. If switching tabs does not switch the code block, the :checked+label+.shortcode-tab-item selector in tab.css isn’t taking effect.

1. Cross-platform command switching (macOS / Windows / Linux)

The most common usage — same goal, different shells, different commands.

podman compose exec openclaw-gateway \
  node dist/index.js channels login --channel feishu

podman compose exec openclaw-gateway `
  node dist/index.js channels login --channel feishu

sudo podman compose exec openclaw-gateway \
  node dist/index.js channels login --channel feishu

Scan the generated QR code with the companion app to continue configuration.

2. Multi-language code samples (same algorithm)

Useful for the “same concept, different languages” explainer pattern.

def gcd(a: int, b: int) -> int:
    while b:
        a, b = b, a % b
    return a

function gcd(a: number, b: number): number {
  while (b !== 0) {
    [a, b] = [b, a % b];
  }
  return a;
}

func gcd(a, b int) int {
    for b != 0 {
        a, b = b, a%b
    }
    return a
}

fn gcd(mut a: u64, mut b: u64) -> u64 {
    while b != 0 {
        let t = b;
        b = a % b;
        a = t;
    }
    a
}

3. Multi-format config switching (YAML / TOML / JSON)

The “pick whichever format you like” style of config example.

server:
  host: 0.0.0.0
  port: 8080
channels:
  - name: feishu
    enabled: true

[server]
host = "0.0.0.0"
port = 8080

[[channels]]
name = "feishu"
enabled = true

{
  "server": { "host": "0.0.0.0", "port": 8080 },
  "channels": [{ "name": "feishu", "enabled": true }]
}

4. tab + highlight shortcode (with title bar)

If you want a title bar on the code block (Hugo’s highlight shortcode provides one), swap the fenced block for {{< highlight >}}:

DATABASE_URL=postgres://localhost:5432/inkstone_dev
DEBUG=true
LOG_LEVEL=debug

DATABASE_URL=postgres://prod-db:5432/inkstone
DEBUG=false
LOG_LEVEL=warn

Self-check list

• Tab switch: clicking different labels switches the code block (CSS only, no JS)
• Active state: the current tab’s label has a 2px underline
• Nesting: both fenced code blocks and {{< highlight >}} render correctly
• Emoji label: 🍎 / 🪟 / 🐧 renders correctly
• position attribute: section 3 uses position="start"; labels align to the start
• Dark mode: after switching to dark, the underline color swaps (--color-shortcode-tab-label-bottom)

Rendering verification for T11a. If you see source instead of a rendered figure, the corresponding shortcode isn’t wired up.

1. MathJax

Inline: the mass–energy equation \(E = mc^2\).

Display:

$$ \int_{-\infty}^{\infty} e^{-x^2},dx = \sqrt{\pi} $$

2. Mermaid

  flowchart LR
  A[content] --> B[markup hook]
  B --> C[Page.Store hasMermaid]
  C --> D[scripts.html init]

3. Markmap

4. Pseudocode

    
\begin{algorithm}
\caption{Euclid's algorithm (gcd)}
\begin{algorithmic}
\PROCEDURE{Gcd}{$a, b$}
  \WHILE{$b \neq 0$}
    \STATE $t \gets b$
    \STATE $b \gets a \bmod b$
    \STATE $a \gets t$
  \ENDWHILE
  \RETURN $a$
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

  

5. AntV G2

(antv-g2 needs a data file to be present; this is just a placeholder call. With no script= attribute it skips the actual chart, but the g2 library should still load correctly.)

6. Theme switch propagation (05-04-theme-broadcast)

After loading this page, click the sidebar “Theme” button. You should see:

• mermaid flowchart palette flips immediately (neutral ↔ dark), no double-render ghost
• If a real antv-g2 chart is present, its palette flips immediately
• After 5 toggles window.antvG2Charts.length does not grow (memory-leak guard)
• No console errors during the toggle
• markmap node text / links / code blocks follow the switch (CSS tokens inherit into <foreignObject>; branch strokes do not follow because of inline strokes inside the library — known limitation, see .trellis/spec/frontend/themed-components.md §4)

Rendering verification for T11b. If any of iframe / video player / swiper / image-compare fails to appear, the corresponding shortcode isn’t wired up.

1. Bilibili

2. Video.js (HTML5 video player)

3. YouTube

4. Iframe (generic embed)

4a. Iframe (whitelisted host: CodePen theme bridge)

After toggling the site to dark mode, this iframe should auto-reload into the dark theme; the very first request should already carry theme-id=dark. Non-whitelisted hosts (example.com) stay as-is and do not reload.

5. Swiper

(swiper requires a data file; this is a placeholder to verify that swiper-bundle JS/CSS is injected. A full test needs a real data reference like assets/data/cn/2020-06-06-bayesian-optimization/active-gp.json, to be added when actual posts are migrated back.)

6. Image Compare

(image-compare needs before/after images; this is a placeholder to verify that image-compare-viewer is injected.)

Rendering verification for T11c. gallery / include / include-code depend on external data/files and are only verified inside real posts.

1. Figure (explicit shortcode form)

2. Tab

3. Flex

4. Song

5. Douban Card

人类群星闪耀时

豆 豆瓣评分

9.0

历史 / 茨威格

14 个人类历史的高光时刻。

6. Copy to clipboard

7. Button

8. Details

9. Highlight (with title)

def gcd(a, b):
    while b:
        a, b = b, a % b
    return a

10. Admonition