README

claudeLauncher

Gestor visual de proyectos con integración de Claude Code. Permite organizar, buscar y abrir rápidamente proyectos en Claude Code con un sistema de contexto multi-nivel.

💡 Concepto: Sistema de Contexto Multi-Nivel para Claude Code

El Problema

Como programador trabajas con múltiples proyectos interconectados: clientes, frameworks, librerías, laboratorios, documentación... Cada vez que abres Claude Code en un proyecto, Claude necesita contexto sobre:

• ¿Qué es este proyecto?
• ¿Qué tecnologías usa?
• ¿Cómo se relaciona con otros proyectos?
• ¿Cuál es la estructura del entorno de desarrollo completo?

Sin este contexto, Claude trabaja "a ciegas" y tienes que explicarle una y otra vez la misma información básica.

La Solución: Arquitectura de 3 Niveles

Este sistema implementa una jerarquía de contexto para Claude Code:

???? Tu Ordenador
?????? ???? CLAUDE.md Global ??? Nivel 1: Contexto del Entorno Completo
???  ?????? Inventario de TODOS los proyectos
???     Frameworks compartidos
???     Convenciones del entorno
???     Estructura de carpetas
???     Herramientas instaladas
???
?????? ???? Proyecto 1
???  ?????? ???? CLAUDE.md ??? Nivel 2: Contexto del Proyecto Espec??fico
???     ?????? Arquitectura del proyecto
???        Dependencias con otros proyectos
???        Convenciones espec??ficas
???        ?????? Referencia al CLAUDE Global
???
?????? ???? Proyecto 2
???  ?????? ???? CLAUDE.md ??? Nivel 2: Contexto del Proyecto Espec??fico
???
?????? ???? claudeLauncher ??? Nivel 3: Gestor Visual
   ?????? Escanea todos los proyectos
      Abre Claude Code donde necesites
      Crea CLAUDE.md desde plantilla
      Gestiona el inventario completo

¿Cómo Funciona?

1️⃣ CLAUDE Global (Nivel 1)

Un archivo CLAUDE.md en una ubicación central (ej: C:\CodingDocs\CLAUDE-GLOBAL\CLAUDE.md) que contiene:

# Entorno de Desarrollo Global

## Estructura
- C:\Projects\ - Proyectos de producción (clientes)
- C:\Labs\ - Laboratorios y desarrollo experimental
- C:\Shared\Libraries\ - Frameworks y librerías compartidas

## Frameworks
- MiFramework (tu stack principal) - Usado en TODOS los proyectos
- React/Node - Para proyectos web
- ...

## Inventario de Proyectos
1. Cliente-A - Aplicación de gestión (Stack principal + Base de datos)
2. Cliente-B - Sistema de asambleas (Full-stack)
3. MiFramework - Framework principal
4. Lab-IA - Experimentos con IA
...

Propósito: Claude entiende el contexto global de tu entorno de desarrollo.

2️⃣ CLAUDE.md por Proyecto (Nivel 2)

Cada proyecto tiene su propio CLAUDE.md con información específica:

# CLAUDE.md - Proyecto Cliente-A

⬆️ IMPORTANTE: Este proyecto forma parte del entorno global.
   Lee también: C:\CodingDocs\CLAUDE-GLOBAL\CLAUDE.md

## Descripción
Aplicación de gestión empresarial...

## Dependencias
- MiFramework (ver CLAUDE Global)
- PostgreSQL / SQL Server
- Librerías compartidas

## Arquitectura
- Backend: API REST
- Frontend: React/Vue/Angular
- Database: ORM + migrations
...

Propósito: Claude entiende el contexto específico del proyecto actual + referencia al contexto global.

3️⃣ claudeLauncher (Nivel 3)

Una aplicación visual que:

• Escanea automáticamente todos tus proyectos
• Detecta qué proyectos tienen CLAUDE.md
• Abre Claude Code directamente en cualquier proyecto
• Gestiona el inventario completo de proyectos
• Crea archivos CLAUDE.md desde plantilla
• Organiza proyectos por tipo, tags, favoritos

Propósito: Es el punto de entrada unificado para trabajar con Claude Code en tu entorno.

Flujo de Trabajo Típico

1. Abres claudeLauncher.exe
   ???
2. Ves todos tus proyectos organizados
   ???
3. Doble clic en "Cliente-A"
   ???
4. Se abre Claude Code en C:\Projects\Cliente-A
   ???
5. Claude lee autom??ticamente:
   - ??? CLAUDE.md del proyecto (contexto espec??fico)
   - ??? CLAUDE Global referenciado (contexto global)
   ???
6. Claude ya sabe:
   - Qu?? es este proyecto
   - Qu?? frameworks usa (MiFramework)
   - C??mo se estructura el c??digo
   - Qu?? otros proyectos existen
   - Convenciones del entorno

Ventajas del Sistema

✅ Contexto Completo: Claude siempre tiene información del proyecto Y del entorno global

