Skip to content

Getting started

Install

cc-calendar requires uv. uv fetches Python 3.12 or later automatically if needed.

uv tool install git+https://github.com/atinfinity/cc-calendar@v0.3.0
cc-calendar

git clone https://github.com/atinfinity/cc-calendar
cd cc-calendar
uv run cc-calendar

The server binds to 127.0.0.1 on a free port and opens your browser. It reads the logs under ~/.claude/projects/, so any session you have run with Claude Code shows up straight away.

Options

Option Description
--port N Listen on a specific port instead of a free one
--no-browser Do not open a browser window
--claude-dir [NAME=]PATH Read logs from another Claude Code config directory (default ~/.claude). Repeat it to show several directories in one calendar
--notes PATH File that keeps your session notes and tags (default: see Notes and tags)

Several config directories

Pass --claude-dir more than once to see sessions from several places together, such as ~/.claude directories synced from other machines or separate configs used with CLAUDE_CONFIG_DIR. Only the directories you list are read, so include ~/.claude to keep your local sessions:

cc-calendar --claude-dir ~/.claude --claude-dir ~/sync/laptop/.claude --claude-dir work=~/.claude-work

Each directory gets a name: the one you give with NAME=, otherwise local for ~/.claude, the parent folder for a path ending in .claude (laptop above), or the folder itself. Sessions show where they came from in the list (Source column and filter), the detail pane, the calendar tooltip and the CSV/JSON export (source), and Color by → Source colors them by directory. A session found in more than one directory is shown once, from the copy with the latest activity.

Finding your way around

  • Calendar / List at the top switches between the calendar and a sortable table of sessions.
  • Day / Week / Month / Year picks the span. Use ◀ ▶ to move and Today to come back.
  • Use the search box, the project filter and the status chips to narrow every view. Totals and reports follow these filters.
  • Click a session to open its detail pane. From the detail pane, open the transcript.
  • Summary, Tools and Copy report work on the displayed range.
  • Press ? for keyboard shortcuts: ← → to move, j k to step through sessions, Enter to open the transcript, Esc to close. See Keyboard shortcuts.

Notes and tags

Notes and tags you add to sessions are saved in one JSON file, keyed by session ID:

Platform Default location
macOS ~/Library/Application Support/cc-calendar/notes.json
Linux $XDG_DATA_HOME/cc-calendar/notes.json (~/.local/share/… when unset)
Windows %APPDATA%\cc-calendar\notes.json

Point --notes at another file to keep it somewhere else, such as a synced folder to share notes between machines; changes made to the file elsewhere are picked up. One file serves every --claude-dir. Notes stay in the file after Claude Code deletes a session's old log.