jasper.nvim/README.md

jasper.nvim

Neovim plugin for automatic time tracking via Jasper.

Features

• Reads a per-project .jasper_config.json to know which Jasper activity to track.
• Automatically starts the timer when Neovim opens and stops it when Neovim closes.
• Auto-pauses after a configurable period of inactivity (no cursor movement, typing, etc.) and resumes on the next keystroke.
• Shares the auth token cache with jasper_waybar.py ($XDG_CONFIG_HOME/jasper/token.json).
• If no token is found, prompts for credentials inside Neovim.

Requirements

• Neovim ≥ 0.10 (uses vim.system and vim.uv)
• curl available in $PATH

Installation (lazy.nvim)

{
  "yourusername/jasper.nvim",
  config = function()
    require("jasper").setup({
      -- Global default inactivity timeout in minutes (can be overridden per project).
      -- inactivity_timeout = 10,
    })
  end,
}

Project configuration

Place a .jasper_config.json file at the root of the project (next to .git):

{
  "attivita_id": 12345,
  "inactivity_timeout": 10
}

Key	Required	Description
attivita_id	✅	Numeric ID of the Jasper activity (the value field returned by the API).
inactivity_timeout	❌	Minutes of inactivity before auto-pause. Defaults to 10.

How it works

1. On VimEnter, the plugin looks for .jasper_config.json by walking up from the current working directory.
2. If found, it reads the cached auth token from $XDG_CONFIG_HOME/jasper/token.json. If the token is missing or expired, it prompts for credentials.
3. It fetches the list of timers from Jasper and finds the one associated with attivita_id. If none exists, it creates one.
4. The timer is started. A libuv countdown is armed; after inactivity_timeout minutes of silence the timer is paused.
5. Any cursor movement or keystroke resets the countdown (and resumes the timer if it was paused).
6. On VimLeave the timer is stopped.