shelltime.nvim

A Neovim plugin for automatic coding activity tracking. Works with the ShellTime daemon to monitor your development time across projects.

Features

• Automatic Time Tracking - Passively monitors coding activity
• Language Detection - Auto-detects programming language from filetype
• Project Analytics - Tracks time per project/workspace
• Git Integration - Records activity by git branch
• Event Debouncing - Efficient heartbeat batching (30s cooldown per file)
• Offline Support - Queues heartbeats when daemon unavailable

Prerequisites

1. Install ShellTime CLI

curl -sSL https://shelltime.xyz/i | bash

After installation, reload your shell configuration:

• zsh: source ~/.zshrc
• fish: source ~/.config/fish/config.fish
• bash: source ~/.bashrc

2. Initialize and Authenticate

shelltime init

This will:

• Open your browser to authenticate with your ShellTime account
• Install shell hooks for your shell (zsh/fish/bash)
• Start the ShellTime daemon

3. Enable Code Tracking

Add the following to your ShellTime config (~/.shelltime/config.yaml):

codeTracking:
  enabled: true

Or in TOML format (~/.shelltime/config.toml):

[codeTracking]
enabled = true

Requirements

• Neovim >= 0.10.0
• Git (optional, for branch tracking)

Installation

lazy.nvim

{
  "shelltime/coding-extension-vim",
  event = "VeryLazy",
  opts = {},
}

packer.nvim

use {
  "shelltime/coding-extension-vim",
  config = function()
    require("shelltime").setup()
  end
}

vim-plug

Plug 'shelltime/coding-extension-vim'

Then add to your init.lua:

require("shelltime").setup()

Quick Start

1. Complete the Prerequisites - Install CLI, authenticate, and enable code tracking

2. Install the plugin using your preferred plugin manager (see above)

3. Start coding - The plugin automatically tracks your activity!

Configuration

The plugin reads settings from ~/.shelltime/config.yaml by default:

-- Default setup (uses ~/.shelltime/config.yaml)
require("shelltime").setup()

-- Custom config path
require("shelltime").setup({
  config = "/path/to/your/config.yaml",
})

Config File Options

Option	Type	Default	Description
socketPath	string	/tmp/shelltime.sock	Unix socket path for daemon
codeTracking.enabled	boolean	true	Enable/disable tracking
debug	boolean	false	Enable debug logging

Commands

Command	Description
:ShellTimeStatus	Show daemon connection status and pending heartbeats
:ShellTimeFlush	Manually flush pending heartbeats to daemon
:ShellTimeEnable	Enable tracking
:ShellTimeDisable	Disable tracking

How It Works

The plugin monitors these Neovim events:

Event	Trigger
BufEnter	Opening a file
TextChanged / TextChangedI	Editing text
BufWritePost	Saving a file
CursorMoved / CursorMovedI	Moving cursor

Heartbeats are:

• Debounced: Max 1 heartbeat per file per 30 seconds (except saves)
• Batched: Sent to daemon every 2 minutes
• Queued: Stored locally if daemon is unavailable

Data Tracked

Each heartbeat includes:

• File info: Path, language, line count, cursor position
• Project info: Name, root path, git branch
• Editor info: Neovim version, plugin version
• System info: Hostname, OS, OS version
• Activity: Timestamp, whether it was a save event

Troubleshooting

Plugin not tracking

1. Check if daemon is running:

   ls -la /tmp/shelltime.sock
   # If not present, run: shelltime init

2. Verify config file exists:

   cat ~/.shelltime/config.yaml

3. Enable debug mode in config:

   debug: true

4. Check status in Neovim:

   :ShellTimeStatus

Heartbeats not sending

Run :ShellTimeStatus to check:

• If "Disconnected", ensure daemon is running
• If pending heartbeats > 0, try :ShellTimeFlush

License

GPL-3.0