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>
This commit is contained in:
Aaron Powell
2026-06-17 14:14:15 +10:00
committed by GitHub
parent 1140812aaa
commit 7667bfe042
@@ -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.' 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: authors:
- GitHub Copilot Learning Hub Team - GitHub Copilot Learning Hub Team
lastUpdated: 2026-06-12 lastUpdated: 2026-06-17
estimatedReadingTime: '8 minutes' estimatedReadingTime: '8 minutes'
tags: tags:
- copilot-app - 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. 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 ### Understanding Session Workflow
Here's what happens when you create a session: Here's what happens when you create a session: