Zurück zum Blog

Codex CLI Benachrichtigungen: Push-Nachricht, wenn die Aufgabe fertig ist

Codex CLI Benachrichtigungen: Push-Nachricht, wenn die Aufgabe fertig ist

Codex CLI sagt dir schon Bescheid, wenn es fertig ist, solange du aufs Terminal schaust. Die eingebauten Benachrichtigungen sind Terminal-Escape-Sequenzen: ein Desktop-Banner, wenn dein Terminal das unterstützt, sonst ein Piepton. Keines davon folgt dir in die Küche.

Codex kann außerdem an bestimmten Punkten seines Lebenszyklus eigene Befehle ausführen, und genau das braucht eine Push-Benachrichtigung aufs Handy. Diese Anleitung schickt eine, wenn Codex einen Durchgang abschließt, und eine weitere, wenn es anhält und um Freigabe bittet.

Zwei Wege, wie Codex deinen Befehl ausführt

  • Hooks, der aktuelle Mechanismus. Konfiguriert in hooks.json, standardmäßig aktiviert, mit Ereignissen wie Stop, PermissionRequest, PreToolUse und SessionEnd. Der Befehl bekommt das Ereignis als JSON auf stdin.
  • notify, die ältere Einstellung in config.toml. Sie feuert bei einem Ereignis, agent-turn-complete, und übergibt das JSON als letztes Kommandozeilenargument. Sie funktioniert noch, aber der Codex-Quellcode markiert sie als Legacy.

Nimm Hooks. Die notify-Variante steht am Ende für ältere Setups.

Was du brauchst

  • Codex CLI, eine aktuelle Version mit Hooks.
  • jq und curl.
  • Ein Pocket-Alert-Konto, einen API-Schlüssel aus API Keys und die App auf deinem Handy. Der kostenlose Tarif reicht.

Lege den API-Schlüssel in einer Datei ab, die nur du lesen kannst, damit er nicht in deiner Shell-History oder der Umgebung landet:

mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key

Schritt 1. Das Hook-Skript

Speichere dies als ~/.codex/hooks/pocketalert.sh:

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Codex finished · $project"
    message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
    level=default ;;
  PermissionRequest)
    title="Codex needs approval · $project"
    message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$payload")
    level=high ;;
  *) exit 0 ;;
esac

jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
  '{title: $t, message: $m, level: $l}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

exit 0
chmod +x ~/.codex/hooks/pocketalert.sh

Codex ist bei der Hook-Ausgabe streng. Bei Stop erwartet es entweder nichts oder JSON auf stdout, und Exit-Code 2 sagt ihm, dass es weitermachen statt anzuhalten. Deshalb geht jede Ausgabe von curl nach /dev/null, und das Skript endet immer mit exit 0.

PermissionRequest-Hooks können auch im Namen von Codex freigeben oder ablehnen. Dieser hier tut nichts davon: Er gibt nichts aus, sodass Codex seine normale Freigabeabfrage zeigt, und du bekommst eine Push-Nachricht, dass es auf dich wartet.

Oder mit der Pocket Alert CLI

Mit installierter Pocket Alert CLI ab Version 2.0 schrumpft der curl-Block auf einen Befehl. Die CLI maskiert den Text selbst und liest den Schlüssel aus pocketalert auth, sodass die Schlüsseldatei nicht mehr nötig ist:

pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true

Verwende -t und -m statt Positionsargumenten: Eine Antwort, die mit einem Bindestrich beginnt, etwa eine Markdown-Liste, würde sonst als Option gelesen.

Schritt 2. Die Hooks registrieren

Erstelle ~/.codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

Die Datei in deinem Home-Verzeichnis gilt überall. Eine .codex/hooks.json innerhalb eines Repositories gilt nur für dieses Projekt, und zwar erst, nachdem du das Projekt als vertrauenswürdig markiert hast.

Hooks sind standardmäßig aktiv. Hast du sie irgendwann ausgeschaltet, entferne hooks = false aus der Tabelle [features] in ~/.codex/config.toml.

Codex führt nur Hooks aus, die du geprüft und als vertrauenswürdig eingestuft hast. Beim nächsten Start warnt es, dass neue Hooks eine Prüfung brauchen: Öffne /hooks, sieh dir die beiden Einträge an und vertraue ihnen. Änderst du sie später, überspringt Codex sie, bis du ihnen erneut vertraust.

Schritt 3. Testen

Starte Codex in einem beliebigen Projekt und gib ihm eine kurze Aufgabe:

> Summarise README.md in one sentence.

