timelog

Claude Code Timelog

Automatic time tracking plugin for Claude Code. Logs session activity as JSONL for timesheet reconstruction.

Use it to:

• Build client timesheets — see how long you spent on each project
• Track your own time across projects and tickets without manual timers
• Generate weekly/monthly reports for invoicing or personal review
• Audit which tickets consumed the most Claude usage

What it tracks

• Session start/end with timestamps
• Every prompt you submit (first 500 characters)
• Project name from file paths, git repository root, or working directory
• Ticket/issue number from git branch name or prompt text
• Model used for the session

All data stays local. Nothing is sent to external services.

Quick start

From marketplace (recommended)

/plugin marketplace add RemoteCTO/claude-plugins-marketplace
/plugin install timelog

Manual

git clone https://github.com/RemoteCTO/claude-code-timelog.git
claude --plugin-dir ./claude-code-timelog

That's it. The plugin starts logging immediately with sensible defaults:

• Project = git repository name
• Tickets = Jira/Linear IDs from branch names (e.g. BAN-123, PROJ-456)
• Logs written to ~/.claude/timelog/

No configuration needed for basic use.

Verify it's working

After your first prompt, check that a log file was created:

ls ~/.claude/timelog/

You should see a file named with today's date (e.g. 2026-02-13.jsonl). If not, check the plugin is installed with /plugin.

To import time from previous sessions:

/timelog:backfill

Set up project detection

If you launch Claude Code from a parent directory (e.g. ~/projects/) rather than individual project directories, all time gets lumped under one project name. Fix this by asking Claude:

"Help me set up my timelog projectPattern — here's my directory structure"

Claude will examine your directories and generate the right regex for your ~/.claude/timelog/config.json. See Project detection for details.

CLI usage

The claudelog command lets you run reports and backfills from any terminal — no active Claude Code session needed.

claudelog                                # default report (--week)
claudelog report --month --timesheet     # explicit flags
claudelog backfill                       # import history
claudelog --help                         # show usage

Running claudelog with no arguments runs a default report. Configure the default via defaultReport in config.json:

{
  "defaultReport": ["--month", "--timesheet"]
}

Falls back to ["--week"] if not set.

Adding to PATH

The plugin installs to a versioned cache directory. Create a wrapper script that automatically finds the latest version:

cat > ~/.claude/bin/claudelog << 'WRAPPER'
#!/usr/bin/env bash
set -euo pipefail

PLUGIN_DIR="$HOME/.claude/plugins/cache"
PLUGIN_DIR+="/remotecto-plugins/timelog"

LATEST=$(
  ls -1 "$PLUGIN_DIR" 2>/dev/null \
    | sort -V | tail -1
)

if [ -z "$LATEST" ]; then
  echo "timelog not installed" >&2
  exit 1
fi

exec node \
  "$PLUGIN_DIR/$LATEST/bin/claudelog" "$@"
WRAPPER
chmod +x ~/.claude/bin/claudelog

~/.claude/bin is on PATH if you use Claude Code (added by the installer). The wrapper survives plugin version bumps — no need to update it after upgrading.

Getting the best results

How project detection works

The plugin needs to know which project you're working on. It tries three methods in order:

1. File path regex (projectPattern) — extracts the project name from file paths Claude touches during the session.
2. Git root (projectSource: "git-root") — uses the git repository directory name.
3. Working directory (projectSource: "cwd") — uses the directory name you launched from.

If you launch Claude Code from a project directory (the most common case), methods 2 and 3 work automatically. No config needed.

If you launch from a parent directory (e.g. ~/projects/), everything gets lumped under one name. Set projectPattern to fix this — see Project detection.

How ticket detection works

Tickets are detected automatically from:

1. Git branch name — feature/BAN-123 extracts BAN-123
2. Prompt text — "Fix BAN-123 login bug" extracts BAN-123

The default pattern matches Jira, Linear, Shortcut, and similar formats: PROJECT-123. To add custom patterns (GitHub issues, internal IDs), see Ticket detection.

Tips for accurate tracking