PTENES
5.4 Ruta 5 ~50 min Caso real

🖥️ Estudio de caso: ClaudeOS (Hermes)

Analizar en detalle un proyecto real de largo plazo: un dashboard personal de IA con Bun + TanStack/React + Vite + Tailwind, con deploy en Cloudflare. V2.3 — may/2026.

1 🗺️ Descripción general del proyecto

ClaudeOS (nombre en clave Hermes) es un dashboard personal read-only para quien ejecuta un stack de IA local. Consolida datos de múltiples fuentes en una interfaz única, sin modificar ninguna de ellas.

🍞

Bun 1.1

Runtime

⚛️

React 19

TanStack Query

⚡

Vite 6

+ Tailwind 4

☁️

Cloudflare

Pages + wrangler

🤖 Claude Code 📓 Obsidian 🔗 OpenRouter 🌲 Pinecone ⚙️ aggregate.ts scanner + pipeline 📄 live-data .json artefacto 🖥️ UI Fuentes de datos scripts/aggregate.ts src/data/

Arquitectura de ClaudeOS: fuentes → pipeline → JSON → dashboard de React

Por qué este proyecto es un buen case study

Aplica 5.1

Arquitectura en capas con separación scripts/src. Cada carpeta tiene una responsabilidad única.

Aplica 5.2

CLAUDE.md con restricciones explícitas de seguridad y privacidad. Saludo de onboarding.

Aplica 5.3

CHANGELOG estructurado desde la V1. Tags semver en cada release. V2.3 en may/2026.

2 ⚙️ scripts/aggregate.ts — el corazón del sistema

El archivo más importante de ClaudeOS no es un componente de React: es un script TypeScript que se ejecuta fuera del navegador. Lee fuentes heterogéneas y produce un único JSON que consume el dashboard.

scripts/aggregate.ts — estructura simplificada
// scripts/aggregate.ts
// Lê todas as fontes de dados e gera src/data/live-data.json
// NUNCA modifica as fontes — read-only

import { readdir, readFile, writeFile } from 'fs/promises'
import { join } from 'path'

async function aggregateClaudeHistory() {
  const historyDir = join(process.env.HOME!, '.claude', 'history')
  // Lê arquivos de sessão dos últimos 30 dias
  // Extrai: tokens usados, projetos, modelos
  return { sessions: [...], tokenTotal: 0 }
}

async function aggregateObsidian() {
  const vaultPath = process.env.OBSIDIAN_VAULT_PATH!
  // Percorre .md recursivamente, lê frontmatter
  return { notes: [...], recentlyModified: [...] }
}

async function main() {
  const [claude, obsidian, openrouter, pinecone] = await Promise.all([
    aggregateClaudeHistory(),
    aggregateObsidian(),
    fetchOpenRouterStats(),
    fetchPineconeStats(),
  ])

  const liveData = { claude, obsidian, openrouter, pinecone,
                      generatedAt: new Date().toISOString() }

  await writeFile('src/data/live-data.json',
                  JSON.stringify(liveData, null, 2))
  console.log('✅ live-data.json gerado')
}

main()

✓ Estándar elegante

  • • Script separado de src/ (responsabilidad única)
  • • Promise.all para I/O en paralelo
  • • Salida en JSON estructurado y versionable
  • • Incluye la marca de tiempo de generación
  • • Nunca modifica las fuentes (read-only)

🔁 Replicable para

  • • Cualquier dashboard de métricas
  • • Informes automatizados
  • • Consolidación de logs distribuidos
  • • Pipelines de datos locales
  • • Generación de feeds estáticos
💡

El patrón "script → JSON → UI"

Separar la recopilación de datos de la presentación es una de las arquitecturas más resilientes para proyectos personales. El dashboard se puede reconstruir desde cero sin perder datos. El pipeline puede ejecutarse en el cron sin que exista la UI.

3 💤 Skill /dream — auditoría de 24h

La skill /dream es un ejemplo de skill con output estructurado. No responde en prosa: escribe un archivo JSON que el dashboard muestra como tarjetas de acción.

~/.claude/skills/dream/SKILL.md — estructura
# Skill /dream

## Propósito
Auditar as últimas 24h do stack de IA em 8 buckets de sinal.
Gerar as 4 prescrições de maior impacto em JSON.

## Buckets de sinal
1. Tokens consumidos vs budget diário
2. Projetos mais ativos (por sessão)
3. Skills mais invocadas
4. Notas Obsidian criadas/modificadas
5. Queries Pinecone (tópicos consultados)
6. Modelos OpenRouter usados
7. Dívidas técnicas registradas hoje
8. Commits e PRs abertos

## Output obrigatório
Ao terminar análise, escrever em src/data/dream-output.json:
{
  "generatedAt": "ISO-8601",
  "buckets": [ { "id": 1, "signal": "...", "value": "..." } ],
  "prescriptions": [
    { "rank": 1, "impact": "high", "action": "...", "rationale": "..." }
  ]
}

## Regras
- NUNCA exibir dados privados em texto livre
- Máximo 4 prescrições, ordenadas por impacto
- Basear APENAS em dados do live-data.json

Los 8 buckets de señal

💰

1. Tokens

vs budget

📁

2. Proyectos

más activos

🧰

3. Skills

más invocadas

📓

4. Obsidian

creadas/mod

🌲

5. Pinecone

temas

🤖

6. Modelos

OpenRouter

💳

7. Deuda

registrada hoy

📝

8. Commits

y PRs

4 📜 CLAUDE.md de ClaudeOS — ejemplo real

El CLAUDE.md de ClaudeOS es un ejemplo de instrucciones de nivel de producción. Cada regla tiene una razón clara de existir.

