aelena/break-time

O que break-time faz?

Uma habilidade ambiente que te lembra de fazer uma pausa quando você está concentrado por muito tempo. O Claude em si não consegue rastrear o tempo real entre respostas — ele vê apenas a conversa. Hooks são executados fora do Claude, no harness, e podem injetar contexto que o Claude não teria de outra forma. É assim que isso funciona.

Se você nunca escreveu um hook, leia HOOKS-101.md primeiro. É um tutorial independente — fácil de copiar e colar, ~15 minutos de leitura, e é a base para qualquer habilidade ambiente que você queira construir depois.

O que faz

• Rastreia o início da "sessão ativa" atual (reinicia após 10 minutos de inatividade).
• A cada prompt que você envia, calcula há quanto tempo você está trabalhando ativamente.
• Quando você ultrapassa um limite configurável (padrão 45, 90, 120 minutos), injeta um lembrete único no contexto do Claude. O Claude o mencionará brevemente na sua próxima resposta, com seu próprio tom, antes de responder sua pergunta.
• Você pode adiar (/snooze 60) ou reiniciar (/break-reset).
• Cada limite é disparado apenas uma vez por sessão ativa — sem spam.

Invocação

A habilidade consiste em duas partes: um hook passivo (executado automaticamente após a instalação) e alguns comandos ativos para gerenciá-la.

Gatilho	Comportamento
(automático)	O hook é executado a cada prompt. Nenhuma invocação necessária após a instalação.
/break ou /break-time	Mostra o estado atual: há quanto tempo a sessão ativa está rodando, quando o próximo limite será disparado, status de adiamento.
/snooze [N]	Adia os lembretes por N minutos (padrão 60).
/break-reset	Reinicia o timer da sessão ativa (trata agora como início da sessão).
/break-time configure	Guia o usuário na edição dos limites em ~/.claude/break-time.conf.
Linguagem natural: "adiar break-time", "vou fazer uma pausa agora", "parar o timer"	Mesmo

Desabilitar

Remova o bloco do hook de ~/.claude/settings.json. Os arquivos da habilidade podem permanecer; sem o hook configurado, eles ficam inertes.

Instalação

1. Copie break-time/ para ~/.claude/skills/break-time/.
2. Adicione o bloco do hook de example-settings.json ao seu ~/.claude/settings.json (o arquivo já existe; faça merge, não sobrescreva).
3. Reinicie o Claude Code para que o harness reconheça o novo hook.
4. Pronto. O hook será executado em cada prompt a partir de agora.

O tutorial completo para iniciantes está em HOOKS-101.md.

Como o hook funciona (mecanicamente)

1. Você envia um prompt.
2. O harness chama bash ~/.claude/skills/break-time/scripts/check_break.sh antes do Claude ver o prompt.
3. O hook lê ~/.claude/break-time.state (um arquivo chave-valor simples), calcula o tempo decorrido e decide se algum limite foi ultrapassado.
4. Se um limite for disparado, o hook imprime um bloco <system-reminder> na saída padrão. O harness captura a saída padrão e a adiciona como contexto adicional para a próxima rodada do Claude.
5. O Claude vê o lembrete e o incorpora na sua resposta: "A propósito, você está focado há 90 minutos — levante-se e ande um pouco antes de continuarmos. Agora, sobre sua pergunta..."
6. Cada limite disparado é registrado no arquivo de estado para que não dispare novamente até que a sessão ativa seja reiniciada.

Configuração

O estado e a configuração ficam em ~/.claude/:

• break-time.state — estado em tempo de execução (session_start, limites disparados, snooze)
• break-time.conf — configuração opcional do usuário (limites, gap de inatividade, estilo da mensagem)

Se break-time.conf estiver ausente, os padrões são usados:

THRESHOLDS="45 90 120"   # minutos — quando lembrar
IDLE_GAP=10              # minutos de inatividade = nova sessão
STYLE=friendly           # friendly | aggressive | poetic

STYLE=poetic transforma o lembrete em um haikai (uma carta de amor entre habilidades para poet-commit).

Salvaguardas de segurança

• Nunca bloqueia um prompt. O hook sempre sai com código 0 — se falhar, o trabalho do usuário não é afetado.
• Sempre registra em um arquivo (~/.claude/break-time.log) para que a depuração seja possível sem exibir erros em banda.
• Saída limitada. O lembrete é um parágrafo curto. Nunca inunda a janela de contexto.
• Adiamento sempre respeitado. Se o usuário adiou, o hook ainda rastreia o tempo, mas não emite nada.
• Sem chamadas de rede. Apenas E/S de arquivos local. Nunca atrasa o prompt.

Arquivos desta habilidade

• SKILL.md — este arquivo
• HOOKS-101.md — tutorial independente sobre como escrever hooks (publicável)
• example-settings.json — configuração de hook pronta para copiar e colar em ~/.claude/settings.json
• scripts/check_break.sh — o hook em si
• scripts/snooze.sh — adia lembretes por N minutos
• scripts/reset.sh — reinicia o timer da sessão ativa
• scripts/state.sh — exibe o estado atual (usado por /break)
• README.md — instruções curtas de instalação