🖥️ 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
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
// 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.
# 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.
# 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
🧩 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.
Galería de documentos
31 may 2026Added: visualización de docs de Obsidian en el dashboard. Filtro por vault. aggregate.ts 3x más rápido (procesamiento en paralelo).
Skill /personas
15 abr 2026Added: panteón de personas YAML locales. Panel de personas en el dashboard. Changed: migración de Vercel → Cloudflare Pages.
Skill /dream
01 mar 2026Added: skill /dream con 8 buckets de señales. Panel de prescripciones en el dashboard.
MVP — Walking Skeleton
10 ene 2026Script 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
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.
📋 Resumen de la Ruta 5
Completaste la Ruta 5. Esto es lo que dominas:
- 🏗️ 5.1 Arquitectura del proyecto
- 🧠 5.2 CLAUDE.md y memoria
- 📦 5.3 Versionado y CHANGELOG
- 🖥️ 5.4 Caso de estudio ClaudeOS
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 →