Getting started¶
Install¶
The recommended way is uv, which fetches Python 3.12 or later automatically if needed. pipx and pip work too.
See Update for getting new versions.
These need Python 3.12 or later already installed.
Without pipx, install it into a virtual environment with pip:
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 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:
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,jkto step through sessions,Enterto open the transcript,Escto 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.