Jira Timer

Timer de horas para o Jira dentro do VS Code, com lançamento automático de worklogs.

Onde ele aparece

• Barra de status (canto inferior esquerdo): tarefa e tempo correndo. Clique para abrir o menu.
• Sidebar: ícone de cronômetro na barra lateral esquerda, com o painel resumido.
• Tela cheia: abre na área de editores, como um arquivo ou o Claude Code. Pelo botão ⤢ da sidebar, pelo menu da barra de status ou pelo comando Jira Timer: Abrir tela completa.

Sidebar

• Timer ativo em destaque: chave, título, relógio, Pausar/Retomar, Parar e lançar, Descartar.
• Resumo: anéis de progresso de hoje e da semana contra as suas metas, e barras por dia.
• Aba Issues: busca, filtros, alfinete para fixar e botão ▶ (issues das branches e as fixadas ficam no topo).
• Aba Worklogs: o que você lançou hoje ou na semana. Clique em um item para editar.

Tela cheia

• Calendário por dia ou semana, com cada worklog no horário certo, totais por dia, linha do "agora" e o timer em andamento crescendo ao vivo. Navegação (‹ › Hoje) e zoom (barra da toolbar ou Ctrl + scroll sobre o calendário, mantendo o horário sob o cursor no lugar).
• Lançar pelo calendário: arraste sobre um horário vazio para escolher o intervalo, clique para 30 min, ou arraste uma issue das Sugestões e solte no horário.
• Ajustar pelo calendário: arraste um bloco para mudar o horário (inclusive para outro dia) ou puxe a borda de cima/baixo para alterar início/duração. Encaixa de 15 em 15 min (segure Shift para 5 em 5) e também nas bordas dos outros blocos (ex.: dá para começar às 9:13, logo quando o bloco anterior terminou; uma linha tracejada mostra onde encaixou). Segure Ctrl para soltar sem nenhum encaixe, com precisão de 1 minuto. Esc cancela e um clique simples abre a edição. A mudança é gravada no Jira na hora; se ele recusar, o bloco volta ao lugar.
• Sugestões: busca, "atribuídas a mim", projeto, filtro salvo e ordenação.
• Lista: os mesmos worklogs em tabela, agrupados por dia.
• Pílula do timer no topo, com pausar, parar e descartar.

Issues no topo: branches e fixadas

A lista de issues (sidebar, tela cheia e seleção rápida) mostra no topo, nesta ordem:

1. Issues das suas branches: a extensão lê a branch de todos os repositórios git abertos no VS Code (uma pasta, várias pastas ou repositórios aninhados) e liga cada chave encontrada (ex.: feature/PROJ-123-login) à issue do Jira. O cartão fica em verde com uma tag por repositório/branch. A lista atualiza sozinha ao trocar de branch.
2. Issues fixadas: clique no alfinete do cartão para fixar (ótimo para tarefas de suporte). Ficam no topo mesmo fora dos filtros ou da busca padrão, na ordem em que foram fixadas. Clique de novo para desafixar.

Lançar e editar worklog

O diálogo tem os mesmos campos do Jira:

Cada pausa fecha um período. Ao parar, o timer lança um worklog por período, no horário em que ele aconteceu (ex.: 8h–12h e 13h–15h viram dois worklogs, e o calendário mostra o intervalo vazio). No diálogo os períodos aparecem como linhas editáveis (início, fim e remover), com a mesma descrição para todos. Pausas menores que 1 minuto são unidas e períodos menores que 1 minuto são descartados.

Ao parar o timer (com jiraTimer.confirmOnStop ligado) o diálogo já vem preenchido com o tempo e o início do timer, e você pode ajustar tudo antes de lançar.

Metas de horas

Padrão: 6h30 por dia e 32h30 por semana. Para mudar, clique na engrenagem do resumo (aceita 6h30, 6:30 ou 6.5) ou edite jiraTimer.dailyGoalHours / jiraTimer.weeklyGoalHours.

Regras de funcionamento

• Iniciar um timer com outro rodando lança o atual no Jira automaticamente e começa o novo (timers com menos de 1 minuto são descartados).
• Ao mudar de branch com a chave de uma issue (ex.: feature/PROJ-123-login), aparece uma sugestão para iniciar ou trocar o timer.
• Se você usar o VS Code por um tempo sem timer rodando, aparece um lembrete.
• Se o VS Code for fechado com o timer rodando, ele é pausado no último instante em que esteve aberto.

Conectar ao Jira (passo a passo)

A conexão usa o seu e-mail da Atlassian + um token de API. O token é uma "senha especial" que só você gera e que só vale para o seu usuário: o timer lança as horas em seu nome, com as suas permissões. Faça isso uma vez.

O que você vai precisar

Passo 1: gerar o token (no navegador)

1. Abra https://id.atlassian.com/manage-profile/security/api-tokens e entre com a sua conta Atlassian, se pedir. (A extensão também abre essa página para você no botão Abrir página do token.)
2. Clique em Criar token de API (Create API token).

   ⚠️ Use o botão simples. Não use Criar token de API com escopos: esse tipo não funciona com a extensão.

3. Em Nome, escreva algo como VS Code. Em Expira em, escolha a validade (o máximo é 1 ano).
4. Clique em Criar.
5. Clique em Copiar. ⚠️ O token só aparece nesta tela, uma vez. Se fechar sem copiar, é só criar outro.

Passo 2: conectar no VS Code

1. Clique no ícone de cronômetro na barra lateral esquerda e depois em Conectar ao Jira. (Ou Ctrl+Shift+P → Jira Timer: Configurar conexão com o Jira.)
2. Leia a janela e clique em Abrir página do token (passo 1) ou em Já tenho o token.
3. Responda as 3 perguntas que aparecem no topo do VS Code:
   1. Endereço do Jira, ex.: https://suaempresa.atlassian.net
   2. E-mail da sua conta Atlassian
   3. Token: cole o que você copiou (Ctrl+V). Ele aparece escondido, é normal.
4. A extensão testa a conexão antes de salvar. Se der certo, aparece "Conectado ao Jira como Seu Nome". Se der errado, ela diz o motivo e deixa tentar de novo sem digitar tudo outra vez.

O token fica guardado no cofre seguro do VS Code (SecretStorage), não em arquivo de texto.

Problemas comuns

Trate o token como uma senha: não envie por chat/e-mail e não coloque em repositório. Se suspeitar que vazou, apague-o na página de tokens da Atlassian (botão Revogar) e gere outro.

Configurações

Limitações

• Jira Cloud (API v3) com e-mail + API token. Jira Server/Data Center não é suportado.
• O token expira na data escolhida ao criá-lo (máximo 1 ano). Quando expirar, a extensão avisa e é só gerar outro.
• Cria worklogs nativos do Jira. O painel lê os worklogs nativos, então ele mostra o que o app de timesheet da empresa gravar como worklog do Jira.