Claup Documentation

Intro

Claup is a macOS app for browsing and organizing Claude Code sessions (Claude Clippings).

Features:

• Hierarchical display with projects, sessions and exchanges
• Nicely formatted display
• Annotate and/or tag exchanges
• User-editable tag names and colors
• Search/filter by text and/or tag
• Deep-linking URL support

and much more.

Overview

Central to Claup is the Viewer Window, with a navigation area on the left and the content on the right. You can open multiple viewer windows for any of these items:

Root  ⏵ Project ⏵ Session ⏵ Exchange

The Root is the Claud Code directory (.claude/projects) or the Xcode Claude Agent directory (~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/projects).

An Exchange is defined by a user input and the resulting Claude responses.

A Claup viewer can start at:

• Basic viewer (⌘N): This shows Claude Code and/or the Xcode Claude Agent directories. If you have both it will show both, otherwise it will just focus on the one you have.
• Root View: Same as above, but specific to either Claude Code or Claude Agent.
• Project: all sessions for a specific project (directory).
• Exchange: A specific exchange in a session.

The viewer has 2 main sections: the outline view on the left showing the structure, and a document view on the right showing session data. In addition to that the view can show a search/filter UI at the top (toggle via ⌘F or from the menu: Edit/Find/Find...). And finally there is an overlay view to modify assign tags and add/edit annotations. There is an annotation button to the right of each exchange, it is either gray or purple, depending on if an annotation is set. Clicking that button brings up the overlay.

In the above screenshot we see:

1. The search/filter UI, see below for a detailed description.
2. The favorite icon/toggle, click to add or remove this view to the favorites section (Menu: File/Open Recent/)
3. The annotation button. Gray (as shown) when there is no annotation yet, purple otherwise. Click to bring up the tags and annotation editor (4).
4. The tags and annotation editor. Click any of the checkboxes to toggle that tag, or edit teh annotation in the text area at the bottom of that view.
5. The annotation/tags summary: here you can see in one glance what tags are set im an exchange, session or project. The outline changes color to indicate the presence of annotations.
6. User input: to make it easy to d=find while scrolling user input has a slightly colored background.
7. The window title shows what we are browsing the Claude project inside the Claude Code directory.

Most items have context menus with a variety of functionality.

Navigation Details

Navigation Area

• Click a session in the sidebar to view it
• Click an exchange (question/answer pair) to scroll to it in the content view
• Double-click a session or folder to open it in a new window
• Hold Option and click an exchange to view just that exchange

When the navigation area is in focus you can also use the arrow keys (up, down, left, right) to navigate.

Expanding/Collapsing

• Click the disclosure triangle to expand or collapse roots, projects and sessions
• Holding Option while clicking the disclosure triangle expands or collapses all items inside
• Sessions expand to show individual exchanges

Working with Code Blocks

Tool use results (file edits, command output, etc.) can be folded to reduce clutter.

• Click the triangle (▶/▼) next to a tool result to fold or unfold it
• Option+click any fold triangle to fold/unfold all code blocks at once

Tagging and Annotations

You can tag exchanges with labels and add personal annotations to help find them later.

Adding Tags

1. Click any tag badge on an exchange, or right-click the exchange
2. Check/uncheck tags in the popover
3. Tags are saved automatically

Adding Annotations

1. Click a tag badge or the annotation badge on an exchange
2. Type your notes in the text area
3. Annotations are saved automatically when you click away

Filtering by Tags

Use the filter controls in the toolbar to show only exchanges with specific tags.

Finding Text

Filter sessions and exchanges by text, tags, or both — combine them to pinpoint the exchange you want.

• Press Cmd+F to open the find bar
• Type your search term and press Enter or click the arrows
• Press Escape to close the find bar
• Use Cmd+G / Shift+Cmd+G for next/previous match
• Use Cmd+E to use the current selection as the search term

Printing

From the menu select File > Print (or Cmd+P) to open the current session in your default web browser with the print dialog ready. The browser handles pagination and print preview as well as exporting as PDF.

Favorites

When you have a window for a project or session that you look at frequently, you can mark the window as Favorite by clicking the heart icon in the top-right corner of the window. Claup will then remember that location in the menu: File/Open Recent, in the Favorites section near the bottom.

Display Options

Session Titles

The appearance of session titles can be controlled via the session context menu:

• File name
• Start Date
• Last Changed
• First Prompt
• Last Prompt

The "Use relative Time" flag will make Start Date or Last Changed show relative times like 2 hours ago.

Scroll Behavior

By default, opening a session scrolls to the most recent exchange. This can be configured in Settings available from the menu (Claup/Settings...*) or using the shortcut ⌘,.

Keyboard Shortcuts

Study the menu to discover the available keyboard shortcuts.

Tips

• The content view updates live when a session is modified externally
• Visible exchanges are highlighted in the sidebar as you scroll
• Code blocks use syntax highlighting for most programming languages
• The app supports dark mode automatically based on system settings

Avoid Losing Old Transcripts

Claude Code auto-purges transcripts older than cleanupPeriodDays (default: 30). To keep more history, raise it in ~/.claude/settings.json:

{ "cleanupPeriodDays": 365 }

You can also use /update-config to set this.

Debug/Research mode

Sometimes it may be useful to see an exchange's individual elements as they are logged by Claude, and even the raw json Claude uses to describe them. To enable this mode execute this line in a terminal window:

open 'clp://?dataDebugMode=1'

Any session expanded after that point (toggle expansion off/on if you are already looking at the desired session) will now show an additional hierarchy for each exchange, showing all the Claude messages relating to the exchange. By default when you select those messages they just show the output they contribute to the normal display, and for many messages taht may be nothing. However if you hold the Command modifier down while selecting the message (or navigating via the arrow keys), Claup will show you the underlying json logged by Claude.

Tracking Development build

By default, once you have installed a development build of Claup, the auto-updater will track the development builds. If you do not want that much change and go back to tracking the main releases only, execute this line in a terminal window:

defaults write com.bitart.Claup CLPDevChannel -bool false

URL scheme support

Many items in the Claup navigation area offer Copy URL in their context menus. These URLs can be used in your local notes or in the browser to bring you back to exactly that item later. But please note that these URLs will only work on the machine and user account on which they were produced, so you can't use them to share information with others.

Also those links may expire when the transcripts they point to are purged, see (Avoid Losing Old Transcripts)[].

Opening Claude Code data from non-default locations

You may use a tool which in turn uses Claude but stores project data in a custom directory. You can still use those in Claude: Find the project directory (similar ~/.claude/projects), and open it in Claude from the command line like so:

open 'clp://<path_to>/projects'

replacing <path_to> with the full path where the projects directory can be found. Mark the resulting window as Favorite by clicking the heart icon in the top-right corner of the window. Claup will then remember that location in the menu: File/Open Recent, in the Favorites section near the bottom.