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

Settings → Setup check lists the repositories you committed to most recently, wherever they are, with the identity and push access each uses; Add there adds one in a click. See Setup check.

  1. Select New, then Repository task.
  2. 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.
  3. Select the checkout. It's saved as a project for future tasks. + Add a project…, the last choice in every Project list, opens the same finder.
  4. 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. It starts from the project's base branch as origin has it now, not from whatever branch your checkout is on:

  1. uuBright Console asks origin for its default branch (for example develop) and fetches just that branch into origin/develop, waiting up to 20 seconds.
  2. The task's branch starts from origin/develop, and pull requests target develop.

Your checkout is never changed: no branch is checked out, local branches such as develop aren't updated, and the task branch isn't set to track anything. Only the remote-tracking branch (origin/develop) moves, as it would with git fetch.

If origin can't be reached, the task starts from the last fetched origin/develop (or, with none, the local default branch) and shows a warning in its activity. A checkout with no origin remote starts from its committed HEAD, also with a warning.

The fetch never waits for input: Git and SSH can't prompt for a password or passphrase, and SSH runs in batch mode unless you set your own core.sshCommand or GIT_SSH_COMMAND. Use credentials that work without a prompt, such as a key in a running agent. If another fetch is updating the same branch at that moment, the task retries once.

Stays in your original checkoutAvailable in the task
Uncommitted, staged and untracked changesEverything committed on the base branch
Ignored files, such as .env and node_modulesShared Git history and repository config

#Choose the base branch

To start from a branch other than origin's default, open Setup for this project in the new-task form, enter a Base branch and select Save setup. A task created through the API can name its own baseBranch, which wins over the project's. A named branch that exists on origin is fetched the same way; otherwise a local branch, tag or commit by that name is used as it is.

The task's Details show the branch and commit it started from. Claude is told the base, and REPO_BASE_BRANCH holds it in the task's environment, so pull requests it opens, and those opened from the app, target that branch.

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 uuBright Console looks

By default uuBright Console discovers repositories under ~/src (on a Mac also ~/code, ~/Projects, ~/Developer and ~/GitHub), and two levels deep in other common folders: ~/Developer, ~/Projects, ~/code, ~/src, ~/workspace and ~/repos. Folders that don't exist are skipped quietly. Select Rescan repositories after adding a checkout.

Desktop and Documents. On Linux, ~/Desktop and ~/Documents are searched too, two levels deep. On a Mac, reading them makes macOS ask for permission, so uuBright Console doesn't look there by itself: in the finder, choose Look in Desktop and Documents on that Mac. It explains the prompt first, then macOS asks once; uuBright Console remembers the choice. If you said no, allow it later in System Settings → Privacy & Security → Files and Folders. To add just one folder there instead, use Choose folder… in the Mac app, or type its path. macOS may still ask once when uuBright Console first works in a folder on the Desktop or in Documents.

To scan other folders instead, set absolute paths in server.env and restart the service. They replace all of the folders above:

SHELL
CCR_CLOUD_REPO_ROOTS='/home/ubuntu/src:/srv/projects'

Discovery works offline and stays fast on large servers. It searches the configured folders three directory levels deep and the common folders two, returning up to 100 matching repositories and visiting up to 3,000 directories within an eight-second time limit. Typing a name or path searches the server again after a short pause; it can find repositories beyond the initial 100 results. Load more repositories adds the next page without clearing your search or previous results. Search is case-insensitive. If the scan is incomplete, the UI says so; use a more specific search or narrower discovery roots. It skips hidden folders, dependency and build folders (such as node_modules, vendor, target, dist and build), the Mac's Library, media and Applications folders, and symlinked directories, and it doesn't check for uncommitted changes.

#Add a repository by path

A checkout outside the search folders can be added by its path: in Find a repository on this server, type it under Or add a repository by path, for example ~/work/my-repo (~ is the server user's home folder), and select Add. In the Mac app connected to This Mac, Choose folder… opens the system folder dialog instead and adds the folder you pick, checked the same way. When nothing is found, the finder names the folders it searched.

The server checks the path before saving it as a project:

  • It needs host mode and the server owner token. A paired phone picks from the repositories found instead.
  • The folder must exist and be a Git checkout's top folder, not a subfolder.
  • Symlinks are resolved first, and the real folder is what's checked and saved, so a link can't later point the project somewhere else.
  • Outside the search folders, the folder must belong to the server user, and it can't be the home folder itself or /.

Tasks for a saved project keep working if you change CCR_CLOUD_REPO_ROOTS later; the same checks run again each time a task starts.

#Search and paging

Repository browsing uses a snapshot with a five-minute idle expiry, sorted by name across all roots. Load more repositories reads the next page from that snapshot without rescanning or running Git on earlier pages. Checkouts created after the snapshot appear when you select Rescan repositories. Active reads extend its lifetime. If it expires, searches refresh automatically; Load more restarts from a fresh first page instead of mixing two lists. Discovery snapshots are held only in server memory.

Search matches checkout names and paths relative to each configured root, so a root folder name or username does not match every repository. You can also enter an absolute path or a ~/ path. Server searches are cancelled when superseded; metadata is cached for that snapshot and inspected with at most four concurrent Git operations. Cached searches do not wait for another directory scan. The eight-second traversal and 3,000-directory limits bound snapshot discovery; Git metadata is read only for the requested page, with a timeout per command.

#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.

  1. In New → Repository task, select the project.
  2. Open Setup for this project, enter the script (for example npm ci) and any environment variables as NAME=value lines, 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 uuBright Console, 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.

  1. Select New, then Repository task, then + Add by URL.
  2. Enter a project name and the clone URL.
  3. Select Check access & save project.

Choose the URL form that matches the credential your server already has:

Credential on the serverClone URL
SSH keygit@github.com:OWNER/REPO.git
HTTPS credential helperhttps://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:

ResultMeaning
Repository readableA read-only Git request to this exact URL succeeded.
Git commit identityGit has an author name and email for commits.
GitHub APIgh api user works. Needed only for GitHub API and pull request actions.
Push accessNot 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:

SHELL
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:

    SHELL
    git config --global user.name "Your Name"
    git config --global user.email "you@example.com"

See Command line for every option.

#Next steps