https://github.com/shelltime/coding-extension-vim
it's a coding extension for vim. track the coding activity
https://github.com/shelltime/coding-extension-vim
Last synced: 5 months ago
JSON representation
it's a coding extension for vim. track the coding activity
- Host: GitHub
- URL: https://github.com/shelltime/coding-extension-vim
- Owner: shelltime
- License: gpl-3.0
- Created: 2025-12-28T08:18:11.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-07T18:31:14.000Z (6 months ago)
- Last Synced: 2026-01-07T23:24:19.162Z (6 months ago)
- Language: Lua
- Homepage:
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# shelltime.nvim
[](https://github.com/shelltime/coding-extension-vim/actions/workflows/ci.yml)
[](https://codecov.io/gh/shelltime/coding-extension-vim)
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
```bash
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
```bash
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`):
```yaml
codeTracking:
enabled: true
```
Or in TOML format (`~/.shelltime/config.toml`):
```toml
[codeTracking]
enabled = true
```
## Requirements
- Neovim >= 0.10.0
- Git (optional, for branch tracking)
## Installation
### lazy.nvim
```lua
{
"shelltime/coding-extension-vim",
event = "VeryLazy",
opts = {},
}
```
### packer.nvim
```lua
use {
"shelltime/coding-extension-vim",
config = function()
require("shelltime").setup()
end
}
```
### vim-plug
```vim
Plug 'shelltime/coding-extension-vim'
```
Then add to your `init.lua`:
```lua
require("shelltime").setup()
```
## Quick Start
1. **Complete the [Prerequisites](#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:
```lua
-- 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:
```bash
ls -la /tmp/shelltime.sock
# If not present, run: shelltime init
```
2. Verify config file exists:
```bash
cat ~/.shelltime/config.yaml
```
3. Enable debug mode in config:
```yaml
debug: true
```
4. Check status in Neovim:
```vim
:ShellTimeStatus
```
### Heartbeats not sending
Run `:ShellTimeStatus` to check:
- If "Disconnected", ensure daemon is running
- If pending heartbeats > 0, try `:ShellTimeFlush`
## License
[GPL-3.0](LICENSE)