Wenn der Durchgang endet, zeigt dein Handy Codex finished · your-project mit der Zusammenfassung. Bitte es, einen Befehl auszuführen, der eine Freigabe braucht, und eine zweite Push-Nachricht, Codex needs approval, kommt mit hoher Priorität an.

Um das Skript ohne Codex zu testen:

echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | ~/.codex/hooks/pocketalert.sh

Was auf dem Handy ankommt

EreignisTitelTextStufe
Durchgang beendetCodex finished · apiDie ersten 300 Zeichen der letzten Antwortdefault
Freigabe nötigCodex needs approval · apiWants to run Bashhigh

high wird auf dem iPhone als zeitkritisch zugestellt, sodass die Freigabe-Push-Nachricht den Fokus-Modus durchbricht, während routinemäßige „finished“-Nachrichten still bleiben. Beide bleiben im Verlauf der App und im Web-Dashboard erhalten.

Der ältere Weg: notify

Wenn deine Codex-Version älter ist als die Hooks oder du bereits notify nutzt, funktioniert es mit ein paar Änderungen. Codex übergibt das Ereignis als letztes Argument statt über stdin, verwendet Schlüssel in Kebab-Case und meldet nur abgeschlossene Durchgänge:

#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0

jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
  '{title: "Codex finished", message: $m}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]

notify kennt kein Freigabe-Ereignis. Nutze daher Hooks, wenn du wissen willst, wann Codex blockiert ist.

Oder lass Codex es über MCP senden

Hooks feuern bei festen Ereignissen. Damit Codex selbst entscheidet, was es dir mitteilt, füge den Pocket Alert MCP-Server zu ~/.codex/config.toml hinzu:

[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"

oder über die Kommandozeile:

codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
  --bearer-token-env-var POCKETALERT_API_KEY

Exportiere POCKETALERT_API_KEY in der Shell, die Codex startet. Dann endet ein Prompt wie „führe die Testsuite aus und schick mir die Fehler als Push“ damit, dass Codex create_message mit einer selbst geschriebenen Zusammenfassung aufruft. Das Tool akzeptiert außerdem level und actions.

Wenn nichts ankommt

  • Führe den Testbefehl aus. Funktioniert er dort, liegt das Problem bei der Hook-Registrierung; wenn nicht, entferne >/dev/null 2>&1, um curls Fehler zu sehen. 401 bedeutet, dass der Schlüssel falsch ist.
  • Prüfe, ob die Hooks vertrauenswürdig sind. Öffne /hooks in Codex; nicht vertrauenswürdige oder geänderte Hooks werden übersprungen.
  • Prüfe, ob das Projekt vertrauenswürdig ist, wenn du hooks.json im Repository abgelegt hast.
  • Prüfe, ob jq im PATH liegt, den Codex sieht. Hook-Befehle laufen mit der Umgebung von Codex und dem Arbeitsverzeichnis der Sitzung.
  • Prüfe das Tageslimit. Der kostenlose Tarif verschickt 50 Nachrichten am Tag, und Stop feuert nach jedem Durchgang.

FAQ

Was ist mit [tui] notifications?

Das ist die eingebaute Terminal-Benachrichtigung von Codex. Sie ist standardmäßig aktiv und kann sowohl abgeschlossene Durchgänge als auch Freigabeanfragen abdecken, erscheint aber auf dem Computer, über dein Terminal. Eine Push-Benachrichtigung erreicht dein Handy und bleibt im Verlauf erhalten.

Funktioniert das in der Codex-IDE-Erweiterung?

Die Erweiterung führt den Codex-Agenten auf deinem Rechner mit derselben ~/.codex-Konfiguration aus. Richte die Hooks also zuerst in der CLI ein und vertraue ihnen dort. Codex-Cloud-Aufgaben laufen auf den Servern von OpenAI und führen deine lokalen Hooks nicht aus.

Kann ich vom Handy aus freigeben?

Mit diesem Skript nicht: Es sagt dir nur, dass Codex wartet. Ein PermissionRequest-Hook kann eine Entscheidung zum Erlauben oder Ablehnen zurückgeben, sodass du darauf Freigaben mit einem Endpunkt aufbauen kannst, den dein Handy aufruft. Human-in-the-loop-Benachrichtigungen zeigt das Muster.

Ist es kostenlos?

Ja. Hooks sind in Codex eingebaut, und der kostenlose Tarif von Pocket Alert umfasst 50 Nachrichten am Tag auf einem Gerät.

Hol dir einen API-Schlüssel, füge den Hook hinzu und schau nicht mehr ständig ins Terminal.

Artikel teilen