My Time Trace VSCode (v0.6.0)
Uma extensão para o Visual Studio Code que monitora automaticamente o tempo gasto em cada arquivo e projeto, permitindo que você acompanhe suas atividades de desenvolvimento com um dashboard moderno, filtros avançados e envio em nuvem. A versão publicada no Marketplace já está disponível para instalação direta.
✅ Disponível no VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=BelicioBCardoso.my-time-trace-vscode
✨ Funcionalidades
🕐 Monitoramento Inteligente
- Rastreamento Automático: Registra tempo por arquivo em tempo real
- Detecção de Inatividade: Pausa automática após 5 minutos de idle
- Organização por Projeto: Agrupa dados por workspace/projeto
- Persistência Local: Armazena dados em SQLite seguro
- Identificação de Dispositivo: Registra nome do computador para cada rastreamento
- Detecção de IDE: Identifica automaticamente qual IDE está em uso (VS Code, Cursor, Windsurf, etc.) e exibe na status bar
- Sistema de Exclusão com Histórico: Soft delete, hard delete automático (>30 dias), e restauração
🗄️ Backup Automático Local (NOVO v0.6.0)
- Cópia Segura via VACUUM INTO: backup com verificação de integridade dupla (origem e destino)
- Arquivo Temporário com Rename Atômico:
.sqlite.tmp → .sqlite sem risco de arquivo corrompido
- Verificação de Espaço em Disco: impede backup se não houver espaço suficiente
- Wizard de Configuração Interativo: 4 passos guiados (pasta de destino, intervalo, retenção, confirmação)
- Agendamento Automático: configurável de 1h a 24h, com verificação de backup perdido ao retomar o VS Code
- Painel WebView de Gerenciamento: tabela com badge
● atual, exclusão individual e em lote, restauração com 1 clique
- FileSystemWatcher: painel atualiza automaticamente ao adicionar/remover backups externamente
- Política de Retenção: remove os mais antigos automaticamente mantendo mínimo de 3
- 7 novos comandos e 6 novas settings
myTimeTraceVSCode.backup.* com scope: machineu
☁️ Sincronização em Nuvem (NOVO v0.5.3)
- Sync Unidirecional: Push automático da extensão para a cloud
- Configuração Dinâmica: Backend controla
batchLimit, syncTimes, maxRetries e retryDelayMs
- Loop Automático: Processa TODAS entries pendentes em um único comando
- Retry Inteligente: Até 5 tentativas com delay configurável (padrão: 10s)
- Persistência de Config: Configs salvas localmente para uso offline
- Auto-Sync: Sincronização automática em horários configuráveis
- Status Visual: Ícone animado na status bar durante sincronização
- Multi-Dispositivo: Cada device envia seu próprio histórico para a cloud
A partir da versão 0.5.2, o sync da extensão é unidirecional (ext -> cloud).
📊 Dashboard Moderno Unificado
- Interface Responsiva: Layout grid 40/60 otimizado
- Filtros Integrados: Por data (inicial/final) e múltiplos projetos
- Gráfico Donut Interativo: Visualização com tooltips e atualização dinâmica
- Tabela Expansível: Projetos com detalhes expansíveis e ordenação por coluna
- Cards de Estatísticas: Total, Hoje, Arquivos, Esta Semana em tempo real
- Paleta de 50 Cores: Distinção visual clara entre projetos
🎨 Interface Integrada
- Status Bar Interativa: Feedback visual constante
- Formatação Inteligente: Caminhos de arquivo legíveis
- Tema Adaptativo: Suporte a dark/light mode
- Performance Otimizada: Redução de ~600 linhas de código desnecessárias
- Cores Consistentes: Mesma cor para cada projeto independente de filtros
Como Funciona
- A extensão começa a monitorar automaticamente quando o VS Code é iniciado
- Detecta automaticamente qual IDE está em uso (VS Code, Cursor, Windsurf, Code - Insiders, Google Antigravity) e exibe na status bar
- Registra o tempo que você passa em cada arquivo
- Detecta quando você muda de arquivos ou projetos
- Registra períodos de inatividade para melhorar a precisão dos dados
- Armazena todos os dados localmente (incluindo qual IDE gerou cada registro)
- Oferece visualização unificada com filtros interativos para análise detalhada
- Permite exclusão segura de projetos com histórico completo de restauração
🖥️ IDEs Suportadas
A detecção de IDE usa três camadas de fallback:
| IDE |
Detecção Primária |
Versão Capturada |
| VS Code |
globalStorageUri.fsPath |
vscode.version (API nativa) |
| Code - Insiders |
globalStorageUri.fsPath |
vscode.version (API nativa) |
| Cursor |
globalStorageUri.fsPath |
package.json da instalação |
| Windsurf |
globalStorageUri.fsPath |
package.json da instalação |
| Google Antigravity |
globalStorageUri.fsPath |
package.json da instalação |
Se a detecção via path falhar, a extensão tenta variáveis de ambiente e process info antes de registrar "unknown" — sem travar a extensão em nenhum caso.
🔬 Fisiologia da Extensão
Arquitetura Interna
A extensão utiliza uma arquitetura modular enterprise com separação clara de responsabilidades:
- Timer Heartbeat: Pulso de 1 segundo para contagem precisa em tempo real
- Event Listeners: Monitora mudanças de arquivos, janelas e atividade do usuário
- Database Layer: Camada de persistência com SQLite para armazenamento local
- UI Components: Webviews com HTML/CSS/JS para dashboards interativos
- Sync Manager: Sistema de sincronização com retry inteligente e auto-sync
💾 Armazenamento de Dados
Os dados são persistidos localmente em um banco SQLite seguro e ficam sob o armazenamento global do VS Code, o que facilita backup, inspeção e limpeza quando necessário:
Linux:
~/.config/Code/User/globalStorage/<your-username>.my-time-trace-vscode/time_tracker.sqlite
macOS:
~/Library/Application Support/Code/User/globalStorage/<your-username>.my-time-trace-vscode/time_tracker.sqlite
Windows:
%APPDATA%\Code\User\globalStorage\<your-username>.my-time-trace-vscode\time_tracker.sqlite
VS Code Insiders:
Substitua Code por Code - Insiders nos caminhos acima.
📊 Estrutura do Banco de Dados
Tabela time_entries - Registros de rastreamento de tempo:
| Campo |
Tipo |
Descrição |
id |
INTEGER |
Chave primária auto-incremento |
timestamp |
TEXT |
Data/hora ISO 8601 do registro |
project |
TEXT |
Nome do projeto/workspace |
file |
TEXT |
Caminho completo do arquivo |
duration_seconds |
INTEGER |
Duração em segundos |
is_idle |
INTEGER |
1 = período inativo, 0 = ativo |
synced |
INTEGER |
1 = sincronizado na nuvem, 0 = local |
deleted_at |
TEXT |
Timestamp do soft delete (NULL = ativo) |
device_name |
TEXT |
Nome do dispositivo/computador |
ide_name |
TEXT |
IDE detectada (VS Code, Cursor, Windsurf…) |
Tabela deletion_history - Histórico de exclusões e restaurações:
- Registro completo de soft/hard deletes
- Permite restauração de projetos excluídos
- Auditoria de operações de exclusão
Índices otimizados: Queries rápidas para filtros por projeto, data e dispositivo
🔄 Ciclo de Vida
- Ativação: Inicializa DB, cria listeners, inicia heartbeat
- Monitoramento: Timer incrementa 1s, detecta idle após 5min
- Salvamento: Persiste dados a cada mudança de arquivo ou idle
- Sincronização: Auto-sync em horários configuráveis (se habilitado)
- Desativação: Cleanup de recursos, fecha DB, cancela timers
Requisitos
- Visual Studio Code 1.100.0 ou superior (ou qualquer fork compatível: Cursor, Windsurf, Google Antigravity 2.x+)
📖 Documentação
Para documentação detalhada, consulte a pasta docs/:
📦 Instalação
Você pode instalar de duas formas: via Marketplace (recomendado) ou via VSIX local para desenvolvimento.
Opção 1 (Recomendado): Instalar pelo Marketplace
ext install BelicioBCardoso.my-time-trace-vscode
Ou acesse diretamente:
https://marketplace.visualstudio.com/items?itemName=BelicioBCardoso.my-time-trace-vscode
Opção 2 (Desenvolvimento): Instalação local via VSIX
Passo 1: Preparar o Ambiente
# Clone o repositório
git clone https://github.com/beliciobcardoso/MyTimeTraceVSCode.git
cd MyTimeTraceVSCode
# Instale as dependências
npm install
# Compile o TypeScript
npm run compile
Passo 2: Instalar a Ferramenta de Empacotamento
# Instale o vsce globalmente
npm install -g @vscode/vsce
Passo 3: Empacotar a Extensão
# Gera o arquivo .vsix
vsce package
Este comando irá gerar um arquivo como my-time-trace-vscode-X.X.X.vsix.
Passo 4: Instalar no VS Code
Após gerar o pacote, você pode instalá-lo de três maneiras:
Opção 1: Pela Interface do VS Code (Recomendado)
- Abra o VS Code (ou VS Code Insiders)
- Vá para a visualização de Extensões (
Ctrl+Shift+X ou Cmd+Shift+X)
- Clique nos três pontos (
...) no canto superior da visualização
- Selecione Instalar do VSIX...
- Navegue e selecione o arquivo
.vsix gerado
Opção 2: Pelo Terminal (VS Code)
# Para o VS Code normal
code --install-extension my-time-trace-vscode-0.6.0.vsix
Opção 3: Pelo Terminal (VS Code Insiders)
# Para o VS Code Insiders
code-insiders --install-extension my-time-trace-vscode-0.6.0.vsix
Nota para VS Code Insiders no Linux: Se o comando code-insiders não for encontrado, use a Opção 1 (instalação pela interface).
Passo 5: Ativar a Extensão
Depois de instalar, o VS Code solicitará que você recarregue a janela para ativar a extensão. Você também pode:
- Pressionar
Ctrl+Shift+P (ou Cmd+Shift+P) e executar Developer: Reload Window
- Fechar e reabrir o VS Code
✅ Verificar Instalação
Após recarregar, você deve ver:
- Ícone do relógio na barra de status inferior
- Comando disponível:
My Time Trace: Show Statistics
Configurações da Extensão
As seguintes configurações já estão disponíveis:
myTimeTraceVSCode.idleTimeout: Define o tempo, em minutos, para considerar o usuário como inativo. Padrão: 5 minutos.myTimeTraceVSCode.autoStart: Ativa ou desativa o início automático do monitoramento quando o VS Code é iniciado. Padrão: ativado.myTimeTraceVSCode.showInStatusBar: Controla a exibição do tempo atual na barra de status. Padrão: ativado.myTimeTraceVSCode.syncEnabled: Ativa ou desativa a sincronização automática em nuvem. Requer API Key. Padrão: ativado.myTimeTraceVSCode.syncInterval: Intervalo de verificação do auto-sync, em minutos. Padrão: 60, com mínimo de 5 e máximo de 1440.
Backup Automático (scope: machine — não sincronizam entre dispositivos):
myTimeTraceVSCode.backup.enabled: Ativa ou desativa o backup automático local. Padrão: desativado.myTimeTraceVSCode.backup.destinationPath: Caminho absoluto da pasta de destino dos backups. Deve ser local (evite pastas de nuvem).myTimeTraceVSCode.backup.intervalHours: Intervalo entre backups automáticos, em horas. Padrão: 24, mínimo: 1.myTimeTraceVSCode.backup.maxBackups: Quantidade máxima de arquivos de backup mantidos. Padrão: 7, mínimo: 3.myTimeTraceVSCode.backup.notifyOnSuccess: Exibe notificação ao concluir um backup com sucesso. Padrão: desativado.myTimeTraceVSCode.backup.showInStatusBar: Exibe indicador de backup na barra de status. Padrão: desativado.
🔑 Passo a passo: API Key e Sync Manual
Use este fluxo para configurar a chave e sincronizar na hora.
1) Configurar a API Key
- Abra a Command Palette (
Ctrl+Shift+P no Linux/Windows ou Cmd+Shift+P no macOS).
- Busque por My Time Trace: Set Api Key.
- Se sua interface estiver em pt-BR, o nome pode aparecer como My Time Trace: Configurar Chave API.
- Cole sua API Key e confirme.
2) Sincronizar agora
- Abra novamente a Command Palette.
- Busque por My Time Trace: Sync Now.
- Se sua interface estiver em pt-BR, o nome pode aparecer como My Time Trace: Sincronizar Agora.
- Execute o comando para enviar as entries pendentes para a nuvem.
3) Validar se funcionou
- Execute My Time Trace: View Sync Status (ou My Time Trace: Ver Status de Sincronização).
- Confira no status se as entries foram sincronizadas.
Problemas comuns
- API Key inválida ou ausente: revise a chave com Set Api Key.
- Nada para sincronizar: significa que não há entries pendentes no momento.
Recursos e Próximos Passos
✅ Recursos já entregues
- Status Bar Item: Mostra o tempo atual do arquivo e o estado do monitoramento na barra de status do VS Code.
- Heartbeat: Timer de 1 segundo para contagem precisa e atualização em tempo real.
- Interface de Visualização: Painéis e gráficos para analisar os dados de tempo coletados.
- Separação de responsabilidades: Arquitetura modular com módulos especializados.
- Tratamento de erros: Fluxos com
async/await e registro seguro de comandos.
- Visualização de dados: Dashboard unificado com filtros e gráficos interativos.
- Status Bar interativa: Feedback visual constante com atualização em tempo real.
- Sincronização em Nuvem: push-only com retry inteligente e auto-sync.
- Backup Automático Local: cópia segura via
VACUUM INTO, wizard de configuração, painel WebView de gerenciamento, agendamento automático e restauração com 1 clique.
⏭️ Próximos passos considerados
- Exportação de Dados: Exportar os dados em formatos como CSV, JSON e Excel.
- Relatórios Personalizados: Criar relatórios customizáveis por período e projeto.
- Integração Git: Correlacionar tempo de desenvolvimento com commits.
Desenvolvimento
Se você quiser contribuir, esta é a trilha recomendada para trabalhar no projeto localmente com segurança e sem perder o contexto da base atual.
Ambiente de Desenvolvimento
# Instalar dependências
npm install
# Compilar a extensão em modo de desenvolvimento
npm run compile
# Compilar e observar mudanças durante o desenvolvimento
npm run watch
🌐 Configuração de Ambiente (.env)
A URL da API é controlada pela variável API_BASE_URL. O repositório inclui um .env.example como ponto de partida:
cp .env.example .env
| Situação |
API_BASE_URL usada |
Como |
Sem .env (clone limpo) |
http://localhost:3000/api |
Fallback em constants.ts |
.env presente (desenvolvimento) |
Valor definido no .env |
Carregado por env-loader.ts via dotenv |
| VSIX publicado |
URL de produção |
.env bundled no pacote |
Nota: o arquivo .env está no .gitignore — nunca é enviado ao GitHub. Isso é intencional para projetos open source: a URL de produção fica apenas na máquina do publicador.
Para publicar com a URL de produção, crie um .env local antes de empacotar:
# Criar .env com a URL de produção (não vai para o git)
echo "API_BASE_URL=https://sua-api.com/api" > .env
# Empacotar
npm run package
Execução e Validação Local
- Pressione F5 no VS Code para abrir uma nova janela com a extensão carregada.
- A extensão deve iniciar automaticamente e começar a monitorar seu tempo.
- Para testar manualmente, use os comandos da paleta do VS Code e valide o fluxo de tracking, dashboard e sync.
- Para verificação de qualidade, rode os testes com
npm test.
Empacotamento para Teste Local
# Gera o arquivo .vsix
vsce package
Esse comando gera um arquivo como my-time-trace-vscode-X.X.X.vsix, que pode ser instalado localmente em outra máquina ou ambiente de teste.
Como Contribuir
- Faça um fork deste repositório.
- Crie uma branch para sua alteração:
git checkout -b minha-feature.
- Faça os commits da sua mudança com mensagens objetivas.
- Execute
npm run compile e npm test antes de abrir o PR.
- Envie a branch e abra um Pull Request.
Observações para Contribuição
- O código está organizado em módulos; prefira alterar a responsabilidade correta em vez de concentrar lógica em
extension.ts.
- Toda persistência deve continuar passando por
DatabaseManager.
- Se a mudança afetar UI, revise também os documentos de
docs/DASHBOARD_MODERNO.md e docs/UI_COMPONENTS.md.
Notas de Lançamento
0.6.0 (21/05/2026)
- Sistema de Backup Automático Local: cópia segura via
VACUUM INTO com verificação de integridade dupla, arquivo temporário .tmp com rename atômico e verificação de espaço em disco
- Wizard de Configuração Interativo: 4 passos guiados (pasta de destino, intervalo, retenção, confirmação) com detecção de pastas de nuvem/rede e abort total no
Esc
- Painel WebView
BackupPanel: tabela de backups ordenada por data, exclusão individual e em lote, badge ● atual, FileSystemWatcher para atualização em tempo real e botão de restauração
- Agendamento Automático:
setTimeout + setInterval com verificação de backup perdido no startup e ao recuperar foco, reagendamento com debounce ao alterar configurações
- 7 novos comandos: Fazer Backup Agora, Configurar Backup, Gerenciar Backups, Abrir Pasta de Backup, Editar Configurações de Backup, Pausar e Retomar Backup Automático
- 6 novas settings
myTimeTraceVSCode.backup.* com scope: machine (não sincronizam entre dispositivos)
- Output Channel: todas as operações registradas em
View → Output → MyTimeTrace
- i18n completo:
localize() em todo o código TypeScript e chaves %key% em package.nls.json / package.nls.pt-br.json
0.5.5 (20/05/2026)
- Detecção automática de IDE: identifica VS Code, Code - Insiders, Cursor, Windsurf e Google Antigravity com três camadas de fallback (path → env → process)
- Indicador de IDE na status bar: novo item
$(code) <nome> (v<versão>) exibido ao lado do contador de tempo
- Campo
ide_name no banco e no sync: cada registro de tempo agora armazena e envia a IDE de origem
- Compatibilidade com Antigravity 2.x: engine atualizada para
>=1.100.0
- Correções de testes: timeouts do SyncRetryManager resolvidos; categorias dos comandos de sync corrigidas
0.2.0 - Beta (28/06/2025)
Terceira versão com refatoração completa e interface avançada:
Arquitetura Modular:
- Separação de responsabilidades em módulos específicos
- Módulos especializados: configuração, banco de dados, status bar, estatísticas, rastreamento e comandos
- Melhor organização do código com classes especializadas
- Sistema Heartbeat: Timer de 1 segundo para contagem precisa e atualização em tempo real
- Tratamento de erros robusto: safeRegisterCommand com async/await para operações assíncronas
- Refatoração completa do arquivo extension.ts para usar arquitetura modular
Interface de Estatísticas Avançada:
- Layout Responsivo: Design em grid 40/60 com aproveitamento otimizado do espaço
- Header Fixo: Título sempre visível durante a navegação
- Filtros Interativos: Controles por data (início/fim) e seleção múltipla de projetos
- Resumo Dinâmico: Estatísticas em tempo real dos dados filtrados
- Projetos Expansíveis: Interface colapsível para melhor organização visual
- CSS Modular: Estilos organizados usando variáveis do tema VS Code
- JavaScript Robusto: Verificações de segurança e tratamento de erros
Melhorias Técnicas:
- Melhoria na gestão de recursos e limpeza de memória
- Melhor isolamento de responsabilidades evitando acoplamento
- Correção de bug crítico com elemento HTML ausente
- Verificações de elementos DOM antes do acesso
- Layout responsivo funcionando em diferentes tamanhos de tela
- Status Bar com feedback visual constante em tempo real
0.1.0 - Beta (18/06/2025)
Segunda versão com melhorias significativas:
- Visualização de estatísticas por projeto com detalhes de arquivos
- Exibição hierárquica de arquivos agrupados por projeto
- Formatação inteligente de caminhos de arquivos para melhor legibilidade
- Interface visual aprimorada para visualização dos dados coletados
- Seções de projetos colapsáveis para melhor organização das estatísticas
- Correção do problema "command already exists" nos testes
- Implementação de registro seguro de comandos para evitar conflitos
- Correção da funcionalidade de toggle para todos os projetos na visualização
0.0.1 - (31/05/2025)
Lançamento inicial com funcionalidades básicas:
- Monitoramento automático de tempo por arquivo
- Persistência local usando SQLite
- Detecção de inatividade após 5 minutos
- Rastreamento por projeto
- Status Bar mostrando o arquivo atual e tempo gasto
Tecnologias Utilizadas
- TypeScript
- VS Code Extension API
- SQLite (via sqlite3)
🏗️ Estrutura do Projeto
MyTimeTraceVSCode/
├── 📁 src/ # Código fonte principal
│ ├── extension.ts # Ponto de entrada da extensão
│ ├── modules/ # Módulos especializados
│ │ ├── timeTrace.ts # Engine de rastreamento
│ │ ├── database.ts # Gerenciamento SQLite
│ │ ├── statusBar.ts # Interface barra de status
│ │ └── ...
│ ├── ui/ # Componentes de interface
│ └── test/ # Testes automatizados
├── 📁 docs/ # 📖 Documentação completa
├── 📁 images/ # Assets visuais
└── 📁 UI/ # Demos e protótipos
Licença
Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para mais detalhes.
Qualidade e Confiabilidade
🧪 Testes Automatizados
A extensão possui 139 testes automatizados que garantem a qualidade e confiabilidade:
- ✅ 139 testes passando
- ✅ Testes abrangentes incluindo:
- Ativação/desativação da extensão
- Rastreamento de tempo e detecção de idle
- Persistência de dados no SQLite
- Detecção de IDE (getIdeName, getIdeVersion, fallbacks)
- Interface do status bar em tempo real
- Retry automático de sincronização
- Backup automático (BackupManager, BackupPanel, BackupRetryManager)
- Integração entre módulos
🏗️ Arquitetura Modular
- Separação clara de responsabilidades com módulos especializados
- Código TypeScript com tipagem forte
- Tratamento robusto de erros com async/await
- Cleanup automático de recursos
Para mais detalhes, consulte o Relatório de Cobertura de Testes.
Aproveite o My Time Trace VSCode e monitore seu tempo de desenvolvimento de forma eficiente!
