Work with repositories
Give a task a repository to work in. In host mode you can pick a checkout that's already on your server, or add a repository by its clone URL. Either way, every task gets its own branch and workspace, so your original checkout is never changed.
#Use a checkout already on the server
- Select New, then Repository task.
- Use Find a repository on this server and search by name or path. It opens automatically when you have no saved projects; otherwise, expand it to find another checkout.
- Select the checkout. It's saved as a project for future tasks.
- Describe a small task, including how Claude should check its work, and start it.
#What the task gets
Each task gets a separate Git worktree on a new branch, ccr/SESSION_ID, created from the checkout's committed HEAD. ccr-cloud doesn't fetch first.
| Stays in your original checkout | Available in the task |
|---|---|
| Uncommitted, staged and untracked changes | Everything committed at HEAD |
Ignored files, such as .env and node_modules | Shared Git history and repository config |
Install dependencies and add environment files in the task's workspace if it needs them. A repository needs at least one commit before a task can start in it.
Stop and Resume keep the same worktree and conversation.
Deleting a task deletes its worktree, including uncommitted task files. Commit or copy anything you want to keep first. The original checkout and the task's branch remain.
Worktrees separate files, not permissions: a task can still read anything your server user can.
#Change where ccr-cloud looks
By default ccr-cloud discovers repositories under ~/src. Select Rescan repositories after adding a checkout. To scan other folders, set absolute paths in server.env and restart the service:
CCR_CLOUD_REPO_ROOTS='/home/ubuntu/src:/srv/projects'Discovery works offline and stays fast on large servers. It searches three directory levels deep, up to 100 repositories and 3,000 directories, within a time limit. It skips hidden folders, common dependency folders and symlinked directories, and it doesn't check for uncommitted changes.
#Prepare each task with a setup script
Every task starts from a clean checkout, so dependencies and generated files aren't there yet. Give the project a setup script, and each new task runs it in its workspace before Claude starts.
- In New → Repository task, select the project.
- Open Setup for this project, enter the script (for example
npm ci) and any environment variables asNAME=valuelines, then select Save setup.
The script runs once per task, as the server user, with the task's workspace as the current folder. Its output appears in the task's activity. If it fails or runs longer than 15 minutes, Claude starts anyway and the activity says why; a failed setup runs again when you resume the task. Changing the setup affects new tasks only.
Keep secrets out of setup variables: anyone with the access token can read them. Names that ccr-cloud, Claude Code, Git or the system rely on, such as PATH, ANTHROPIC_*, GIT_* or NODE_OPTIONS, are refused. Dependency caches shared between tasks aren't available yet.
#Add a repository by URL
Use this for a repository that isn't on the server yet, or in Docker mode, which always clones.
- Select New, then Repository task, then + Add by URL.
- Enter a project name and the clone URL.
- Select Check access & save project.
Choose the URL form that matches the credential your server already has:
| Credential on the server | Clone URL |
|---|---|
| SSH key | git@github.com:OWNER/REPO.git |
| HTTPS credential helper | https://github.com/OWNER/REPO.git |
An SSH key doesn't authenticate an HTTPS URL, and the reverse is also true.
#What the access check tells you
The check runs as the server user, without prompts and with time limits. It never clones or pushes. Each result is reported separately:
| Result | Meaning |
|---|---|
| Repository readable | A read-only Git request to this exact URL succeeded. |
| Git commit identity | Git has an author name and email for commits. |
| GitHub API | gh api user works. Needed only for GitHub API and pull request actions. |
| Push access | Not verified. Nothing is written. |
The result is a snapshot. If credentials change, add the repository again to rerun the check. In Docker mode the check runs inside the session image, not on the host.
#Set up GitHub access
Only do this if a check fails or you need GitHub API actions. Run these on the server, as the service user:
npm run github # diagnose identity, API login and SSH
npm run github -- --repo git@github.com:OWNER/REPO.git # check one exact URL
npm run github -- --setup --protocol ssh # print SSH setup steps--setup only prints steps. It never creates keys, logs in or changes Git configuration. A few things to know:
- Verify a new Git host's fingerprint once in the server terminal; unattended checks can't answer that prompt.
- A forwarded SSH agent disappears when your SSH login ends. Use credentials that stay available on the server.
Set a commit identity if the check reports none:
SHELLgit config --global user.name "Your Name" git config --global user.email "you@example.com"
See Command line for every option.