Cc Session Tracker

cc-session-tracker

A Claude Code plugin that tracks your sessions over time — with human-readable titles, git context, real token usage, and easy reconnect.

What it does

• Asks "What are we working on?" at the start of every fresh session and saves your answer as the session title via the /cc-session-tracker:title slash command. No API calls, no guessing from the first prompt.
• Tracks git repo, branch, and worktree per session.
• Accumulates real token usage by parsing the session transcript on every Stop event (one write per turn, not per tool call).
• Persists up to 50 sessions (configurable) under $XDG_DATA_HOME/cc-session-tracker/session-store.json.
• Lists, searches, renames, prunes, and reconnects to any past session — via tmux reattach if the session is still alive, otherwise claude --resume <id> in the same cwd.

Install

Option A — as a Claude Code plugin (recommended)

One-time marketplace add, then install:

/plugin marketplace add audenaert/utils
/plugin install cc-session-tracker@audenaert-utils

That's it. The plugin registers its hooks, wires up the /cc-session-tracker:title slash command, and on the next SessionStart symlinks cc-sessions and cc-set-title into ~/.local/bin so they're available from your interactive shell (make sure ~/.local/bin is on your PATH). To opt out of the symlinks, set CC_TRACKER_NO_SYMLINK=1.

Option B — standalone install

For users who'd rather not touch the plugin system:

git clone https://github.com/audenaert/utils.git
cd utils/cc-session-tracker
./install.sh

Or one-line:

curl -fsSL https://raw.githubusercontent.com/audenaert/utils/main/cc-session-tracker/install.sh | bash

Then add $HOME/.local/bin to your PATH if it isn't already.

Usage

cc-sessions                     List 10 most recent sessions
cc-sessions -a                  List all sessions
cc-sessions <N>                 Reconnect to session [N] (0 = newest)
cc-sessions show <N>            Full detail: tokens, git, timestamps
cc-sessions search <query>      Search title / dir / branch / repo
cc-sessions rename <N> <text>   Rename session [N]
cc-sessions rm <N>              Remove session [N]
cc-sessions pick                Interactive fzf picker (needs fzf)
cc-sessions clean               Prune sessions older than $CC_TRACKER_MAX_AGE_DAYS
cc-sessions help                Show full help

Inside a Claude Code session:

/cc-session-tracker:title Refactor auth module to use JWT

Reconnecting

cc-sessions <N> tries three paths in order:

1. Reattach to the original tmux session if it's still alive.
2. Spawn a new tmux session running claude --resume <id> in the original cwd — but only if you're already inside tmux.
3. Plain terminal resume: cd <cwd> && claude --resume <id> in the current terminal.

So tmux is optional: the tracker works fine without it, you just lose the "reattach to a live pane" step.

Shell function (optional, tmux users)

Add to ~/.bashrc or ~/.zshrc:

cc() {
  local s="cc-$(date +%s)"
  if [ -n "$TMUX" ]; then
    # Already inside tmux — create a detached session and switch to it
    # (avoids tmux's nested-session warning and keeps the parent running).
    tmux new-session -d -s "$s" claude && tmux switch-client -t "$s"
  else
    tmux new-session -s "$s" claude
  fi
}

Ctrl-b d detaches back to whatever you were in. Jump between sessions later with cc-sessions <N> or tmux switch-client -t <name>.

Configuration

All env vars are optional.

Variable	Default	Purpose
CC_TRACKER_HOME	$XDG_DATA_HOME/cc-session-tracker	Store directory
CC_TRACKER_MAX_SESSIONS	50	Hard cap on stored sessions
CC_TRACKER_MAX_AGE_DAYS	30	Cutoff used by clean
CC_TRACKER_BIN_DIR	$HOME/.local/bin	Where cc-sessions / cc-set-title symlinks are created
CC_TRACKER_NO_SYMLINK	unset	Set to 1 to disable automatic symlink creation on SessionStart

Files

Plugin layout:

cc-session-tracker/
├── .claude-plugin/plugin.json
├── hooks/hooks.json              SessionStart (startup), Stop, SessionEnd
├── scripts/
│   ├── _lib.sh                   Shared helpers (store path, flock, git)
│   ├── session-start.sh          Inject title prompt + register session
│   ├── stop.sh                   Parse transcript, update tokens + git
│   └── session-end.sh            Mark ended
├── commands/title.md             /cc-session-tracker:title slash command
├── bin/
│   ├── cc-sessions               Main CLI
│   └── cc-set-title              Shim used by the slash command
├── install.sh                    Standalone installer (non-plugin users)
└── tests/smoke.sh                Non-interactive smoke tests

Runtime state (XDG-compliant):

$XDG_DATA_HOME/cc-session-tracker/
├── session-store.json            All session data (capped)
└── session-store.lock            flock file for atomic writes

How token tracking works

Every Stop hook invocation reads the session's JSONL transcript and sums the usage fields from every assistant message. The result is written to the store entry. Summing the whole file each turn is idempotent, robust to dropped events, and cheap enough — transcripts stay small.

PostToolUse is intentionally not used: writing the store on every tool call is both wasteful and racy, and the PostToolUse payload doesn't carry token usage anyway.

Requirements

• Required: bash, jq, git
• Recommended: flock (Linux default; macOS: brew install flock)
• Optional: tmux (for reattach), fzf (for cc-sessions pick)

Development

Run the smoke tests:

bash tests/smoke.sh

Test the plugin locally without installing:

claude --plugin-dir ./cc-session-tracker

Notes

• Only the startup SessionStart matcher is registered. Resumes/clears/compacts keep the existing store entry untouched (beyond a last_seen bump).
• The title prompt is injected via hookSpecificOutput.additionalContext, the correct schema for SessionStart hooks.
• Hook registration merges array-by-array and is idempotent — re-running install.sh will not duplicate or clobber existing user hooks.