---

Table of Contents

• Quick Start
  • VS Code
  • Neovim
  • CLI
• Features
• Usage Examples
• Language-Aware Detection
• Configuration
  • VS Code Settings
  • Neovim Settings
• Editor Commands
  • VS Code Commands
  • Neovim Commands
• Contributing
• License

---

Quick Start

VS Code

1. Install TimeScope (rifen.rifen-timescope) from the VS Code Marketplace or via the Command Palette (Ctrl+P / Cmd+P):

   ext install rifen.rifen-timescope
   

2. Open any supported file and hover over any duration (e.g. timeout = 900 or 3000 in setTimeout(fn, 3000)). The human-readable duration displays instantly in a hover tooltip.

Neovim

Requirements: Neovim ≥ 0.7 and Node.js ≥ 18.

lazy.nvim:

{
  'rifen/timescope',
  tag = 'nvim-v0.2.30', -- latest nvim-v* tag; or branch = 'nvim' for rolling
  opts = {
    format = 'compact',
  },
}

packer.nvim:

use {
  'rifen/timescope',
  tag = 'nvim-v0.2.30',
  config = function()
    require('timescope').setup({
      format = 'compact',
    })
  end,
}

The nvim-v* tags are published by CI on every release and ship the prebuilt Node.js bridge — no clone or build required. See the Releases page for the latest tag. To run from a source checkout instead, see packages/nvim/README.md.

Move the cursor over any numeric duration to view the formatted duration rendered as inline virtual text.

CLI

Run TimeScope directly from your terminal using npx:

# Parse a numeric duration or math expression
npx @rifen/timescope-core parse "60 * 60 * 24"

# Scan a source file or directory for durations
npx @rifen/timescope-core scan ./src

---

Features

• Smart detection — Infers units from variable names, comments, and identifiers (e.g., timeout, interval, delay, ttl, retention).
• Language-aware rules — Recognizes language standard library conventions (setTimeout → ms in JS/TS, time.sleep → seconds in Python, time.Sleep → nanoseconds in Go).
• Expression evaluation — Computes compound expressions like 60 * 60 * 24 → 1d.
• Flexible formatting — Choose between compact (15m), verbose (15 minutes), or combined (both).
• Context hints — Displays inference clues alongside formatted times (e.g., keyword: "timeout" (javascript)).
• Zero runtime dependencies — Lightweight and fast in both editors.
• Cross-editor consistency — Identical detection engine across VS Code, Neovim, and CLI.

---

Usage Examples

# Python
timeout = 900              # → "15m"
retry_delay = 5000         # → "5s"
cache_ttl = 60 * 60 * 24   # → "1d"
time.sleep(30)             # → "30s" (language-aware)

// JavaScript / TypeScript
setTimeout(fn, 3000);       // → "3s" (language-aware)
setInterval(fn, 5000);      // → "5s" (language-aware)
const timeout = 30000;      // → "30s" (context clues)

// Go
timeout := 15 * time.Second  // → "15s"
time.Sleep(2 * time.Second)  // → "2s" (language-aware)

# YAML
timeout: 300          # → "5m"
interval: 3600000     # → "1h"
ttl: 86400            # → "1d"

---

Language-Aware Detection

TimeScope detects the active language and adapts its unit inference to standard library conventions:

Language	Recognized Patterns	Inferred Unit
JavaScript / TypeScript	setTimeout, setInterval, setImmediate, requestAnimationFrame	Milliseconds
Python	time.sleep	Seconds
Go	time.Sleep, time.After, time.Tick	Nanoseconds
Rust	std::thread::sleep, tokio::time::sleep	Milliseconds
Java	Thread.sleep	Milliseconds
Other Languages	Common keywords: timeout, interval, delay, duration, ttl, sleep, wait, cache, etc.	Context Heuristics

---

Configuration

TimeScope requires zero configuration by default, but provides granular options to customize behavior.

VS Code Settings

Configure in the VS Code Settings UI or add directly to settings.json:

{
  "timescope.enabled": true,
  "timescope.format": "compact",           // "compact" | "verbose" | "both"
  "timescope.defaultUnit": "seconds",      // "seconds" | "milliseconds" | "microseconds" | "nanoseconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years" | "auto"
  "timescope.minValue": 1,
  "timescope.maxValue": 31557600000,       // Ignore values above ~1000 years in ms
  "timescope.contextClues": true,          // Use variable names and comments to infer units
  "timescope.fileTypes": ["*"]             // Glob patterns for active file types
}

Neovim Settings

Configure through require('timescope').setup({...}) or the opts table in lazy.nvim:

require('timescope').setup({
  enabled = true,
  format = 'compact',              -- 'compact' | 'verbose' | 'both'
  defaultUnit = 'seconds',         -- 'seconds' | 'milliseconds' | 'microseconds' | 'nanoseconds' | 'hours' | 'days' | 'weeks' | 'months' | 'years' | 'auto'
  minValue = 1,
  maxValue = 31557600000,
  contextClues = true,
  debounceMs = 150,                -- Cursor move debounce delay in ms
})

---

Editor Commands

VS Code Commands

Access these from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command	Action
TimeScope: Toggle Enabled	Toggle the hover provider on or off
TimeScope: Dump Settings to Output	Print active configuration to the TimeScope output channel
TimeScope: Log Hover Target	Inspect token and AST context under the active cursor

Neovim Commands

Command	Description
:TimeScopeEnable	Enable the hover provider
:TimeScopeDisable	Disable the hover provider and clear virtual text
:TimeScopeToggle	Toggle the hover provider on or off
:TimeScopeSettings	Display active configuration in the command window
:TimeScopeReload	Clear virtual text and force refresh

---

Contributing

We welcome contributions!

• Read our Contributing Guide for local development setup, workflow standards, and testing procedures.
• Please review our Code of Conduct before engaging in discussions or opening issues.
• Security disclosures should follow the instructions in SECURITY.md.

---

License

This project is licensed under the MIT License.