Add clickable branch links and support for remote branch/PR checkout

- Branch names in UI are now clickable and link to GitHub
- Added --remote-branch option to checkout remote branches
- Added --pr option to checkout specific PRs by number
- Fixed shadow repo sync to preserve git-tracked files regardless of gitignore
- Updated documentation with shadow repo sync principles

Author: osolmaz

public/app.js

@@ -665,7 +665,30 @@ function updateGitInfo(data) {
   const prInfoElement = document.getElementById("pr-info");
 
   if (data.currentBranch) {
-    branchNameElement.textContent = data.currentBranch;
+    // Clear existing content
+    branchNameElement.innerHTML = "";
+    
+    if (data.branchUrl) {
+      // Create clickable branch link
+      const branchLink = document.createElement("a");
+      branchLink.href = data.branchUrl;
+      branchLink.target = "_blank";
+      branchLink.textContent = data.currentBranch;
+      branchLink.style.color = "inherit";
+      branchLink.style.textDecoration = "none";
+      branchLink.title = `View ${data.currentBranch} branch on GitHub`;
+      branchLink.addEventListener("mouseenter", () => {
+        branchLink.style.textDecoration = "underline";
+      });
+      branchLink.addEventListener("mouseleave", () => {
+        branchLink.style.textDecoration = "none";
+      });
+      branchNameElement.appendChild(branchLink);
+    } else {
+      // Fallback to plain text
+      branchNameElement.textContent = data.currentBranch;
+    }
+    
     gitInfoElement.style.display = "inline-block";
   }
 

src/cli.ts

@@ -80,7 +80,7 @@ program
   )
   .option("-n, --name <name>", "Container name prefix")
   .option("--no-push", "Disable automatic branch pushing")
-  .option("--no-pr", "Disable automatic PR creation")
+  .option("--no-create-pr", "Disable automatic PR creation")
   .option(
     "--include-untracked",
     "Include untracked files when copying to container",
@@ -89,6 +89,14 @@ program
     "-b, --branch <branch>",
     "Switch to specific branch on container start (creates if doesn't exist)",
   )