CLAUDE.md — ClaudeOS (Hermes)
# ClaudeOS (Hermes) — Instruções do agente

## Saudação de onboarding
Bem-vindo ao ClaudeOS! Você está trabalhando no dashboard
pessoal de IA. Antes de qualquer task, leia este arquivo.

## O que é este projeto
Dashboard read-only que consolida dados de Claude Code,
Obsidian, OpenRouter e Pinecone para visualização pessoal.
Stack: Bun + React 19 + TanStack Query + Vite + Tailwind 4
Deploy: Cloudflare Pages (wrangler)

## Regras OBRIGATÓRIAS

### Privacidade
- NUNCA ler ou escrever diretamente em ~/.claude/
  → Dados chegam via scripts/aggregate.ts e src/data/live-data.json
- NUNCA enviar dados do usuário para serviços externos
- Anonimização LIGADA — remove PII de outputs
- Sem telemetria — sem analytics, sem tracking

### Arquitetura
- Dashboard é READ-ONLY — NUNCA modificar fontes de dados
- Código novo vai em src/ — scripts de dados vão em scripts/
- Não criar arquivos na raiz do projeto

### Segurança
- API keys SEMPRE via variáveis de ambiente (.env)
- .env está no .gitignore — nunca commit

## Estrutura do projeto
src/
  components/   → UI React
  data/         → live-data.json (gerado, não editado)
scripts/
  aggregate.ts  → coleta dados das fontes
  setup.ts      → setup inicial (roda uma vez)

🔍 Por qué existe cada regla

Nunca leas ~/.claude directamente: evita el acceso inadvertido a conversaciones privadas
Read-only enforcement: evita errores que corrompen las fuentes de datos
Sin telemetría: proyecto personal — ningún dato sale del dispositivo

🧩 Patrón reutilizable

• Saludo de onboarding = contexto inmediato

• Reglas por categoría (privacidad, arquitectura, seguridad)

• Justificación inline para cada restricción crítica

• Mapa de carpetas con propósito explícito

5 📦 CHANGELOG V2.3 — el historial como espejo

El CHANGELOG de ClaudeOS cuenta la historia de un proyecto que evolucionó de un script simple a un dashboard completo. Cada versión es un hito.

V2.3

Galería de documentos

31 may 2026

Added: visualización de docs de Obsidian en el dashboard. Filtro por vault. aggregate.ts 3x más rápido (procesamiento en paralelo).

V2.2

Skill /personas

15 abr 2026

Added: panteón de personas YAML locales. Panel de personas en el dashboard. Changed: migración de Vercel → Cloudflare Pages.

V2.1

Skill /dream

01 mar 2026

Added: skill /dream con 8 buckets de señales. Panel de prescripciones en el dashboard.

V1.0

MVP — Walking Skeleton

10 ene 2026

Script aggregate.ts básico + dashboard React mínimo. Solo datos de Claude Code.

💡

Qué revela el CHANGELOG

Al leer el CHANGELOG, ves que el proyecto empezó siendo pequeño (V1.0 solo Claude Code), creció de forma incremental, migró de plataforma cuando tuvo sentido y cada versión agregó una cosa a la vez. Eso es un crecimiento saludable.

6 🔗 Mock del dashboard y lecciones para tu proyecto

ClaudeOS — Dashboard (MOCK ILUSTRATIVO — no es una captura de pantalla real)
V2.3
🖥️ Hermes ClaudeOS
v2.3.0

Tokens de hoy

84.2k

Notas de Obsidian

1.847

Consultas de Pinecone

23

Skills invocadas

7

💤 Prescripciones /dream

#1 Alta prioridad

Consolidar 3 proyectos inactivos para reducir la sobrecarga de contexto

#2 Prioridad media

62% del budget consumido — considera usar caché para prompts repetidos

Generado en 2026-06-01T08:00:00Z · READ-ONLY

⚠️ Mock HTML ilustrativo — no representa datos reales ni una captura de pantalla del sistema

✓ Patrones replicables

  • • Script generador + artefacto JSON + UI
  • • CLAUDE.md con restricciones por categoría
  • • Skills con salida JSON (no prosa)
  • • CHANGELOG desde la V1
  • • Walking skeleton que crece de forma incremental

🚀 Aplícalo en tu proyecto

  • • Identifica cuál es tu "aggregate.ts"
  • • Define restricciones en el CLAUDE.md antes de programar
  • • Inicia el CHANGELOG en la V0.1
  • • Separa los scripts de src/ desde el inicio
  • • Read-only cuando sea posible: menos bugs
🏗️

Descarga el proyecto ClaudeOS (Hermes) V2.3 · ~88 MB

El código fuente completo de este estudio de caso: el scanner aggregate.ts, o setup.ts, las skills /dream e /personas, o CLAUDE.md e o CHANGELOG. Un proyecto real de largo plazo para estudiar de principio a fin.

⬇ Descargar ClaudeOS-Hermes-V2.3.zip

📋 Resumen de la Ruta 5

Completaste la Ruta 5. Esto es lo que dominas:

✅ Módulos completados
  • 🏗️ 5.1 Arquitectura del proyecto
  • 🧠 5.2 CLAUDE.md y memoria
  • 📦 5.3 Versionado y CHANGELOG
  • 🖥️ 5.4 Caso de estudio ClaudeOS
🚀 Próxima ruta

La Ruta 6 cubre Deploy: cómo poner tu proyecto en producción con Cloudflare, GitHub Actions, dominios personalizados y monitoreo.

🚀 Ir a la Ruta 6: Deploy →