Add repositories on remote machines over SSH

Sidebar ⊕ → Add Remote Repository…: server, optional user/port, and an
absolute path, validated before anything is saved — reachability under
BatchMode (key auth or fail fast), the path being a git repository, and
zmx being installed there — so each failure names itself in the sheet
instead of surfacing later as a loop that silently does nothing.

A remote project's identity is the URI ssh://user@host[:port]/path,
following the precedent the global graph set: the daemon keys its graph
by it, nothing collides with a local checkout, and everything that
treats a path as a directory branches on RemoteProjectLocation.parse.
The daemon stays local — starting an unattended loop wraps the same zmx
argv in ssh with a remote login shell and a cd into the repository, and
the app's surfaces attach with ssh -t, plain-shell tabs included. The
opening prompt can't ride the local environment through sshd, so it is
assigned inside the quoted remote command and expanded by the same
"$GRAPHCODE_TRIGGER_PROMPT" the local path uses.

V1 limitations, stated in docs/09 and the README: kill/message/usage
stay local-only (their closures don't carry the project path yet), no
briefing or worktrees remotely, and a sleeping Mac fires no edges.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: scgopi

GraphcodeKit/Sources/Domain/RemoteProjectLocation.swift

@@ -0,0 +1,106 @@
+import Foundation
+
+/// A project whose working tree lives on another machine, reached over SSH — the
+/// docs/09-remote-repositories.md Phase B model, drawn on supacode's remote connections
+/// (shape, not code).
+///
+/// **The project path *is* the identity.** A remote project's path is the URI
+/// `ssh://user@host[:port]/absolute/path`, following the precedent the global graph set
+/// (`graphcode://global`): the daemon keys graphs by path string, the app keys sidebar
+/// rows by it, and a URI that embeds the host can never collide with a local folder or
+/// with the same folder on a different machine. Everything that treats a project path as
+/// a *directory* branches on `parse` returning non-nil.
+///
+/// **The daemon stays local.** Every remote effect is "run a command over ssh": the
+/// session is a `zmx` session on the remote host, started and attached through
+/// `sshInvocation`. What that buys — and what it costs (no edge firing while the Mac
+/// sleeps) — is docs/09's trade, made deliberately.
+public struct RemoteProjectLocation: Equatable, Sendable {
+  public var user: String?
+  public var host: String
+  public var port: Int?
+  /// Absolute path of the repository on the remote machine.
+  public var remotePath: String
+
+  public init(user: String? = nil, host: String, port: Int? = nil, remotePath: String) {
+    self.user = user
+    self.host = host
+    self.port = port
+    self.remotePath = remotePath
+  }
+
+  /// The reserved scheme. A path with this prefix is a remote project everywhere a
+  /// project path travels.
+  public static let scheme = "ssh"
+
+  /// Parses a project path, returning `nil` for anything that isn't a remote one —
+  /// which is the branch every existing call site takes for ordinary folders.
+  public static func parse(projectPath: String) -> RemoteProjectLocation? {
+    guard projectPath.hasPrefix("\(scheme)://"),
+      let components = URLComponents(string: projectPath),
+      components.scheme == scheme,
+      let host = components.host, !host.isEmpty,
+      !components.path.isEmpty, components.path.hasPrefix("/")
+    else { return nil }
+    return RemoteProjectLocation(
+      user: components.user, host: host, port: components.port, remotePath: components.path)
+  }
+
+  /// The path string this location travels as — `parse`'s inverse.
+  public var projectPath: String {
+    "\(Self.scheme)://\(authority)\(remotePath)"
+  }
+
+  /// `user@host` / `user@host:port` — what `ssh` is pointed at (port rides separately
+  /// as `-p`, but the authority string carries it for identity and display).
+  public var authority: String {
+    let userPart = user.map { "\($0)@" } ?? ""
+    let portPart = port.map { ":\($0)" } ?? ""
+    return "\(userPart)\(host)\(portPart)"
+  }
+
+  /// What ssh itself is told to connect to — the authority without the port.
+  public var sshDestination: String {
+    let userPart = user.map { "\($0)@" } ?? ""
+    return "\(userPart)\(host)"
+  }
+
+  /// The sidebar title: the repository folder's name, with the host to tell it apart
+  /// from a local checkout of the same project.
+  public var displayName: String {
+    let leaf = remotePath.split(separator: "/").last.map(String.init) ?? remotePath
+    return "\(leaf) @ \(host)"
+  }
+
+  /// POSIX single-quote escaping — the one quoting rule that survives every layer here.
+  /// ssh joins its command arguments with spaces and hands the result to the remote
+  /// login shell, so every remote command is built as one string with each embedded
+  /// value quoted by this; nesting works because a quoted string is itself safe to
+  /// quote again.
+  public static func shellQuoted(_ text: String) -> String {
+    "'" + text.replacingOccurrences(of: "'", with: "'\\''") + "'"
+  }
+
+  /// The local argv that runs `remoteCommand` on this host.
+  ///
+  /// `BatchMode=yes` because nothing launched by the app or daemon has a tty to answer
+  /// a password prompt — key auth or fail fast, the same rule the clone form applies.
+  /// `interactive` adds `-t`: a terminal surface needs the remote side to have a tty
+  /// (zmx attaches a full-screen session), where a launch/query must *not* take one.
+  public func sshInvocation(remoteCommand: String, interactive: Bool = false) -> [String] {
+    var invocation = ["/usr/bin/ssh"]
+    if interactive { invocation.append("-t") }
+    invocation += ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10"]
+    if let port { invocation += ["-p", String(port)] }
+    invocation += [sshDestination, "--", remoteCommand]
+    return invocation
+  }
+
+  /// Wraps a remote command so it resolves `PATH` the way a human's terminal would —
+  /// the remote twin of `ZmxSessionLauncher.loginShellInvocation`, and `-i` is
+  /// load-bearing for the same reason: the remote `~/.zshrc` is what knows where `zmx`
+  /// and the agent live, and zsh reads it only when interactive.
+  public func remoteLoginShellCommand(_ script: String) -> String {
+    "exec zsh -l -i -c \(Self.shellQuoted(script))"
+  }
+}

GraphcodeKit/Sources/ProjectRegistry.swift

@@ -208,16 +208,22 @@ public actor ProjectRegistry {
     return newStore
   }
 
-  /// The global graph's reserved path is a `graphcode://` URL, not a folder — running it
-  /// through `fileURLWithPath` would mangle it into a relative path under the cwd and
-  /// route its commands to a store that doesn't exist.
+  /// The global graph's reserved path is a `graphcode://` URL, and a remote project's
+  /// is an `ssh://` one — neither is a folder, and running either through
+  /// `fileURLWithPath` would mangle it into a relative path under the cwd and route its
+  /// commands to a store that doesn't exist.
   private static func canonicalize(_ path: String) -> String {
-    guard path != LoopGraphScope.globalPath else { return path }
+    guard path != LoopGraphScope.globalPath,
+      RemoteProjectLocation.parse(projectPath: path) == nil
+    else { return path }
     return URL(fileURLWithPath: path).resolvingSymlinksInPath().path
   }
 
   private static func displayName(for path: String) -> String {
-    URL(fileURLWithPath: path).lastPathComponent
+    if let remote = RemoteProjectLocation.parse(projectPath: path) {
+      return remote.displayName
+    }
+    return URL(fileURLWithPath: path).lastPathComponent
   }
 
   // MARK: - Unicast reply

GraphcodeKit/Sources/Sessions/ZmxSessionLauncher.swift

@@ -205,8 +205,13 @@ public enum ZmxSessionLauncher {
     // Read per launch, not cached: changing a setting in the app then applies to the very
     // next loop the daemon starts, with nothing to restart.
     let settings = GraphcodeSettingsStore.load()
+    // No briefing for a remote project's session: the file is written on *this* machine
+    // and the session runs on another, and the CLI it describes talks to a daemon the
+    // remote host can't reach. A remote loop that can't fan out is a stated v1
+    // limitation (docs/09-remote-repositories.md), not a silent failure.
+    let remote = projectPath.flatMap { RemoteProjectLocation.parse(projectPath: $0) }
     let briefingFile =
-      settings.briefsSessionsAboutTheGraph
+      settings.briefsSessionsAboutTheGraph && remote == nil
       ? SessionBriefing.write(projectPath: projectPath) : nil
     // Both the executable and the shape of its arguments come from the node's backend —
     // `claude` takes its prompt positionally and its briefing via `--append-system-prompt`,
@@ -249,9 +254,17 @@ public enum ZmxSessionLauncher {
   /// it was branched from — see `CopilotPermissions.readableDirectories`.
   ///
   /// The global graph's reserved `graphcode://` path names no directory and is dropped.
+  /// A remote project contributes its *remote* path — the directory as the session
+  /// running on that host sees it, which is the one a path-verifying backend needs.
   static func workspacePaths(forNode node: LoopNode, projectPath: String?) -> [String] {
     var paths: [String] = []
-    if let projectPath, !projectPath.hasPrefix("graphcode://") { paths.append(projectPath) }
+    if let projectPath, !projectPath.hasPrefix("graphcode://") {
+      if let remote = RemoteProjectLocation.parse(projectPath: projectPath) {
+        paths.append(remote.remotePath)
+      } else {
+        paths.append(projectPath)
+      }
+    }
     if let worktree = node.worktreeBinding?.worktreePath { paths.append(worktree) }
     return paths
   }
@@ -303,7 +316,68 @@ public enum ZmxSessionLauncher {
     return projectPath
   }
 
+  // MARK: - Remote projects
+
+  /// The local `ssh` argv that checks whether a remote node's session exists — the same
+  /// `zmx get` exit-status test as local, run on the host the session lives on.
+  static func remoteExistenceInvocation(
+    forNode node: LoopNode, at location: RemoteProjectLocation
+  ) -> [String] {
+    let script = quotedCommand(["zmx"] + existenceCheckArguments(forNode: node))
+    return location.sshInvocation(remoteCommand: location.remoteLoginShellCommand(script))
+  }
+
+  /// The local `ssh` argv that starts a remote node's session, or `nil` when the node
+  /// has nothing to run. The zmx argv is exactly the local one — session name, detach,
+  /// nested login shell, backend command — assembled into one quoted string, because ssh
+  /// joins its arguments with spaces and hands them to the remote shell. `cd` first so
+  /// the session opens in the repository, the remote twin of `workingDirectory`.
+  static func remoteLaunchInvocation(
+    forNode node: LoopNode, at location: RemoteProjectLocation
+  ) -> [String]? {
+    guard let zmxArguments = arguments(forNode: node, projectPath: location.projectPath)
+    else { return nil }
+    let script =
+      "cd \(RemoteProjectLocation.shellQuoted(location.remotePath)) && "
+      + quotedCommand(["zmx"] + zmxArguments)
+    return location.sshInvocation(remoteCommand: location.remoteLoginShellCommand(script))
+  }
+
+  /// One argv as one shell-safe string — each argument quoted, so a prompt containing
+  /// quotes, `$(…)`, or `;` stays one word through the remote shell exactly as it does
+  /// through zmx's own quoting locally. Public because the app's remote *attach* is
+  /// built from the same pieces (`GhosttyTerminalView.remoteCommand`).
+  public static func quotedCommand(_ argv: [String]) -> String {
+    argv.map(RemoteProjectLocation.shellQuoted).joined(separator: " ")
+  }
+
+  private static func startRemote(_ node: LoopNode, at location: RemoteProjectLocation) async {
+    guard let launch = remoteLaunchInvocation(forNode: node, at: location) else { return }
+    let existence = remoteExistenceInvocation(forNode: node, at: location)
+    do {
+      // Create only, same as local: a live remote session is the loop still running,
+      // and re-sending the command would type into it.
+      let existing = try PTYProcessSession(
+        executable: existence[0], arguments: Array(existence.dropFirst()))
+      guard await !existing.waitUntilFinished() else { return }
+
+      let session = try PTYProcessSession(
+        executable: launch[0], arguments: Array(launch.dropFirst()))
+      _ = await session.waitUntilFinished()
+    } catch {
+      // Same posture as the local path: no UI here, the node's state stays honest, and
+      // opening the loop retries.
+      return
+    }
+  }
+
   static func start(_ node: LoopNode, projectPath: String? = nil) async {
+    // A remote project's session starts on the remote host — local zmx isn't involved
+    // and doesn't need to be installed for it.
+    if let projectPath, let remote = RemoteProjectLocation.parse(projectPath: projectPath) {
+      await startRemote(node, at: remote)
+      return
+    }
     guard ZmxLocator.isInstalled else { return }
     guard let arguments = arguments(forNode: node, projectPath: projectPath) else { return }
 

README.md

@@ -77,9 +77,11 @@ current release.
 
 ## Using it
 
-1. **Add a folder** — the sidebar's ⊕ menu. It becomes a project with its own graph. Whatever
-   was open is restored next launch; right-click a project to Close, Remove, or delete its
-   loops.
+1. **Add a project** — the sidebar's ⊕ menu: open a local folder, **clone a repository
+   from a URL**, or **add a remote repository over SSH** (key auth and zmx on the server
+   required — loops then run on the server while this Mac steers them). Each becomes a
+   project with its own graph. Whatever was open is restored next launch; right-click a
+   project to Close, Remove, or delete its loops.
 2. **Create a loop** — ⊕ on the canvas. Write the prompt and hit Create: the form opens
    on goal-based, and the title is optional — leave it blank and GraphCode asks the loop's
    own backend for a name. For a time-based loop put the cadence in the prompt itself:
@@ -151,6 +153,11 @@ Design docs live in `docs/` and are kept local (gitignored) for now.
   instance) — the queued command runs only after the profile finishes.
 - **Sessions aren't reaped.** Long-lived `graphcode-*` zmx sessions accumulate; list them
   with `zmx list` and remove dead ones with `zmx kill`.
+- **Remote repositories are attach-first.** Loops on an SSH remote launch and attach
+  fine, but deleting one doesn't kill its remote session, message edges into remote
+  loops report undelivered, presence/usage read "not reported", and worktrees and
+  loop fan-out aren't available there yet. And a sleeping Mac fires no edges — the
+  daemon stays local by design.
 
 ## Inspiration & third-party
 

graphcode/Sources/Clients/RemoteRepositoryClient.swift

@@ -0,0 +1,77 @@
+import Dependencies
+import Foundation
+import GraphcodeKit
+
+/// Validates a remote repository connection before it is saved — reachability, the
+/// path being a git repository, and the session stack (`zmx`) being installed there.
+/// Run up front, in the form, because every one of these failures is otherwise
+/// discovered as a loop that silently does nothing: the connection that passes is one
+/// whose sessions can actually start.
+struct RemoteRepositoryClient: Sendable {
+  /// `nil` when the connection is usable; otherwise the reason it isn't, worded for the
+  /// sheet's footer.
+  var validate: @Sendable (RemoteProjectLocation) async -> String?
+}
+
+extension RemoteRepositoryClient: DependencyKey {
+  static let liveValue = RemoteRepositoryClient { location in
+    let quoted = RemoteProjectLocation.shellQuoted
+    // Ordered so the first failure names the actual problem: an unreachable host would
+    // otherwise read as "not a repository", which sends someone debugging the wrong
+    // thing. BatchMode in `sshInvocation` means a password-only host fails here, fast —
+    // key auth is a requirement, not a preference, since nothing later has a tty either.
+    let checks: [(command: String, failure: String)] = [
+      (
+        "true",
+        "Can't reach \(location.sshDestination) — check the host, and that key "
+          + "authentication works (`ssh \(location.sshDestination)` from a terminal)."
+      ),
+      (
+        "test -d \(quoted(location.remotePath))",
+        "\(location.remotePath) doesn't exist on \(location.host)."
+      ),
+      (
+        "git -C \(quoted(location.remotePath)) rev-parse --is-inside-work-tree",
+        "\(location.remotePath) isn't a git repository."
+      ),
+      (
+        location.remoteLoginShellCommand("command -v zmx"),
+        "zmx isn't installed on \(location.host) — sessions live in it. "
+          + "Install it there and try again."
+      ),
+    ]
+    for check in checks {
+      let invocation = location.sshInvocation(remoteCommand: check.command)
+      guard await succeeds(invocation) else { return check.failure }
+    }
+    return nil
+  }
+
+  /// Form tests have no network and should not discover that by hanging.
+  static let testValue = RemoteRepositoryClient { _ in nil }
+
+  private static func succeeds(_ invocation: [String]) async -> Bool {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: invocation[0])
+    process.arguments = Array(invocation.dropFirst())
+    process.standardOutput = FileHandle.nullDevice
+    process.standardError = FileHandle.nullDevice
+    do {
+      try process.run()
+    } catch {
+      return false
+    }
+    return await withCheckedContinuation { continuation in
+      process.terminationHandler = { process in
+        continuation.resume(returning: process.terminationStatus == 0)
+      }
+    }
+  }
+}
+
+extension DependencyValues {
+  var remoteRepositoryClient: RemoteRepositoryClient {
+    get { self[RemoteRepositoryClient.self] }
+    set { self[RemoteRepositoryClient.self] = newValue }
+  }
+}

graphcode/Sources/Features/App/AppSidebarView.swift

@@ -95,6 +95,14 @@ struct AppSidebarView: View {
     ) {
       CloneRepositoryFormView(store: store.scope(state: \.welcome, action: \.welcome))
     }
+    .sheet(
+      isPresented: Binding(
+        get: { store.welcome.remoteDraft != nil },
+        set: { if !$0 { store.send(.welcome(.remoteCancelled)) } }
+      )
+    ) {
+      RemoteRepositoryFormView(store: store.scope(state: \.welcome, action: \.welcome))
+    }
     .confirmationDialog(
       "Delete this project's loops?",
       isPresented: Binding(
@@ -143,6 +151,12 @@ struct AppSidebarView: View {
       } label: {
         Label("Clone Repository…", systemImage: "square.and.arrow.down.on.square")
       }
+      // A repository on another machine, over SSH — loops run there, this Mac steers.
+      Button {
+        store.send(.welcome(.addRemoteRepositoryButtonTapped))
+      } label: {
+        Label("Add Remote Repository…", systemImage: "network")
+      }
       if !store.welcome.recentProjects.isEmpty {
         Divider()
         ForEach(store.welcome.recentProjects) { project in

graphcode/Sources/Features/LoopWorkspace/LoopWorkspaceView.swift

@@ -190,8 +190,10 @@ struct LoopWorkspaceView: View {
       // should open there, not wherever the app process happened to launch from.
       workingDirectory: store.node.worktreeBinding?.worktreePath ?? store.projectPath,
       // The graph's own project, for the session briefing — deliberately not the
-      // worktree, whose path names a graph that doesn't exist.
-      projectPath: ref.launchesClaudeCode ? store.projectPath : nil,
+      // worktree, whose path names a graph that doesn't exist. Every surface gets it,
+      // not just the agent's: a remote project's plain-shell tabs open on the remote
+      // host, and which host that is lives in this path.
+      projectPath: store.projectPath,
       // Only *one* surface in the whole workspace is the live one: the showing tab's
       // focused pane. Every other surface stays mounted and must not hold the keyboard —
       // including the other half of this tab's own split, which is what stops both panes