Descripción Detallada del Proyecto Claude Code UI

Resumen del Proyecto

Claude Code UI es una interfaz de usuario de código abierto, amigable para web y dispositivos móviles, diseñada específicamente para la CLI oficial de Claude Code de Anthropic. Este proyecto permite a los usuarios ver y gestionar todas las sesiones y proyectos de Claude Code, tanto local como remotamente, de la misma manera que lo harían con la CLI. Esto proporciona a los usuarios una interfaz completa que funciona en cualquier lugar.

Características del Proyecto

🎨 Diseño Responsivo

• Compatibilidad multiplataforma: Soporte fluido para dispositivos de escritorio, tabletas y móviles.
• Diseño adaptable: Barra lateral plegable y priorización inteligente del contenido.
• Táctil: Gestos de deslizamiento y navegación táctil.
• Navegación móvil: Barra de pestañas inferior para facilitar el uso con el pulgar.

💬 Interfaz de Chat Interactiva

• Chat integrado: Interfaz de chat incorporada para una comunicación fluida con Claude Code.
• Comunicación en tiempo real: Transmisión de las respuestas de Claude a través de conexiones WebSocket.
• Gestión de sesiones: Reanudar conversaciones anteriores o iniciar nuevas sesiones.
• Historial de mensajes: Historial completo de conversaciones, incluyendo marcas de tiempo y metadatos.
• Soporte multiformato: Texto, bloques de código y referencias de archivos.

🖥️ Funcionalidad de Terminal Integrada

• Acceso directo a la CLI: Acceso directo a la CLI de Claude Code a través de la funcionalidad de shell integrada.
• Gestión de procesos: Generación y gestión de procesos integradas con la CLI de Claude.
• Ejecución de comandos: Soporte para todos los comandos de la CLI de Claude Code.

📁 Explorador de Archivos

• Árbol de archivos interactivo: Árbol de archivos interactivo con resaltado de sintaxis y edición en tiempo real.
• Edición de archivos en tiempo real: Leer, modificar y guardar archivos directamente en la interfaz.
• Resaltado de sintaxis: Soporte para múltiples lenguajes de programación.
• Operaciones de archivos: Crear, renombrar, eliminar archivos y directorios.

💾 Persistencia de Sesiones

• Guardado automático: Todas las conversaciones se guardan automáticamente.
• Organización de sesiones: Sesiones agrupadas por proyecto y marca de tiempo.
• Operaciones de sesión: Renombrar, eliminar y exportar el historial de conversaciones.
• Sincronización entre dispositivos: Acceso a las sesiones desde cualquier dispositivo.

Arquitectura Técnica

Diagrama de Arquitectura del Sistema

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Claude CLI │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Pila Tecnológica del Backend

• Servidor Express: Proporciona API RESTful y sirve archivos estáticos.
• Servidor WebSocket: Utilizado para la comunicación de chat y la actualización de proyectos.
• Integración con la CLI de Claude: Generación y gestión de procesos.
• Gestión de sesiones: Análisis de JSONL y persistencia de conversaciones.
• API del sistema de archivos: Proporciona un explorador de archivos para los proyectos.

Pila Tecnológica del Frontend

• React 18: Arquitectura de componentes moderna, utilizando Hooks.
• CodeMirror: Editor de código avanzado con resaltado de sintaxis.
• Vite: Herramienta de construcción rápida y servidor de desarrollo.
• Tailwind CSS: Framework CSS utilitario.

Instalación y Configuración

Requisitos del Sistema

• Node.js v16 o superior.
• Claude Code CLI instalado y configurado.

Pasos de Instalación

1. Clonar el repositorio:

   git clone https://github.com/siteboon/claudecodeui.git
   cd claudecodeui
   

2. Instalar dependencias:

   npm install
   

3. Configurar el entorno:

   cp .env.example .env
   # Edite el archivo .env según sea necesario
   

4. Iniciar la aplicación:

   # Modo desarrollo (con recarga en caliente)
   npm run dev
   

5. Abrir el navegador:

   • Entorno de desarrollo: http://localhost:3001

Configuración de Seguridad

🔒 Aviso de Seguridad Importante

Todas las herramientas de Claude Code están deshabilitadas por defecto. Esto evita que operaciones potencialmente dañinas se ejecuten automáticamente.

Para utilizar la funcionalidad completa de Claude Code, debe habilitar las herramientas manualmente:

1. Abrir la configuración de herramientas: Haga clic en el icono de engranaje en la barra lateral.
2. Habilitación selectiva: Active solo las herramientas que necesite.
3. Aplicar configuración: Sus preferencias se guardarán localmente.

Método recomendado: Comience habilitando las herramientas básicas y añada más funcionalidades según sea necesario.

Funcionalidades Principales

Gestión de Proyectos

• Descubrimiento automático de proyectos: La UI descubre automáticamente los proyectos de Claude Code desde ~/.claude/projects/.
• Explorador de proyectos visual: Muestra todos los proyectos disponibles con sus metadatos y número de sesiones.
• Operaciones de proyecto: Renombrar, eliminar y organizar proyectos.
• Navegación inteligente: Acceso rápido a proyectos y sesiones recientes.

Gestión de Archivos

• Exploración de la estructura del proyecto: Con funcionalidad de navegación expandir/colapsar.
• Edición en tiempo real: Modificar archivos directamente en la interfaz.
• Operaciones de archivos: Funcionalidad completa de gestión de archivos y directorios.

Gestión de Sesiones

• Almacenamiento persistente: Todas las sesiones se guardan automáticamente.
• Historial: Seguimiento completo del historial de conversaciones.
• Soporte multisecuencia: Gestionar múltiples sesiones de proyecto simultáneamente.

Solución de Problemas

Problema Común 1: La UI no muestra proyectos o la lista de proyectos está vacía

Solución:

• Asegúrese de que Claude CLI esté correctamente instalado.
• Ejecute el comando claude en al menos un directorio de proyecto para inicializarlo.
• Verifique que el directorio ~/.claude/projects/ exista y tenga los permisos adecuados.

Problema Común 2: Archivos no cargados, errores de permisos, directorio vacío

Solución:

• Verifique los permisos del directorio del proyecto (use ls -la en la terminal).
• Verifique que la ruta del proyecto exista y sea accesible.
• Consulte los registros de la consola del servidor para obtener información detallada sobre errores.
• Asegúrese de no intentar acceder a directorios del sistema fuera del alcance del proyecto.