session-tracker

session-tracker

Track Claude Code session duration with automatic timestamps.

Features

• SessionStart hook - saves timestamp in plugin directory, exports CLAUDE_SESSION_FILE env var
• SessionEnd hook - appends completed sessions to a JSONL history log for worklog reports
• Active vs idle time - UserPromptSubmit and Stop hooks record turn boundaries; gaps longer than SESSION_IDLE_THRESHOLD_SECONDS (default 300s) are counted as idle, so you can see real working time vs the AFK gaps
• Persistent session files - session data survives session end so you can track hours later
• /session-tracker:session-status skill - check elapsed time, plus today's accumulated total
• /session-tracker:session-history command + skill - review past sessions filtered by date or project
• /session-tracker:reset-session command - reset the timer to zero
• Auto-reset on /clear - clearing the session automatically restarts the timer
• Status line snippet - optional integration for live timer display

Installation

Option 1: From Marketplace (recommended)

# Add as a standalone marketplace plugin
claude plugin marketplace add aguinaldotupy/claude-session-tracker

# Install the plugin
claude plugin install session-tracker@aguinaldotupy --scope user

# Restart Claude Code to activate hooks

Option 2: Local Install (development)

git clone https://github.com/aguinaldotupy/claude-session-tracker.git
claude --plugin-dir ./claude-session-tracker

Option 3: Manual Install

# Clone into the plugins directory
git clone https://github.com/aguinaldotupy/claude-session-tracker.git \
  ~/.claude/plugins/marketplaces/claude-session-tracker

Then enable in ~/.claude/settings.json:

{
  "enabledPlugins": {
    "session-tracker@claude-session-tracker": true
  }
}

Verify Installation

Inside a Claude Code session:

/plugin

Navigate to the Installed tab - session-tracker should appear.

Usage

Check Session Time

Type /session-tracker:session-status or ask naturally:

• "how long is this session?"
• "quanto tempo de sessao?"
• "session duration"

Example output:

Session: 1h 23m (active: 48m, idle: 35m, started at 14:30)

Idle is the sum of gaps between Claude finishing a turn (Stop) and your next prompt that exceeded SESSION_IDLE_THRESHOLD_SECONDS (default 300). Tune it by setting the env var, e.g. export SESSION_IDLE_THRESHOLD_SECONDS=180 for a stricter 3-minute cutoff.

Reset Timer

Type /session-tracker:reset-session or ask naturally:

• "reset the session timer"
• "reiniciar o tempo"
• "restart timer"

The timer resets to zero from the current time. The /clear command also resets the timer automatically.

Session History & Worklog

Each time a session ends, the SessionEnd hook appends one JSON line to ~/.claude/session-env/history.jsonl with the session id, start/end timestamps, duration in seconds, project directory, and exit reason.

Query it with /session-tracker:session-history or ask naturally:

• "quanto trabalhei hoje?"
• "worklog da semana"
• "session history last 7 days"
• "histórico de sessões nesse projeto"

The command accepts an optional date filter (today, yesterday, 7d, 30d, or YYYY-MM-DD..YYYY-MM-DD) and an optional --project <substring> filter. It prints a markdown table of sessions plus a total. See commands/session-history.md and skills/session-history/SKILL.md for details.

/session-tracker:session-status also reports today's accumulated total (previous completed sessions plus the current live elapsed).

Issue Tagging & Worklog

Each finished session is tagged with an issue key (e.g. LIN-456, ABC-123) so the worklog can group time per ticket.

Resolution order used by the SessionEnd hook:

1. Explicit tag written via /session-tracker:tag LIN-456 — stored at ~/.claude/session-env/<session_id>/issue-tag.
2. Branch heuristic — the first [A-Z][A-Z0-9_]+-[0-9]+ match on the current git branch (works with common conventions like feat/LIN-456-title).
3. Empty if nothing resolves. Older entries without issue_key are treated as empty.

Tag the current session mid-flight:

/session-tracker:tag LIN-456
/session-tracker:tag --clear

Forgot to tag? Retroactively fix any session that already ended without an issue key:

/session-tracker:tag-session abc12345 LIN-456     # tag an old session by id prefix
/session-tracker:tag-session abc12345 --clear     # blank the tag again

The worklog flow itself also offers inline retroactive tagging — when it spots an "Untagged" bucket, it walks you through each session and lets you tag, batch-tag, or skip before anything is posted to your MCP.

Then post your worklog to whichever issue tracker MCP you have connected: