█████
   █ █ █   Claude LCD — Estado de Claude Code en tiempo real
   █████   ─────────────────────────────────────────────────────────
  ███████  Hardware : Waveshare RP2350-LCD-1.47 (RP2350, 320×172 px)
   █████   Firmware : MicroPython 1.27
    █ █    Autor   : github.com/686f6c61
    █ █    Repo    : github.com/686f6c61/Claude-RP2350-LCD
           ─────────────────────────────────────────────────────────
           Licencia MIT — libre de usar, modificar y redistribuir.

Claude LCD

Muestra el estado de tu sesión de Claude Code en tiempo real sobre una pantalla LCD externa conectada por USB. La placa actúa como un indicador permanente: de un vistazo sabes si Claude está pensando, ejecutando una herramienta, esperando tu respuesta o pidiendo una elección.

El sistema tiene dos partes independientes que se comunican por puerto serie USB:

• Firmware (Pico) — recibe comandos JSON y renderiza la interfaz en pantalla.
• Daemon (Mac) — escucha los hooks de Claude Code, mantiene la cola de sesiones activas y envía el estado al Pico.

Hardware necesario

La Waveshare RP2350-LCD-1.47 integra en una sola placa el microcontrolador RP2350 (Pico 2), un panel IPS de 320×172 px (ST7789V3), un LED RGB WS2812B y un conector USB-C. No es necesario ningún cableado adicional.

Instalación rápida

1. Preparar el Pico

Instala MicroPython 1.27 en la placa. Descarga el fichero .uf2 para RPI_PICO2 desde micropython.org, mantén pulsado el botón BOOTSEL al conectar el USB y cópialo a la unidad que aparece.

2. Instalar el sistema

Con la placa conectada y visible como /dev/cu.usbmodem*, ejecuta:

bash ~/Desktop/Claude-LCD/install-mac/install.sh

El script hace todo lo necesario de forma automática:

• Verifica que Python 3 esté instalado (sale con error si no lo está)
• Instala pyserial y mpremote si no están presentes
• Copia daemon.py y notify.py a ~/.claude-lcd/
• Registra el daemon como LaunchAgent (arranca al iniciar sesión y se reinicia si falla)
• Inyecta los hooks de Claude Code en ~/.claude/settings.json (sin duplicar si ya existen)
• Sube el firmware al Pico por mpremote
• Reinicia la placa

Si la placa no está conectada al ejecutar el instalador, el script avisa pero continúa con el resto de pasos. Puedes subir el firmware después con:

bash ~/Desktop/Claude-LCD/install-mac/install.sh /dev/cu.usbmodem1101

Si el Pico está en un puerto distinto al predeterminado:

bash ~/Desktop/Claude-LCD/install-mac/install.sh /dev/cu.usbmodem1201

3. Verificar

# Ver logs del daemon en tiempo real
tail -f ~/.claude-lcd/daemon.log

# Estado del LaunchAgent
launchctl list | grep claude-lcd

Al iniciar una sesión de Claude Code el LCD debe mostrar inmediatamente el estado correspondiente.

Estados y su significado

La pantalla se divide en dos zonas: la mascota animada (Clawde) a la izquierda y el estado actual a la derecha. Debajo del estado aparece el nombre del proyecto en verde y, en gris, el modelo de Claude utilizado (p.ej. sonnet-4-6).

La prioridad de estados cuando hay varias sesiones en paralelo es:
approval > question > waiting > working > thinking > idle

Flujo de datos

Usuario envía mensaje
        │
        ▼
  [hook UserPromptSubmit]
        │  notify.py → "thinking"
        ▼
     daemon.py
        │  SessionQueue actualiza prioridad
        ▼
  SerialManager.send()
        │  JSON por USB 115200
        ▼
     Pico / main.py
        │  _process() → ClaudeDisplay.update_status()
        ▼
      LCD + LED

Los hooks de Claude Code invocan notify.py en menos de 50 ms para no añadir latencia visible. El daemon gestiona la cola de sesiones y solo envía al Pico cuando el estado cambia, evitando tráfico serie innecesario. Las sesiones persisten indefinidamente: el LCD mantiene el último estado hasta recibir un nuevo evento.

Estructura del proyecto

Claude-LCD/
├── pico/
│   ├── main.py       Punto de entrada; bucles asyncio serie + animación
│   ├── display.py    Driver ST7789, ClaudeDisplay, AnswerDisplay
│   ├── mascot.py     Sprite animado de Clawde (pixel-art 7×7)
│   ├── led.py        Control del LED WS2812B integrado
│   └── config.py     Pines GPIO, dimensiones, paleta de colores
│
├── install-mac/
│   ├── daemon.py     Daemon principal: socket Unix + cola + serie
│   ├── notify.py     Cliente de hook; se ejecuta desde Claude Code
│   ├── install.sh    Instalador automático
│   └── com.claude-lcd.daemon.plist   LaunchAgent para macOS
│
└── tests/
    ├── test_daemon.py   Tests unitarios del daemon (SessionQueue, build_serial_cmd…)
    └── test_notify.py   Tests unitarios de notify (_build_message, _stop_event…)

Protocolo serie

Todos los mensajes son líneas JSON terminadas en \n a 115200 baudios. El Pico responde con {"status": "ok"} o {"status": "error", "msg": "..."}.

Comando principal:

{"cmd": "claude_status", "type": "thinking", "sessions": 2, "project": "Claude-LCD"}

Los campos sessions, project, tool y model son opcionales y se omiten cuando no tienen valor.

Comandos de diagnóstico:

{"cmd": "ping"}
{"cmd": "clear"}

Instalación manual de hooks

Si prefieres configurar los hooks sin el instalador, añade esto a ~/.claude/settings.json:

"hooks": {
  "UserPromptSubmit": [{"hooks": [{"type": "command",
      "command": "python3 ~/.claude-lcd/notify.py promptsubmit"}]}],
  "Stop": [{"hooks": [{"type": "command",
      "command": "python3 ~/.claude-lcd/notify.py stop"}]}],
  "PreToolUse": [
    {"matcher": "AskUserQuestion", "hooks": [{"type": "command",
        "command": "python3 ~/.claude-lcd/notify.py pretool"}]},
    {"matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit", "hooks": [{"type": "command",
        "command": "python3 ~/.claude-lcd/notify.py pretool"}]}
  ],
  "PostToolUse": [{"hooks": [{"type": "command",
      "command": "python3 ~/.claude-lcd/notify.py posttool"}]}]
}

Depuración

El daemon no arranca:

python3 ~/.claude-lcd/daemon.py

Ejecutarlo directamente muestra los errores en la terminal. Revisa que pyserial esté instalado (pip3 install pyserial).

El Pico no responde / no se detecta el puerto:

ls /dev/cu.usbmodem*

Si no aparece ningún puerto, reconecta el cable. Si aparece pero el daemon no lo detecta, reinicia el daemon:

launchctl stop com.claude-lcd.daemon
launchctl start com.claude-lcd.daemon

Probar notify.py manualmente:

echo '{"session_id":"test","transcript_path":""}' | python3 ~/.claude-lcd/notify.py promptsubmit

Ejecutar los tests:

cd ~/Desktop/Claude-LCD
python3 -m pytest tests/ -v

Actualizar el firmware del Pico

python3 -m mpremote connect /dev/cu.usbmodem* cp pico/*.py :
python3 -m mpremote connect /dev/cu.usbmodem* reset

Licencia

MIT — libre de usar, modificar y redistribuir.