+  .option(
+    "--remote-branch <branch>",
+    "Checkout a remote branch (e.g., origin/feature-branch)",
+  )
+  .option(
+    "--pr <number>",
+    "Checkout a specific PR by number",
+  )
   .option(
     "--shell <shell>",
     "Start with 'claude' or 'bash' shell",
@@ -100,9 +108,11 @@ program
     const config = await loadConfig(options.config);
     config.containerPrefix = options.name || config.containerPrefix;
     config.autoPush = options.push !== false;
-    config.autoCreatePR = options.pr !== false;
+    config.autoCreatePR = options.createPr !== false;
     config.includeUntracked = options.includeUntracked || false;
     config.targetBranch = options.branch;
+    config.remoteBranch = options.remoteBranch;
+    config.prNumber = options.pr;
     if (options.shell) {
       config.defaultShell = options.shell.toLowerCase();
     }

src/index.ts

@@ -38,17 +38,67 @@ export class ClaudeSandbox {
       const currentBranch = await this.git.branchLocal();
       console.log(chalk.blue(`Current branch: ${currentBranch.current}`));
 
-      // Use target branch from config or generate one
-      const branchName =
-        this.config.targetBranch ||
-        (() => {
-          const timestamp = new Date()
-            .toISOString()
-            .replace(/[:.]/g, "-")
-            .split("T")[0];
-          return `claude/${timestamp}-${Date.now()}`;
-        })();
-      console.log(chalk.blue(`Will create branch in container: ${branchName}`));
+      // Determine target branch based on config options
+      let branchName = "";
+      
+      if (this.config.prNumber) {
+        // Checkout PR
+        console.log(chalk.blue(`Fetching PR #${this.config.prNumber}...`));
+        try {
+          branchName = `pr-${this.config.prNumber}`;
+          
+          // Check if PR branch already exists locally
+          const branches = await this.git.branchLocal();
+          if (branches.all.includes(branchName)) {
+            // PR branch exists, just checkout
+            await this.git.checkout(branchName);
+            console.log(chalk.green(`✓ Switched to existing PR branch: ${branchName}`));
+          } else {
+            // Fetch and create new PR branch
+            await this.git.fetch("origin", `pull/${this.config.prNumber}/head:${branchName}`);
+            await this.git.checkout(branchName);
+            console.log(chalk.green(`✓ Checked out PR #${this.config.prNumber}`));
+          }
+        } catch (error) {
+          console.error(chalk.red(`✗ Failed to checkout PR #${this.config.prNumber}:`), error);
+          throw error;
+        }
+      } else if (this.config.remoteBranch) {
+        // Checkout remote branch
+        console.log(chalk.blue(`Checking out remote branch: ${this.config.remoteBranch}...`));
+        try {
+          await this.git.fetch("origin");
+          const localBranchName = this.config.remoteBranch.replace("origin/", "");
+          
+          // Check if local branch already exists
+          const branches = await this.git.branchLocal();
+          if (branches.all.includes(localBranchName)) {
+            // Local branch exists, just checkout
+            await this.git.checkout(localBranchName);
+            console.log(chalk.green(`✓ Switched to existing branch: ${localBranchName}`));
+          } else {
+            // Create new local branch from remote
+            await this.git.checkoutBranch(localBranchName, this.config.remoteBranch);
+            console.log(chalk.green(`✓ Checked out remote branch: ${this.config.remoteBranch}`));
+          }
+          branchName = localBranchName;
+        } catch (error) {
+          console.error(chalk.red(`✗ Failed to checkout remote branch ${this.config.remoteBranch}:`), error);
+          throw error;
+        }
+      } else {
+        // Use target branch from config or generate one
+        branchName =
+          this.config.targetBranch ||
+          (() => {
+            const timestamp = new Date()
+              .toISOString()
+              .replace(/[:.]/g, "-")
+              .split("T")[0];
+            return `claude/${timestamp}-${Date.now()}`;
+          })();
+        console.log(chalk.blue(`Will create branch in container: ${branchName}`));
+      }
 
       // Discover credentials (optional - don't fail if not found)
       const credentials = await this.credentialManager.discover();

src/types.ts

@@ -23,6 +23,8 @@ export interface SandboxConfig {
   bashTimeout?: number;
   includeUntracked?: boolean;
   targetBranch?: string;
+  remoteBranch?: string;
+  prNumber?: string;
 }
 
 export interface Credentials {

src/web-server.ts

@@ -99,6 +99,24 @@ export class WebUIServer {
           currentBranch = branchResult.stdout.trim();
         }
 
+        // Get repository remote URL for branch links
+        let repoUrl = "";
+        try {
+          const remoteResult = await execAsync("git remote get-url origin", {
+            cwd: this.originalRepo || process.cwd(),
+          });
+          const remoteUrl = remoteResult.stdout.trim();
+          
+          // Convert SSH URLs to HTTPS for web links
+          if (remoteUrl.startsWith("git@github.com:")) {
+            repoUrl = remoteUrl.replace("git@github.com:", "https://github.com/").replace(".git", "");
+          } else if (remoteUrl.startsWith("https://")) {
+            repoUrl = remoteUrl.replace(".git", "");
+          }
+        } catch (error) {
+          console.warn("Could not get repository URL:", error);
+        }
+
         // Get PR info using GitHub CLI (always use original repo)
         let prs = [];
         try {
@@ -114,8 +132,12 @@ export class WebUIServer {
           console.warn("Could not fetch PR info:", error);
         }
 
+        const branchUrl = repoUrl ? `${repoUrl}/tree/${currentBranch}` : "";
+
         res.json({
           currentBranch,
+          branchUrl,
+          repoUrl,
           prs,
         });
       } catch (error) {