# latent-spaces/cled architecture

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

- Interactive diagram: https://gitdiagram.com/latent-spaces/cled
- Repository: https://github.com/latent-spaces/cled

## Overview

CLED is an ambient keyboard status daemon: it samples agent-tab state and machine load, maps them to key colors, and continually sends frames to an OpenRGB-controlled keyboard. The main runtime starts the tab monitor and owns the render loop; provider-specific logic distinguishes Claude and Codex sessions. The README also documents a Claude Code plugin launcher. Unsampled plugin implementation is represented only at its existing directory path; external state sources and services are shown where documented, without inferring internal calls beyond the excerpts.

Main entry points: [`src/cled/agent_tabs.py`](https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py) (Tab Monitor), [`src/cled/cled.py`](https://github.com/latent-spaces/cled/blob/main/src/cled/cled.py) (Daemon Runtime), [`plugin/skills/cled`](https://github.com/latent-spaces/cled/tree/main/plugin/skills/cled) (Plugin Launcher), [`src/cled/rgb.py`](https://github.com/latent-spaces/cled/blob/main/src/cled/rgb.py) (RGB Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_state["Agent State"]
  node_tab_monitor["Tab Monitor<br/>[agent_tabs.py]"]
  node_tab_detection["Tab Detection<br/>[agent_tabs.py]"]
  node_claude_provider["Claude Status<br/>[agent_tabs.py]"]
  node_codex_provider["Codex Status<br/>[agent_tabs.py]"]
end

subgraph group_daemon["Daemon"]
  node_plugin_launcher["Plugin Launcher"]
  node_runtime["Daemon Runtime<br/>[cled.py]"]
end

subgraph group_rendering["Rendering"]
  node_frame_composer["Frame Composer<br/>[cled.py]"]
  node_rgb_tools["RGB Mapping<br/>[rgb.py]"]
end

subgraph group_hardware["Keyboard Output"]
  node_rgb_session["RGB Session<br/>[rgb.py]"]
end

node_terminal_user(("Terminal User"))
node_claude_user(("Claude Code User"))
node_iterm["iTerm2 / macOS"]
node_claude_state["Claude Session Files"]
node_codex_state[("Codex State")]
node_system_metrics["System Metrics"]
node_openrgb["OpenRGB Server"]
node_keyboard["RGB Keyboard"]

node_terminal_user -->|"starts"| node_runtime
node_claude_user -->|"invokes"| node_plugin_launcher
node_plugin_launcher -->|"launches"| node_runtime
node_runtime -->|"starts"| node_tab_monitor
node_tab_monitor -->|"polls tabs"| node_tab_detection
node_tab_monitor -->|"checks status"| node_claude_provider
node_tab_monitor -->|"checks status"| node_codex_provider
node_tab_detection -->|"queries tabs"| node_iterm
node_claude_provider -->|"reads session"| node_claude_state
node_codex_provider -->|"resolves rollouts"| node_codex_state
node_runtime -->|"runs renderer"| node_frame_composer
node_frame_composer -->|"reads slots"| node_tab_monitor
node_frame_composer -->|"samples CPU/RAM"| node_system_metrics
node_frame_composer -->|"builds frame"| node_rgb_tools
node_runtime -->|"runs render loop"| node_rgb_session
node_rgb_session -->|"sets LED colors"| node_openrgb
node_openrgb -->|"controls"| node_keyboard

click node_plugin_launcher "https://github.com/latent-spaces/cled/tree/main/plugin/skills/cled"
click node_runtime "https://github.com/latent-spaces/cled/blob/main/src/cled/cled.py"
click node_tab_monitor "https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py"
click node_tab_detection "https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py"
click node_claude_provider "https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py"
click node_codex_provider "https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py"
click node_frame_composer "https://github.com/latent-spaces/cled/blob/main/src/cled/cled.py"
click node_rgb_tools "https://github.com/latent-spaces/cled/blob/main/src/cled/rgb.py"
click node_rgb_session "https://github.com/latent-spaces/cled/blob/main/src/cled/rgb.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_tab_monitor,node_tab_detection,node_claude_provider,node_codex_provider,node_terminal_user,node_claude_user toneBlue
class node_plugin_launcher,node_runtime,node_codex_state toneAmber
class node_frame_composer,node_rgb_tools,node_openrgb toneMint
class node_rgb_session toneRose
class node_iterm,node_claude_state,node_system_metrics,node_keyboard toneIndigo
```

## Components

### Agent State

- [Tab Monitor](https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py): `src/cled/agent_tabs.py`
- [Tab Detection](https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py): `src/cled/agent_tabs.py`
- [Claude Status](https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py): `src/cled/agent_tabs.py`
- [Codex Status](https://github.com/latent-spaces/cled/blob/main/src/cled/agent_tabs.py): `src/cled/agent_tabs.py`

### Daemon

- [Plugin Launcher](https://github.com/latent-spaces/cled/tree/main/plugin/skills/cled): `plugin/skills/cled`
- [Daemon Runtime](https://github.com/latent-spaces/cled/blob/main/src/cled/cled.py): `src/cled/cled.py`

### Rendering

- [Frame Composer](https://github.com/latent-spaces/cled/blob/main/src/cled/cled.py): `src/cled/cled.py`
- [RGB Mapping](https://github.com/latent-spaces/cled/blob/main/src/cled/rgb.py): `src/cled/rgb.py`

### Keyboard Output

- [RGB Session](https://github.com/latent-spaces/cled/blob/main/src/cled/rgb.py): `src/cled/rgb.py`

### Other components

- **Terminal User**
- **Claude Code User**
- **iTerm2 / macOS**
- **Claude Session Files**
- **Codex State**
- **System Metrics**
- **OpenRGB Server**
- **RGB Keyboard**

## Connections

- Terminal User → Daemon Runtime: starts (evidence: `README.md`)
- Claude Code User → Plugin Launcher: invokes (evidence: `README.md`)
- Plugin Launcher → Daemon Runtime: launches (evidence: `README.md`)
- Daemon Runtime → Tab Monitor: starts (evidence: `src/cled/cled.py`)
- Tab Monitor → Tab Detection: polls tabs (evidence: `src/cled/agent_tabs.py`)
- Tab Monitor → Claude Status: checks status (evidence: `src/cled/agent_tabs.py`)
- Tab Monitor → Codex Status: checks status (evidence: `src/cled/agent_tabs.py`)
- Tab Detection → iTerm2 / macOS: queries tabs (evidence: `src/cled/agent_tabs.py`)
- Claude Status → Claude Session Files: reads session (evidence: `src/cled/agent_tabs.py`)
- Codex Status → Codex State: resolves rollouts (evidence: `src/cled/agent_tabs.py`)
- Daemon Runtime → Frame Composer: runs renderer (evidence: `src/cled/cled.py`)
- Frame Composer → Tab Monitor: reads slots (evidence: `src/cled/cled.py`)
- Frame Composer → System Metrics: samples CPU/RAM (evidence: `src/cled/cled.py`)
- Frame Composer → RGB Mapping: builds frame (evidence: `src/cled/cled.py`)
- Daemon Runtime → RGB Session: runs render loop (evidence: `src/cled/cled.py`)
- RGB Session → OpenRGB Server: sets LED colors (evidence: `README.md`)
- OpenRGB Server → RGB Keyboard: controls (evidence: `README.md`)