# 777genius/claude-notifications-go architecture

> Architecture diagram of the GitHub repository 777genius/claude-notifications-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/777genius/claude-notifications-go
- Repository: https://github.com/777genius/claude-notifications-go

## Overview

Agent Notifications is a cross-platform desktop alert and click-to-focus product for Claude Code and Codex CLI. The principal workflow is agent hook events entering the Go CLI, being interpreted and enriched with session/project context, filtered and deduplicated by policy, then delivered through desktop notifications, sound, or optional webhooks. Setup and configuration manage each agent’s hooks and settings; the README also documents terminal targeting, sound controls, focus-aware delivery, and webhook integrations. The graph follows documented capabilities where source excerpts were unavailable; those branches use exact enclosing paths from the tree.

Main entry points: [`cmd/claude-notifications/main.go`](https://github.com/777genius/claude-notifications-go/blob/main/cmd/claude-notifications/main.go) (Hook CLI), [`internal/notifier/notifier.go`](https://github.com/777genius/claude-notifications-go/blob/main/internal/notifier/notifier.go) (Notification dispatcher), [`internal/notifier`](https://github.com/777genius/claude-notifications-go/tree/main/internal/notifier) (Desktop notifications), [`internal/config`](https://github.com/777genius/claude-notifications-go/tree/main/internal/config) (Effective settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_events["Event intake"]
  node_cli["Hook CLI<br/>[main.go]"]
  node_hookparse["Hook mapping"]
  node_codexmap["Codex mapping<br/>[codexsource.go]"]
end

subgraph group_policy["Context and policy"]
  node_context["Session context"]
  node_enrich["Event enrichment<br/>[enricher.go]"]
  node_config["Effective settings"]
  node_policyeval["Delivery policy"]
  node_dedup["Duplicate suppression<br/>[dedup.go]"]
  node_journal[("Event journal")]
end

subgraph group_delivery["Alert delivery"]
  node_notify["Notification dispatcher<br/>[notifier.go]"]
  node_desktop["Desktop notifications"]
  node_focus["Focus targeting"]
  node_daemon["Focus daemon<br/>[server.go]"]
  node_audio["Sound playback<br/>[audio.go]"]
  node_soundcatalog["Sound catalog<br/>[sounds.go]"]
  node_webhook["Webhook delivery"]
end

subgraph group_setup["Setup and settings"]
  node_setupwizard["Setup wizard"]
  node_registration["Agent registration<br/>[registration.go]"]
  node_codexsetup["Codex setup"]
  node_installer["Runtime installer"]
  node_settingscli["Config commands<br/>[config_command.go]"]
end

node_claude(("Claude Code"))
node_codex(("Codex CLI"))
node_webhookservice(("Webhook endpoints"))

node_claude -->|"invokes hooks"| node_cli
node_codex -->|"invokes hooks"| node_cli
node_cli -->|"routes Claude events"| node_hookparse
node_cli -->|"maps Codex events"| node_codexmap
node_cli -->|"reads context"| node_context
node_cli -->|"enriches events"| node_enrich
node_cli -->|"loads settings"| node_config
node_cli -->|"evaluates delivery"| node_policyeval
node_cli -->|"suppresses repeats"| node_dedup
node_cli -->|"records state"| node_journal
node_cli -->|"dispatches alerts"| node_notify
node_notify -->|"sends alerts"| node_desktop
node_notify -->|"plays sound"| node_audio
node_notify -.->|"sends webhooks"| node_webhook
node_webhook -.->|"posts events"| node_webhookservice
node_desktop -->|"attaches target"| node_focus
node_daemon -->|"sends alerts"| node_desktop
node_daemon -->|"handles click"| node_focus
node_settingscli -->|"inspects settings"| node_config
node_setupwizard -->|"configures hooks"| node_registration
node_setupwizard -->|"prepares settings"| node_config
node_codexsetup -->|"registers Codex"| node_registration
node_installer -->|"installs runtime"| node_cli
node_soundcatalog -->|"selects sounds"| node_audio

click node_cli "https://github.com/777genius/claude-notifications-go/blob/main/cmd/claude-notifications/main.go"
click node_hookparse "https://github.com/777genius/claude-notifications-go/tree/main/internal/hooks"
click node_codexmap "https://github.com/777genius/claude-notifications-go/blob/main/internal/codexsource/codexsource.go"
click node_context "https://github.com/777genius/claude-notifications-go/tree/main/internal/analyzer"
click node_enrich "https://github.com/777genius/claude-notifications-go/blob/main/internal/hooks/enricher.go"
click node_config "https://github.com/777genius/claude-notifications-go/tree/main/internal/config"
click node_policyeval "https://github.com/777genius/claude-notifications-go/tree/main/internal/notification"
click node_dedup "https://github.com/777genius/claude-notifications-go/blob/main/internal/dedup/dedup.go"
click node_journal "https://github.com/777genius/claude-notifications-go/tree/main/internal/agentnotify/journal"
click node_notify "https://github.com/777genius/claude-notifications-go/blob/main/internal/notifier/notifier.go"
click node_desktop "https://github.com/777genius/claude-notifications-go/tree/main/internal/notifier"
click node_focus "https://github.com/777genius/claude-notifications-go/tree/main/internal/notifier"
click node_daemon "https://github.com/777genius/claude-notifications-go/blob/main/internal/daemon/server.go"
click node_audio "https://github.com/777genius/claude-notifications-go/blob/main/internal/audio/audio.go"
click node_soundcatalog "https://github.com/777genius/claude-notifications-go/blob/main/internal/sounds/sounds.go"
click node_webhook "https://github.com/777genius/claude-notifications-go/tree/main/internal/webhook"
click node_setupwizard "https://github.com/777genius/claude-notifications-go/tree/main/internal/agentnotify/setupwizard"
click node_registration "https://github.com/777genius/claude-notifications-go/blob/main/internal/agentnotify/registration/registration.go"
click node_codexsetup "https://github.com/777genius/claude-notifications-go/tree/main/internal/codexsetup"
click node_installer "https://github.com/777genius/claude-notifications-go/tree/main/internal/installruntime"
click node_settingscli "https://github.com/777genius/claude-notifications-go/blob/main/cmd/claude-notifications/config_command.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_hookparse,node_codexmap toneBlue
class node_context,node_enrich,node_config,node_policyeval,node_dedup,node_journal toneAmber
class node_notify,node_desktop,node_focus,node_daemon,node_audio,node_soundcatalog,node_webhook,node_webhookservice toneMint
class node_setupwizard,node_registration,node_codexsetup,node_installer,node_settingscli toneRose
class node_claude,node_codex toneIndigo
```

## Components

### Event intake

- [Hook CLI](https://github.com/777genius/claude-notifications-go/blob/main/cmd/claude-notifications/main.go): `cmd/claude-notifications/main.go`
- [Hook mapping](https://github.com/777genius/claude-notifications-go/tree/main/internal/hooks): `internal/hooks`
- [Codex mapping](https://github.com/777genius/claude-notifications-go/blob/main/internal/codexsource/codexsource.go): `internal/codexsource/codexsource.go`

### Context and policy

- [Session context](https://github.com/777genius/claude-notifications-go/tree/main/internal/analyzer): `internal/analyzer`
- [Event enrichment](https://github.com/777genius/claude-notifications-go/blob/main/internal/hooks/enricher.go): `internal/hooks/enricher.go`
- [Effective settings](https://github.com/777genius/claude-notifications-go/tree/main/internal/config): `internal/config`
- [Delivery policy](https://github.com/777genius/claude-notifications-go/tree/main/internal/notification): `internal/notification`
- [Duplicate suppression](https://github.com/777genius/claude-notifications-go/blob/main/internal/dedup/dedup.go): `internal/dedup/dedup.go`
- [Event journal](https://github.com/777genius/claude-notifications-go/tree/main/internal/agentnotify/journal): `internal/agentnotify/journal`

### Alert delivery

- [Notification dispatcher](https://github.com/777genius/claude-notifications-go/blob/main/internal/notifier/notifier.go): `internal/notifier/notifier.go`
- [Desktop notifications](https://github.com/777genius/claude-notifications-go/tree/main/internal/notifier): `internal/notifier`
- [Focus targeting](https://github.com/777genius/claude-notifications-go/tree/main/internal/notifier): `internal/notifier`
- [Focus daemon](https://github.com/777genius/claude-notifications-go/blob/main/internal/daemon/server.go): `internal/daemon/server.go`
- [Sound playback](https://github.com/777genius/claude-notifications-go/blob/main/internal/audio/audio.go): `internal/audio/audio.go`
- [Sound catalog](https://github.com/777genius/claude-notifications-go/blob/main/internal/sounds/sounds.go): `internal/sounds/sounds.go`
- [Webhook delivery](https://github.com/777genius/claude-notifications-go/tree/main/internal/webhook): `internal/webhook`

### Setup and settings

- [Setup wizard](https://github.com/777genius/claude-notifications-go/tree/main/internal/agentnotify/setupwizard): `internal/agentnotify/setupwizard`
- [Agent registration](https://github.com/777genius/claude-notifications-go/blob/main/internal/agentnotify/registration/registration.go): `internal/agentnotify/registration/registration.go`
- [Codex setup](https://github.com/777genius/claude-notifications-go/tree/main/internal/codexsetup): `internal/codexsetup`
- [Runtime installer](https://github.com/777genius/claude-notifications-go/tree/main/internal/installruntime): `internal/installruntime`
- [Config commands](https://github.com/777genius/claude-notifications-go/blob/main/cmd/claude-notifications/config_command.go): `cmd/claude-notifications/config_command.go`

### Other components

- **Claude Code**
- **Codex CLI**
- **Webhook endpoints**

## Connections

- Claude Code → Hook CLI: invokes hooks
- Codex CLI → Hook CLI: invokes hooks
- Hook CLI → Hook mapping: routes Claude events
- Hook CLI → Codex mapping: maps Codex events
- Hook CLI → Session context: reads context
- Hook CLI → Event enrichment: enriches events
- Hook CLI → Effective settings: loads settings
- Hook CLI → Delivery policy: evaluates delivery
- Hook CLI → Duplicate suppression: suppresses repeats
- Hook CLI → Event journal: records state
- Hook CLI → Notification dispatcher: dispatches alerts
- Notification dispatcher → Desktop notifications: sends alerts
- Notification dispatcher → Sound playback: plays sound
- Notification dispatcher → Webhook delivery: sends webhooks
- Webhook delivery → Webhook endpoints: posts events
- Desktop notifications → Focus targeting: attaches target
- Focus daemon → Desktop notifications: sends alerts
- Focus daemon → Focus targeting: handles click
- Config commands → Effective settings: inspects settings
- Setup wizard → Agent registration: configures hooks
- Setup wizard → Effective settings: prepares settings
- Codex setup → Agent registration: registers Codex
- Runtime installer → Hook CLI: installs runtime
- Sound catalog → Sound playback: selects sounds