5.4 Trilha 5 ~50 min Case Real

🖥️ Case study: ClaudeOS (Hermes)

Dissecar um projeto real de longo prazo: dashboard pessoal de IA com Bun + TanStack/React + Vite + Tailwind, deploy em Cloudflare. V2.3 — mai/2026.

1 🗺️ Visão geral do projeto

ClaudeOS (codinome Hermes) é um dashboard pessoal read-only para quem roda um stack de IA local. Ele consolida dados de múltiplas fontes em uma interface única — sem modificar nenhuma delas.

🍞

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 artefato 🖥️ UI Fontes de dados scripts/aggregate.ts src/data/

Arquitetura do ClaudeOS: fontes → pipeline → JSON → dashboard React

Por que este projeto é um bom case study

Aplica 5.1

Arquitetura em camadas com separação scripts/src. Cada pasta com responsabilidade única.

Aplica 5.2

CLAUDE.md com restrições explícitas de segurança e privacidade. Onboarding saudação.

Aplica 5.3

CHANGELOG estruturado desde a V1. Tags semver em cada release. V2.3 em mai/2026.

2 ⚙️ scripts/aggregate.ts — o coração do sistema

O arquivo mais importante do ClaudeOS não é um componente React — é um script TypeScript que roda fora do browser. Ele lê fontes heterogêneas e produz um único JSON que o dashboard consome.

scripts/aggregate.ts — estrutura 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()

✓ Padrão elegante

  • • Script separado de src/ (responsabilidade única)
  • • Promise.all para I/O paralelo
  • • Saída em JSON estruturado e versionável
  • • Timestamp de geração incluso
  • • Nunca modifica as fontes (read-only)

🔁 Replicável para

  • • Qualquer dashboard de métricas
  • • Relatórios automatizados
  • • Consolidação de logs distribuídos
  • • Pipelines de dados locais
  • • Geração de feeds estáticos
💡

O padrão "script → JSON → UI"

Separar coleta de dados da apresentação é uma das arquiteturas mais resilientes para projetos pessoais. O dashboard pode ser reconstruído do zero sem perder dados. O pipeline pode rodar no cron sem a UI existir.

3 💤 Skill /dream — auditoria de 24h

A skill /dream é um exemplo de skill com output estruturado. Ela não responde em prosa — ela escreve um arquivo JSON que o dashboard renderiza como cards de ação.

~/.claude/skills/dream/SKILL.md — estrutura
# 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

Os 8 buckets de sinal

💰

1. Tokens

vs budget

📁

2. Projetos

mais ativos

🧰

3. Skills

mais invocadas

📓

4. Obsidian

criadas/mod

🌲

5. Pinecone

tópicos

🤖

6. Modelos

OpenRouter

💳

7. Dívida

registrada hoje

📝

8. Commits

e PRs

4 📜 CLAUDE.md do ClaudeOS — exemplo real

O CLAUDE.md do ClaudeOS é um exemplo de instruções de nível produção. Cada regra tem uma razão 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 que cada regra existe

Nunca ler ~/.claude diretamente: evita acesso inadvertido a conversas privadas
Read-only enforcement: impede bugs que corrompem fontes de dados
Sem telemetria: projeto pessoal — nenhum dado sai do dispositivo

🧩 Padrão reutilizável

• Saudação de onboarding = contexto imediato

• Regras por categoria (privacidade, arquitetura, segurança)

• Justificativa inline para cada restrição crítica

• Mapa de pastas com propósito explícito

5 📦 CHANGELOG V2.3 — historial como espelho

O CHANGELOG do ClaudeOS conta a história de um projeto que evoluiu de um script simples para um dashboard completo. Cada versão é um marco.

V2.3

Documents Gallery

31 mai 2026

Added: visualização de docs Obsidian no dashboard. Filtro por vault. aggregate.ts 3x mais rápido (processamento paralelo).

V2.2

Skill /personas

15 abr 2026

Added: panteão de personas YAML locais. Painel de personas no dashboard. Changed: migração Vercel → Cloudflare Pages.

V2.1

Skill /dream

01 mar 2026

Added: skill /dream com 8 buckets de sinal. Painel de prescrições no dashboard.

V1.0

MVP — Walking Skeleton

10 jan 2026

Script aggregate.ts básico + dashboard React mínimo. Apenas dados do Claude Code.

💡

O que o CHANGELOG revela

Lendo o CHANGELOG você vê: o projeto começou pequeno (V1.0 só Claude Code), cresceu incrementalmente, migrou de plataforma quando fez sentido, e cada versão adicionou uma coisa por vez. Isso é crescimento saudável.

6 🔗 Mock do dashboard e lições para o seu projeto

ClaudeOS — Dashboard (MOCK ILUSTRATIVO — não é screenshot real)
V2.3
🖥️ Hermes ClaudeOS
v2.3.0

Tokens hoje

84.2k

Notas Obsidian

1.847

Queries Pinecone

23

Skills invocadas

7

💤 Prescrições /dream

#1 Alta prioridade

Consolidar 3 projetos inativos para reduzir overhead de contexto

#2 Média prioridade

Budget 62% consumido — considerar cache para prompts repetidos

Gerado em 2026-06-01T08:00:00Z · READ-ONLY

⚠️ Mock HTML ilustrativo — não representa dados reais nem screenshot do sistema

✓ Padrões replicáveis

  • • Script gerador + JSON artefato + UI
  • • CLAUDE.md com restrições por categoria
  • • Skills com output JSON (não prosa)
  • • CHANGELOG desde a V1
  • • Walking skeleton crescendo incrementalmente

🚀 Aplique no seu projeto

  • • Identifique qual é o seu "aggregate.ts"
  • • Defina restrições no CLAUDE.md antes de codar
  • • Inicie o CHANGELOG na V0.1
  • • Separe scripts de src/ desde o início
  • • Read-only onde possível — menos bugs
🏗️

Baixe o projeto ClaudeOS (Hermes) V2.3 · ~88 MB

O código-fonte completo deste estudo de caso: o scanner aggregate.ts, o setup.ts, as skills /dream e /personas, o CLAUDE.md e o CHANGELOG. Um projeto de longo prazo real para estudar de ponta a ponta.

⬇ Baixar ClaudeOS-Hermes-V2.3.zip

📋 Resumo da Trilha 5

Você completou a Trilha 5. Aqui está o que dominou:

✅ Módulos concluídos
  • 🏗️ 5.1 Arquitetura de projeto
  • 🧠 5.2 CLAUDE.md e memória
  • 📦 5.3 Versionamento e CHANGELOG
  • 🖥️ 5.4 Case study ClaudeOS
🚀 Próxima trilha

Trilha 6 cobre Deploy — como colocar seu projeto em produção com Cloudflare, GitHub Actions, domínios customizados e monitoramento.

🚀 Ir para Trilha 6: Deploy →