Skip to content

Getting started

Install

The recommended way is uv, which fetches Python 3.12 or later automatically if needed. pipx and pip work too.

uv tool install cc-calendar
cc-calendar

See Update for getting new versions.

uvx cc-calendar

These need Python 3.12 or later already installed.

pipx install cc-calendar
cc-calendar

Without pipx, install it into a virtual environment with pip:

python3 -m venv .venv
.venv/bin/pip install cc-calendar
.venv/bin/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.

Linux, macOS and Windows are supported. On Windows the logs are read from %USERPROFILE%\.claude\projects\; one limitation: Copy resume command joins two commands with &&, which cmd and PowerShell 7 accept but Windows PowerShell 5.1 does not — there, replace the && with ;.

Update

Check which version you have with cc-calendar --version; the releases list what changed in each one. When a newer version is out, the top bar shows vX.Y.Z available next to the version, linking here, and the terminal prints a line about it. cc-calendar checks PyPI when it starts and once a day; --no-update-check turns this off.

uv tool upgrade cc-calendar

uv tool list shows the installed version. To install a given version, or to go back to one, use uv tool install cc-calendar==0.6.0.

If you installed v0.3.0 or earlier from GitHub, switch to the PyPI package once with uv tool install --force cc-calendar. uv tool upgrade works from then on.

uvx cc-calendar reuses the version it cached the first time. Ask for the latest one:

uvx cc-calendar@latest
pipx upgrade cc-calendar

In a virtual environment: .venv/bin/pip install --upgrade cc-calendar.

git pull
uv run cc-calendar

A running cc-calendar keeps serving the old version: stop it with Ctrl+C and start it again. The version it runs shows next to the logo in the top bar. Notes, tags, ratings and the search index are kept outside the installation, so they carry over.

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)
--search-index PATH File that keeps the full-text search index (default: see Full-text search)
--no-update-check Do not ask PyPI whether a newer version is out. Setting CC_CALENDAR_NO_UPDATE_CHECK=1 does the same. See Privacy
--version Print the version and exit

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 This week (Today, This month or This year, following the span) to come back.
  • Use the search box, the project filter and the status chips to narrow every view. With prompts only (on by default) hides sessions in which no prompt was sent. Totals and reports follow these filters. Tick Full text to search the whole transcripts, not just titles and prompts; see Full-text search.
  • 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, tags and ratings 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.