cc-pickerAbout cc-pickerGuideGitHub ↗
THE LITTLE USER GUIDE

Your projects.
Everything in its place.

From your first launch to a tidy project list.
Step by step, at your own pace.

Guide / Getting started

Up and running in a few steps.

You need Linux and a working Claude Code installation. cc-picker helps you start Claude in the right project folder.

1

Install once

Open a terminal and run these two lines, one after the other.

If window support is missing, the installer offers to install it, shows the command first and asks for your approval. If you decline, the terminal menu remains available.

$ git clone https://github.com/bruneler/cc-picker.git
$ cd cc-picker && ./install.sh
2

Open cc-picker

Find “cc-picker” in your application menu. Or enter cc-picker in a terminal.

3

Choose your first project

Select a folder from the list or choose “+ Create new project”. Claude Code starts right there.

Projects live in ~/claude-projects by default. You can configure additional project folders.
What gets installed? · Technical details

The launcher, application menu entry and icon are installed in your user directory. If no dialog tool is found, the installer offers kdialog on KDE or zenity elsewhere. It displays the exact command and runs it only after your approval. If installation is declined or fails, the terminal menu remains available. Without an interactive terminal or with CC_PICKER_NO_DEPS=1, it does not prompt. An unknown package manager results in manual installation guidance.

Guide / Choose a project

The right project. Within reach.

Recently used projects appear near the top. Pinned favourites stay first.

1

Choose and start

In the window, select a project and click “Start”. In the terminal menu, enter its number.

2

Narrow down the list

In the terminal, type part of the name. The window offers a search entry once you have eight projects.

3

Return to your last project

This short command opens the most recently used project:

$ cc-picker -
Direct launch and search tools · Technical details

cc-picker NAME accepts a unique name prefix. If fzf is installed, it handles terminal search. Use CC_PICKER_FZF=0 for the regular menu.

Guide / Create & clone

A good idea needs a folder.

Start empty, use a template, or download a project that already exists online.

1

Choose “Create new project”

Give your project a name. An existing project folder will not be overwritten.

2

Start fresh or download

Enter a Git address to clone a repository. Leave the field empty for a new project.

3

Choose a template if you like

The included standard template provides a file for project instructions to Claude and a Git ignore file. You can also choose an empty folder.

Your own templates · Technical details

Templates live in ~/.config/cc-picker/templates/. The {{PROJECT_NAME}} placeholder is replaced with the project name. Templates also run git init. For GitHub clones, user/repo is enough.

Guide / Continue sessions

Pick up where you left off.

If Claude Code has saved earlier sessions for your project, cc-picker offers three choices.

1

Start fresh

Open a new conversation in the same project folder.

2

Continue the last session

Pick up your most recent conversation.

3

Choose an earlier session

Open Claude Code’s session picker to resume an older conversation.

Choose from the command line · Technical details

Use -n for new, -c to continue, or -r to choose a session. For example: cc-picker -c my-project. Set a default with CC_PICKER_SESSION.

Guide / Keep things organised

Less clutter. More clarity.

Use “Manage projects” to keep your list tidy without losing your work.

1

Pin what matters

Favourites appear above recently used projects. You can also open projects directly in your editor or file manager.

2

Archive finished projects

Archived folders leave the regular list. They remain on disk and can be restored later.

Renaming a project changes its folder path. Claude Code cannot resume the old sessions under the new name in the same way.
Several project folders · Technical details

In ~/.config/cc-picker/config, set something like CC_PICKER_BASE=~/claude-projects:~/code. New projects go in the first folder. Each folder has its own .archive/.

Guide / Updates & help

Stay current. Keep going.

One command installs the latest published release. Your settings and project list are kept.

$ cc-picker --update
No window appears

The graphical picker needs zenity, kdialog or yad. If none is installed, the installer offers kdialog on KDE or zenity elsewhere. It shows the command and asks for your approval. You can run ./install.sh again from the downloaded cc-picker folder. If you decline or installation fails, cc-picker uses the terminal menu. Normal launches do not ask again. Open it directly with cc-picker --shell-mode.

My project is missing

Check that its folder is inside a configured project directory. Hidden folders are not shown. Restore archived projects through project management.

I want to report a bug

Include the output of cc-picker --version, your Linux distribution and the steps leading to the problem. Report security vulnerabilities privately using the channel in SECURITY.md.

cc-picker chooses the working folder. Claude Code’s own permissions determine which other files it can read or change.
Warranty and responsible use

cc-picker is provided without warranty. The warranty and liability provisions of the MIT License apply to the extent permitted by law. Back up important data regularly and review the permissions you grant to Claude Code.