✅ No Repetir Información: Defines una vez en CLAUDE Global, referencias desde cada proyecto

✅ Navegación Rápida: Un clic para abrir cualquier proyecto en Claude Code

✅ Gestión Centralizada: Un solo lugar para ver y gestionar todos tus proyectos

✅ Autodetección: Escanea automáticamente nuevos proyectos

✅ Portable: Otros programadores pueden usar el mismo sistema con su configuración

Ejemplo Real

Imagina que tienes:

• 5 proyectos de clientes (tu stack principal)
• 1 framework compartido propio
• 4 laboratorios experimentales (Python, JavaScript, etc.)
• 1 blog o documentación personal

Sin este sistema:

• Abres cada proyecto manualmente
• Claude no sabe qué es tu framework personalizado
• Repites constantemente "este proyecto usa X, Y, Z..."
• No tienes visión global

Con este sistema:

• claudeLauncher muestra los 11 proyectos
• CLAUDE Global explica tu framework una vez
• Cada proyecto referencia al Global
• Claude siempre tiene contexto completo
• Navegación instantánea entre proyectos

Para Quién Es Este Sistema

✅ Programadores que trabajan con múltiples proyectos ✅ Equipos que comparten frameworks/librerías ✅ Desarrolladores que usan Claude Code intensivamente ✅ Entornos con proyectos interconectados

🚀 Características

• Búsqueda y filtrado de proyectos por nombre, tipo o tags
• Integración con Claude Code - Abre proyectos directamente en Claude Code
• Sistema de favoritos ⭐ - Marca tus proyectos más usados
• Escaneo automático 🔎 - Detecta proyectos automáticamente buscando archivos CLAUDE.md
• Información Git 🌿 - Muestra el branch actual de cada proyecto
• Gestión de CLAUDE.md - Crea archivos CLAUDE.md desde plantilla
• Multi-directorio - Escanea múltiples carpetas base
• Configurable - Archivo config.json para personalización

📋 Requisitos

• Delphi 12 Athens (o superior)
• Claude Code CLI instalado (npm install -g @anthropic/claude-code-cli)
• Windows 10/11

🔧 Instalación

1. Clonar o copiar este directorio
2. Copiar configuración de ejemplo:
   cmdCopy

   copy config.example.json config.json

3. Editar config.json con tus rutas:
   jsonCopy

   {
     "baseDirs": [
       "C:\\tu\\carpeta\\proyectos",
       "C:\\otra\\carpeta"
     ],
     "projectsFile": "projects.json",
     "claudeGlobalPath": "C:\\ruta\\a\\DOC-CLAUDE",
     "claudeTemplatePath": "C:\\ruta\\a\\PLANTILLA-CLAUDE-MD.md",
     "claudeCommand": "",
     "autoDetectClaudeCommand": true,
     "windowTitle": "Claude Launcher",
     "version": "1.0"
   }

4. Compilar con Delphi:
   • Abrir claudeLauncher.dproj
   • Build → Compile

⚙️ Configuración

config.json

Detección automática de proyectos

El escaneo automático detecta proyectos por:

Tipo de proyecto (según nombre - configurable):

• Prefijo cliente (ej: CLI-*, Client-*) → Cliente
• Contiene LIB, Framework → Framework
• Prefijo docs (ej: DOC-*, Docs-*) → Documentación
• Prefijo lab (ej: dev-*, Lab-*) → Laboratorio
• Contiene TOOL → Herramienta

Tecnología (según archivos):

• package.json → nodejs, npm
• composer.json → php, laravel
• requirements.txt → python
• *.dpr → delphi

🎯 Uso

Primera vez

1. Ejecutar claudeLauncher.exe
2. Click en "🔎 Reescanear" para detectar proyectos automáticamente
3. Los proyectos se guardan en projects.json

Operaciones

Filtros

• Todos: Muestra todos los proyectos
• ⭐ Favoritos: Solo proyectos marcados como favoritos
• Por tipo: Clientes, Frameworks, Documentación, Laboratorios, Herramientas
• Búsqueda: Por nombre, descripción o tags

Gestión de Proyectos

Quitar proyectos de la lista

La funcionalidad "🗑️ Quitar Proyecto" permite eliminar proyectos de la lista de gestión:

Características importantes:

• ✅ NO borra archivos del disco - Solo quita el proyecto del sistema de gestión
• 🔒 Exclusión permanente - El proyecto se añade a excludedProjects en config.json
• 🚫 No reaparece en escaneos - Los escaneos futuros ignorarán el proyecto automáticamente
• 🔄 Reversible manualmente - Puedes editar config.json para quitar la exclusión si lo necesitas

Casos de uso:

• Proyectos obsoletos que ya no usas
• Directorios que fueron detectados por error
• Proyectos que prefieres gestionar manualmente
• Reducir ruido en la lista de proyectos

Cómo funciona:

