Working across multiple repos with Claude Code (desktop app)

Working across multiple repos with Claude Code (desktop app)

Draft for colleagues (e.g. Fae). Written 2026-10-01. Some UI details may differ in your version of the app; check against what you see and fix this guide.

The core idea

Your tasks and files live in several places: GitHub issues, Beads (in a repo), and files in repos. Claude can reach them in three different ways. Pick the one that matches the job.

ModeWhere Claude runsSees files?Sees GitHub issues?Beads (bd)?
A. Local session, repo clonedYour computerYes, on disk, and fastYes, via gh / GitHub (needs login)Yes, if bd is installed locally
B. Local session, no cloneYour computerNo (only what's online)Yes, via GitHubNo: Beads lives in the repo files
C. Cloud sessionA cloud VM that clones the repo(s) for youYes, inside the VMYesOnly if you tell Claude to install bd; Dolt sync errors can be ignored

Rule of thumb: working on files or Beads, clone the repo (A) or use the cloud (C). Only asking "what GitHub issues am I assigned to?", you can run without cloning (B).

Two kinds of question

  1. Overview ("what's my week?", "what's been going on?"): start from the central index in the planning repo. It lists initiatives, their repos, and where their tasks live. Tell Claude: read the index, then check each initiative's tracker (GitHub issues and/or Beads) for items assigned to me.
  2. Focused work ("I'm working on the website design"): open a session in just that repo or folder (e.g. design). No need to load anything else. Ask: show me the tasks here.

Step by step in the desktop app

  1. Get the repos locally (once). Ask Claude: "clone life-itself/ops and life-itself/planning into ~/src/life-itself using gh". It will run gh repo clone. You need GitHub access and to be signed in (gh auth login). Keep them up to date with "pull the latest".
  2. Start a session in a repo. In the Code tab, choose the repo folder as the working folder. Claude then reads and searches those files directly (much faster than going over the network).
  3. Work across several repos. Either start the session in a parent folder that contains the clones, or add extra folders to the session, or use the cloud option and select multiple repos.
  4. Find your tasks. Example prompts:
    • "In this repo, list open Beads assigned to me (bd list --assignee <my email>)."
    • "Search GitHub issues in life-itself/ops assigned to me."
    • "Check both Beads and GitHub issues in ops and give me one list."
  5. Cloud sessions. Choose the cloud option and select the repos. Claude clones them into a sandbox VM, works there, and saves changes back through branches or pull requests. To use Beads there, say: "install the bd (Beads) command line tool, then list my tasks". Ignore Dolt sync errors.
  6. Save work back. Changes on a local clone need commit and push (ask Claude to do it, via a branch and PR if the repo expects that).

Common gotchas

  • "It can't see my files": the repo isn't cloned, or you started the session in the wrong folder.
  • "No Beads found": Beads only works where bd is installed and the repo has a .beads folder. Locally, install bd; in the cloud, ask Claude to install it.
  • Stale local copy: pull before you start.
  • Two trackers: during the transition, check both GitHub issues and Beads.
Edit this page

Links to this page:

  1. Writing briefings, guides and briefs
Built with LogoFlowershow