Skip to content

Commit 7667bfe

Browse files
aaronpowellCopilot
andauthored
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>
1 parent 1140812 commit 7667bfe

1 file changed

Lines changed: 60 additions & 1 deletion

File tree

website/src/content/docs/learning-hub/github-copilot-app.md

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'Getting Started with the GitHub Copilot app'
33
description: 'Learn about the GitHub Copilot app, a desktop experience built for agent-native development. Understand its key features and who it''s for.'
44
authors:
55
- GitHub Copilot Learning Hub Team
6-
lastUpdated: 2026-06-12
6+
lastUpdated: 2026-06-17
77
estimatedReadingTime: '8 minutes'
88
tags:
99
- copilot-app
@@ -143,6 +143,65 @@ Once installed, you can create a session by:
143143

144144
Each session runs in its own worktree with its own isolated environment. You can run multiple sessions in parallel.
145145

146+
### Launching Sessions from the Terminal with Deep Links
147+
148+
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.
149+
150+
Supported schemes:
151+
152+
- `ghapp://` (canonical)
153+
- `github-app://`
154+
- `gh://`
155+
156+
In examples below, replace `owner/repo` with your repository.
157+
158+
#### Open a new session
159+
160+
Use the `session/new` route:
161+
162+
```bash
163+
# Basic new session
164+
open "ghapp://session/new?repo=owner/repo"
165+
166+
# Start from a branch
167+
open "ghapp://session/new?repo=owner/repo&branch=main"
168+
169+
# Start from a pull request
170+
open "ghapp://session/new?repo=owner/repo&pr=1234"
171+
172+
# Start with a kickoff prompt
173+
open "ghapp://session/new?repo=owner/repo&prompt=fix%20the%20flaky%20test"
174+
175+
# Set the initial session mode
176+
open "ghapp://session/new?repo=owner/repo&mode=plan"
177+
```
178+
179+
`session/new` supports:
180+
181+
- `repo` (**required**, format `owner/repo`)
182+
- `pr` (integer, mutually exclusive with `branch`)
183+
- `branch` (mutually exclusive with `pr`)
184+
- `prompt` (URL-encoded text)
185+
- `mode` (`plan`, `interactive`, or `autopilot`)
186+
187+
#### Other useful deep links
188+
189+
- `ghapp://repo/owner/repo` - Open (or clone) a repo into projects
190+
- `ghapp://clone/owner/repo` - Clone a repo
191+
- `ghapp://sessions/<sessionId>` - Open an existing session
192+
- `ghapp://chats` - Open chats
193+
- `ghapp://mywork` - Open the My Work view
194+
- `ghapp://recent` - Open recent workspaces
195+
- `ghapp://workflows` - Open automations
196+
- `ghapp://owner/repo/issues/123` - Open an issue
197+
- `ghapp://owner/repo/pull/456` - Open a pull request
198+
199+
#### Important limitations
200+
201+
- Deep links are **repo-centric** and expect `owner/repo`.
202+
- There is no deep link that directly opens an arbitrary local folder.
203+
- 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`.
204+
146205
### Understanding Session Workflow
147206

148207
Here's what happens when you create a session:

0 commit comments

Comments
 (0)