1. Selecciona el proyecto que deseas quitar
2. Click en "🗑️ Quitar Proyecto"
3. Confirma la acción en el diálogo
4. El proyecto desaparece de la lista
5. Su ruta se añade a excludedProjects en config.json
6. En futuros escaneos, ese directorio será ignorado automáticamente

📁 Estructura de archivos

claudeLauncher/
????????? claudeLauncher.dpr        # Proyecto principal
????????? claudeLauncher.dproj      # Archivo de proyecto Delphi
????????? FRM.Main.pas/dfm         # Formulario principal
????????? Model.Project.pas        # Modelo de datos y manager
????????? Config.pas               # Gestor de configuraci??n
????????? config.json             # Tu configuraci??n (NO compartir)
????????? config.example.json     # Plantilla de configuraci??n
????????? projects.json          # Base de datos de proyectos (NO compartir)
????????? projects.example.json  # Plantilla de projects.json
????????? README.md             # Este archivo
????????? .gitignore           # Excluye archivos personales

🔒 Compartir con otros

Si quieres compartir este proyecto:

1. NO incluyas: config.json, projects.json (son personales)
2. SÍ incluye: config.example.json, projects.example.json, código fuente, README.md, .gitignore
3. Los demás deberán:
   • Copiar config.example.json a config.json
   • Editar config.json con sus rutas
   • Ejecutar y hacer clic en "Reescanear" para generar su projects.json

🐛 Solución de problemas

"No se encuentra claude.cmd"

• Verifica que Claude Code CLI está instalado: npm install -g @anthropic/claude-code-cli
• O configura la ruta manualmente en config.json:
  jsonCopy

  "claudeCommand": "C:\\ruta\\completa\\a\\claude.cmd",
  "autoDetectClaudeCommand": false

"No se detectan proyectos"

• Verifica que las rutas en baseDirs existen
• Haz clic en "Reescanear" para buscar proyectos
• Revisa los permisos de lectura de las carpetas

"Error al crear CLAUDE.md"

• Verifica que claudeTemplatePath apunta a un archivo válido
• Asegúrate de tener permisos de escritura en el proyecto

"Caracteres extraños" (ñ, á, é, etc.)

• Asegúrate de que los archivos .pas estén guardados como UTF-8 con BOM en Delphi
• El projects.json se guarda automáticamente como UTF-8

📝 Archivo projects.json

Los proyectos se almacenan en formato JSON:

{
  "projects": [
    {
      "name": "Cliente-A",
      "path": "C:\\Projects\\Cliente-A",
      "type": "Cliente",
      "description": "Sistema de gestión empresarial - Full-stack",
      "hasClaude": true,
      "claudePath": "C:\\Projects\\Cliente-A\\CLAUDE.md",
      "isActive": true,
      "location": "Projects",
      "isFavorite": true,
      "tags": ["web", "backend", "frontend", "activo"]
    }
  ]
}

Campos

• name: Nombre del proyecto
• path: Ruta completa al directorio
• type: Tipo (Cliente, Framework, Documentación, Laboratorio, Herramienta)
• description: Descripción breve del proyecto
• hasClaude: Indica si tiene archivo CLAUDE.md
• claudePath: Ruta al archivo CLAUDE.md (si existe)
• isActive: Si el proyecto está activo
• location: Nombre de la carpeta base (Projects, Labs, etc.)
• isFavorite: Si está marcado como favorito
• tags: Array de tags para búsqueda

🔧 Notas técnicas

Arquitectura

• Config.pas: Singleton para gestión de configuración
• Model.Project.pas: Modelo de datos y TProjectManager (Singleton)
• FRM.Main.pas: Interfaz visual

Patrones de diseño

• Singleton: TAppConfig, TProjectManager
• MVC: Separación entre modelo, vista y lógica

Detección de Git

• Lee directamente .git/HEAD para obtener el branch
• No ejecuta comandos git externos
• Información en caché para rendimiento

📋 Futuras mejoras

• [x] Integración con Git (mostrar branch actual)
• [x] Favoritos/estrellas
• [x] Escaneo automático de proyectos
• [x] Sistema de configuración portable
• [x] Quitar proyectos de la lista con exclusión permanente
• [ ] Atajos de teclado configurables
• [ ] Exportar/importar configuración
• [ ] Indicador de última vez abierto
• [ ] Temas visuales (claro/oscuro)
• [ ] Grupos personalizados de proyectos

📄 Licencia

Uso personal / Compartible con atribución

📌 Versión

v1.1 - 2025-10-12

• Sistema de exclusión permanente de proyectos (excludedProjects en config.json)
• Funcionalidad "Quitar Proyecto" para eliminar proyectos de la lista
• Los proyectos excluidos no reaparecen en futuros escaneos

v1.0 - 2025-10-11

• Sistema de configuración con config.json
• Escaneo automático de proyectos
• Integración con Git
• Sistema de favoritos
• Detección automática de tecnologías

Sistema de Contexto Multi-Nivel para Claude Code Herramienta: Gestión de proyectos y apertura rápida de Claude Code