From 7667bfe0429b7b749ac148a2a50b548b65c9ea3a Mon Sep 17 00:00:00 2001
From: Aaron Powell <me@aaron-powell.com>
Date: Wed, 17 Jun 2026 14:14:15 +1000
Subject: [PATCH] docs: add GitHub Copilot app deep links guide (#2023)

Add a new 'Launching Sessions from the Terminal with Deep Links' section to the
GitHub Copilot app overview documentation. This section covers:

- Supported URL schemes (ghapp://, github-app://, gh://)
- session/new route with all supported parameters (repo, branch, pr, prompt, mode)
- Practical examples for common workflows
- Other useful deep links (chats, mywork, workflows, issues, PRs)
- Important limitations (repo-centric focus, local folder restrictions)

This addresses the request from the #github-app Slack channel discussion about
opening ghapp from the terminal for a better development experience.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/learning-hub/github-copilot-app.md   | 61 ++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/website/src/content/docs/learning-hub/github-copilot-app.md b/website/src/content/docs/learning-hub/github-copilot-app.md
index 319c4f09..14628fcc 100644
--- a/website/src/content/docs/learning-hub/github-copilot-app.md
+++ b/website/src/content/docs/learning-hub/github-copilot-app.md
@@ -3,7 +3,7 @@ title: 'Getting Started with the GitHub Copilot app'
 description: 'Learn about the GitHub Copilot app, a desktop experience built for agent-native development. Understand its key features and who it''s for.'
 authors:
   - GitHub Copilot Learning Hub Team
-lastUpdated: 2026-06-12
+lastUpdated: 2026-06-17
 estimatedReadingTime: '8 minutes'
 tags:
   - copilot-app
@@ -143,6 +143,65 @@ Once installed, you can create a session by:
 
 Each session runs in its own worktree with its own isolated environment. You can run multiple sessions in parallel.
 
+### Launching Sessions from the Terminal with Deep Links
+
+The GitHub Copilot app supports URL deep links. This is useful when you want to open the app or start a session directly from your terminal workflow.
+
+Supported schemes:
+
+- `ghapp://` (canonical)
+- `github-app://`
+- `gh://`
+
+In examples below, replace `owner/repo` with your repository.
+
+#### Open a new session
+
+Use the `session/new` route:
+
+```bash
+# Basic new session
+open "ghapp://session/new?repo=owner/repo"
+
+# Start from a branch
+open "ghapp://session/new?repo=owner/repo&branch=main"
+
+# Start from a pull request
+open "ghapp://session/new?repo=owner/repo&pr=1234"
+
+# Start with a kickoff prompt
+open "ghapp://session/new?repo=owner/repo&prompt=fix%20the%20flaky%20test"
+
+# Set the initial session mode
+open "ghapp://session/new?repo=owner/repo&mode=plan"
+```
+
+`session/new` supports:
+
+- `repo` (**required**, format `owner/repo`)
+- `pr` (integer, mutually exclusive with `branch`)
+- `branch` (mutually exclusive with `pr`)
+- `prompt` (URL-encoded text)
+- `mode` (`plan`, `interactive`, or `autopilot`)
+
+#### Other useful deep links
+
+- `ghapp://repo/owner/repo` - Open (or clone) a repo into projects
+- `ghapp://clone/owner/repo` - Clone a repo
+- `ghapp://sessions/<sessionId>` - Open an existing session
+- `ghapp://chats` - Open chats
+- `ghapp://mywork` - Open the My Work view
+- `ghapp://recent` - Open recent workspaces
+- `ghapp://workflows` - Open automations
+- `ghapp://owner/repo/issues/123` - Open an issue
+- `ghapp://owner/repo/pull/456` - Open a pull request
+
+#### Important limitations
+
+- Deep links are **repo-centric** and expect `owner/repo`.
+- There is no deep link that directly opens an arbitrary local folder.
+- For local folders, use the app's **Add local folder** flow; if the folder is already a Git repository with a `github.com` remote, resolve that remote to `owner/repo` and use `session/new`.
+
 ### Understanding Session Workflow
 
 Here's what happens when you create a session: