🖥️ 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
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
// 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.
# 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.
# 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
🧩 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.
Documents Gallery
31 mai 2026Added: visualização de docs Obsidian no dashboard. Filtro por vault. aggregate.ts 3x mais rápido (processamento paralelo).
Skill /personas
15 abr 2026Added: panteão de personas YAML locais. Painel de personas no dashboard. Changed: migração Vercel → Cloudflare Pages.
Skill /dream
01 mar 2026Added: skill /dream com 8 buckets de sinal. Painel de prescrições no dashboard.
MVP — Walking Skeleton
10 jan 2026Script 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
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.
📋 Resumo da Trilha 5
Você completou a Trilha 5. Aqui está o que dominou:
- 🏗️ 5.1 Arquitetura de projeto
- 🧠 5.2 CLAUDE.md e memória
- 📦 5.3 Versionamento e CHANGELOG
- 🖥️ 5.4 Case study ClaudeOS
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 →