Tutorial: Continue a cloud agent session in your terminal

Start an agent task in Visual Studio Code, close the application, and continue the same conversation from GitHub Copilot CLI in a regular terminal. The agent runs in a managed cloud environment, so your development machine doesn't need to stay online for the task to run.

In this tutorial, you ask an agent to explore one of your private repositories and suggest improvements. Then you connect from your terminal and turn one suggestion into an implementation plan without repeating the repository context. You don't need to clone the repository, install its dependencies, or change any code.

If you haven't worked with agents before, start with the agents quickstart.

Prerequisites

• Install VS Code and set up GitHub Copilot.
• Use a GitHub account with access to cloud sessions. Availability depends on your account and organization.
• Have an existing repository on GitHub.com.
• Ensure the chat.agentHost.cloudSandbox.enabled Open in VS Code Open in VS Code Insiders setting is on in VS Code.
• Install the latest Copilot CLI. Choose a native installation option if you don't already have Node.js. Your account and organization must allow CLI access and cloud connections.

1. Choose a repository

Choose a repository from your own projects that is available for cloud sessions. Pick a small project or focus on one feature to keep the exploration manageable.

The task only reads repository files and returns its findings in the conversation. You don't need to install dependencies or run the project for this walkthrough.

The cloud session works with the code available on GitHub.com. Uncommitted changes, local dependencies, and files that exist only on your computer aren't copied to the cloud environment.

2. Start the task in a cloud session

A cloud session provides an isolated environment for the agent to explore the repository without affecting your local setup. It runs on GitHub's infrastructure.

1. In VS Code, select Open in Agents in the title bar to open the Agents window.

2. Select New to start a session.

3. Choose the Cloud environment from the environment dropdown, then select Work in Repository from the workspace dropdown, and choose your private repository.

   

4. Keep other options at their defaults.

5. Enter the following prompt:

   Explore this repository to help me understand where to make a small contribution.
   
   1. Summarize the project's purpose and main directories.
   2. Trace one main feature from its entry point or data source to its output.
   3. Suggest three small improvements, numbered so I can refer to them later.
   
   Cite the relevant file paths for the explanation and each suggestion.
   Don't edit files, install dependencies, execute project code, or create
   issues or pull requests. Return your findings in this conversation.
   

   To focus the exploration, add the name of a feature you're interested in and ask the agent to trace how it works.

6. Wait for the cloud environment to connect and for the agent to start working. Review any approval requests before accepting them.

7. Note the session title so you can recognize it in the CLI, then close the VS Code application.

This task starts in the cloud. Connecting from another app doesn't move a local session or upload a local workspace. Because a cloud session runs on the remote cloud infrastructure, it is independent of your local application state. Closing the application doesn't stop cloud execution.

3. Continue in the Copilot CLI

You can connect and interact with Copilot agents sessions from different Copilot clients. In this section, you use the Copilot CLI to continue working with the cloud session you started in VS Code. Alternatively, use another supported Copilot client, like the Copilot app.

You can use the same computer or another computer with Copilot CLI installed.

1. If you haven't signed in to the CLI, run:

   copilot login
   

   Sign in with the same GitHub account you used to start the cloud session.

2. Type /sessions to view the list of sessions. Use right to select the Remote tab.

3. Choose the cloud session you started in VS Code. Match its title and repository to the task from the previous section.

   

4. Wait for the connection, then check that the conversation includes your repository exploration prompt and the agent's progress or findings.

   

5. Observe that the terminal now shows the ongoing conversation and the agent's progress. You can continue interacting with the agent as if you were in the original client.

   The terminal is another client for the same session. Repository access and agent tools still run in the cloud environment, not in your terminal's current directory. You don't need a local clone.

If you already know the session ID or task ID, you can connect directly with copilot --connect=<session-or-task-id>. For details, see the CLI command-line options.

If you can't find or connect to the session:

• Check that both applications use the same account and that your account has cloud session access.
• Run copilot --help to check for --connect. If it's missing, update the CLI using the installation instructions.
• Reopen the original session in VS Code and check its connection state. A saved transcript doesn't guarantee that the cloud environment is available for live work.

4. Continue without repeating the context

After the agent finishes its exploration, enter this follow-up in the connected CLI session:

Turn the second improvement you suggested into a short implementation plan.
Identify the affected files, acceptance criteria, and verification steps.
Don't implement the change, install dependencies, execute project code,
or create issues or pull requests.

The agent uses the earlier conversation to identify the suggestion. You don't need to paste the repository summary or start another task.

Review the result:

• Confirm that the plan addresses the second suggestion from the original response.
• Open the cited files on GitHub.com and check that they support the explanation.
• Check that the acceptance criteria describe an observable outcome and that proposed verification steps are labeled as steps to run, not tests that already passed.

You have explored a repository in VS Code and continued the same cloud-hosted task from your terminal. You can also reopen the original session in the Agents window to continue there.

Next steps

• Manage cloud sessions to learn about reconnecting, reviewing work, and finishing a session.
• Create an automation for recurring work such as a repository digest. An automation starts new runs from a saved prompt rather than keeping this interactive session running.