# mmeookamy/herdr-always-need-cats architecture

> Architecture diagram of the GitHub repository mmeookamy/herdr-always-need-cats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mmeookamy/herdr-always-need-cats
- Repository: https://github.com/mmeookamy/herdr-always-need-cats

## Overview

This repository adds pixel-art cat features to the Herdr desktop app, with Claude Code usage and agent state driving sidebar, notification, pane-header, and animated-strip experiences. Users can also browse, resume, and delete saved Claude sessions. The graph includes the documented hooks, usage status line, update check, and sprite-generation capability. Some runtime modules and integrations are unsampled; their links are included only where the README or excerpts establish them.

Main entry points: [`strip-cats/main.js`](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/strip-cats/main.js) (Walking cat strip), [`tools/make_sprites.py`](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/tools/make_sprites.py) (Sprite generator), [`usage-cat/main.js`](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/usage-cat/main.js) (Usage cat), [`claude-sessions/main.js`](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/claude-sessions/main.js) (Session browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_usage["Usage and updates"]
  node_usage_ui["Usage cat<br/>[main.js]"]
  node_statusline["Usage status line<br/>[statusline.py]"]
  node_usage_state[("Usage state file")]
  node_updates["Update checker<br/>[updates.py]"]
  node_update_state[("Update state")]
end

subgraph group_agents["Agent experiences"]
  node_agents_ui["Agent list cats<br/>[main.js]"]
  node_strip["Walking cat strip<br/>[main.js]"]
  node_hooks["Claude event hooks<br/>[hook.py]"]
  node_toast["Cat notifications<br/>[main.js]"]
  node_pane["Cat pane headers<br/>[main.js]"]
end

subgraph group_sessions["Session browser"]
  node_footer["Sessions shortcut<br/>[main.js]"]
  node_session_ui["Session browser<br/>[main.js]"]
  node_session_reader["Session reader<br/>[sessions.py]"]
  node_session_files[("Claude session files")]
  node_session_cache[("Session cache")]
end

subgraph group_artwork["Cat artwork"]
  node_drawings["Cat drawings<br/>[drawings.py]"]
  node_sprite_generator["Sprite generator<br/>[make_sprites.py]"]
end

node_user(("Herdr user"))
node_herdr["Herdr app"]
node_claude["Claude Code"]

node_user -->|"uses"| node_herdr
node_herdr -->|"renders"| node_usage_ui
node_claude -->|"provides status"| node_statusline
node_statusline -->|"writes"| node_usage_state
node_usage_ui -->|"polls"| node_usage_state
node_usage_ui -->|"runs checks"| node_updates
node_updates -->|"writes"| node_update_state
node_usage_ui -->|"reads"| node_update_state
node_herdr -->|"renders"| node_agents_ui
node_herdr -->|"renders"| node_strip
node_claude -->|"dispatches events"| node_hooks
node_hooks -->|"supplies agent activity"| node_strip
node_herdr -->|"renders notifications"| node_toast
node_herdr -->|"renders headers"| node_pane
node_strip -->|"shares status"| node_pane
node_strip -->|"shares coat choice"| node_agents_ui
node_strip -->|"shares coat choice"| node_toast
node_user -->|"opens sessions"| node_footer
node_footer -->|"opens"| node_session_ui
node_user -->|"filters and selects"| node_session_ui
node_session_ui -->|"runs"| node_session_reader
node_session_reader -->|"reads and deletes"| node_session_files
node_session_reader -->|"caches metadata"| node_session_cache
node_session_ui -->|"resumes or shows"| node_herdr
node_drawings -->|"supplies drawings"| node_sprite_generator
node_sprite_generator -->|"generates cat sprites"| node_agents_ui
node_sprite_generator -->|"generates cat sprites"| node_usage_ui
node_sprite_generator -->|"generates cat sprites"| node_toast
node_sprite_generator -.->|"generates cat sprites"| node_strip

click node_usage_ui "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/usage-cat/main.js"
click node_statusline "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/statusline.py"
click node_updates "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/updates.py"
click node_agents_ui "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/agents-cats/main.js"
click node_strip "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/strip-cats/main.js"
click node_hooks "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/hook.py"
click node_toast "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/toast-cats/main.js"
click node_pane "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/pane-cats/main.js"
click node_footer "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/sessions-footer/main.js"
click node_session_ui "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/claude-sessions/main.js"
click node_session_reader "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/claude-sessions/sessions.py"
click node_drawings "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/tools/drawings.py"
click node_sprite_generator "https://github.com/mmeookamy/herdr-always-need-cats/blob/main/tools/make_sprites.py"

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_usage_ui,node_statusline,node_usage_state,node_updates,node_update_state,node_user toneBlue
class node_agents_ui,node_strip,node_hooks,node_toast,node_pane toneAmber
class node_footer,node_session_ui,node_session_reader,node_session_files,node_session_cache toneMint
class node_drawings,node_sprite_generator toneRose
class node_herdr,node_claude toneIndigo
```

## Components

### Usage and updates

- [Usage cat](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/usage-cat/main.js): `usage-cat/main.js`
- [Usage status line](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/statusline.py): `statusline.py`
- **Usage state file**
- [Update checker](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/updates.py): `updates.py`
- **Update state**

### Agent experiences

- [Agent list cats](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/agents-cats/main.js): `agents-cats/main.js`
- [Walking cat strip](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/strip-cats/main.js): `strip-cats/main.js`
- [Claude event hooks](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/hook.py): `hook.py`
- [Cat notifications](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/toast-cats/main.js): `toast-cats/main.js`
- [Cat pane headers](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/pane-cats/main.js): `pane-cats/main.js`

### Session browser

- [Sessions shortcut](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/sessions-footer/main.js): `sessions-footer/main.js`
- [Session browser](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/claude-sessions/main.js): `claude-sessions/main.js`
- [Session reader](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/claude-sessions/sessions.py): `claude-sessions/sessions.py`
- **Claude session files**
- **Session cache**

### Cat artwork

- [Cat drawings](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/tools/drawings.py): `tools/drawings.py`
- [Sprite generator](https://github.com/mmeookamy/herdr-always-need-cats/blob/main/tools/make_sprites.py): `tools/make_sprites.py`

### Other components

- **Herdr user**
- **Herdr app**
- **Claude Code**

## Connections

- Herdr user → Herdr app: uses (evidence: `README.md`)
- Herdr app → Usage cat: renders (evidence: `README.md`)
- Claude Code → Usage status line: provides status (evidence: `README.md`)
- Usage status line → Usage state file: writes (evidence: `README.md`)
- Usage cat → Usage state file: polls (evidence: `README.md`)
- Usage cat → Update checker: runs checks (evidence: `usage-cat/main.js`)
- Update checker → Update state: writes
- Usage cat → Update state: reads (evidence: `usage-cat/main.js`)
- Herdr app → Agent list cats: renders (evidence: `README.md`)
- Herdr app → Walking cat strip: renders (evidence: `README.md`)
- Claude Code → Claude event hooks: dispatches events (evidence: `README.md`)
- Claude event hooks → Walking cat strip: supplies agent activity (evidence: `README.md`)
- Herdr app → Cat notifications: renders notifications (evidence: `README.md`)
- Herdr app → Cat pane headers: renders headers (evidence: `README.md`)
- Walking cat strip → Cat pane headers: shares status (evidence: `pane-cats/main.js`)
- Walking cat strip → Agent list cats: shares coat choice (evidence: `README.md`)
- Walking cat strip → Cat notifications: shares coat choice (evidence: `README.md`)
- Herdr user → Sessions shortcut: opens sessions (evidence: `sessions-footer/main.js`)
- Sessions shortcut → Session browser: opens (evidence: `sessions-footer/main.js`)
- Herdr user → Session browser: filters and selects (evidence: `README.md`)
- Session browser → Session reader: runs (evidence: `claude-sessions/main.js`)
- Session reader → Claude session files: reads and deletes (evidence: `README.md`)
- Session reader → Session cache: caches metadata (evidence: `README.md`)
- Session browser → Herdr app: resumes or shows (evidence: `README.md`)
- Cat drawings → Sprite generator: supplies drawings (evidence: `tools/make_sprites.py`)
- Sprite generator → Agent list cats: generates cat sprites (evidence: `README.md`)
- Sprite generator → Usage cat: generates cat sprites (evidence: `README.md`)
- Sprite generator → Cat notifications: generates cat sprites (evidence: `README.md`)
- Sprite generator → Walking cat strip: generates cat sprites
