GitHub Copilot CLI

Install GitHub Copilot CLI and the SpecStory CLI. Copilot CLI needs SpecStory CLI 2.17.0 or later, and sessions created with Copilot CLI 1.0.105 or later. Open your project folder in a terminal and run specstory check copilot.

This guide covers the terminal agent. For Copilot Chat in VS Code, see the VS Code extension.

specstory run copilot

Use Copilot as usual. SpecStory saves the conversation in .specstory/history/. Cloud sync can run when you are logged in; add --no-cloud-sync to keep the session local.

specstory list copilot
specstory sync copilot

# Export a single session
specstory sync copilot -s <session-id>

SpecStory reads Copilot's session history from ~/.copilot/session-state/ and matches it to your project. You can export conversations even if you did not start them through SpecStory. Copilot keeps every session in one place, so the match uses the directory recorded inside each session, and it must be exact: run these commands from the folder where you started Copilot, not a parent or a subfolder.

Sessions Copilot runs for the GitHub Copilot app and for VS Code's Agents window are stored the same way, so they are saved too. An Agents window session with no workspace selected is recorded under a scratch folder such as ~/.copilot/chats/<id> instead of your project.

A sub-agent's work stays inside its parent conversation instead of becoming its own session. Reasoning is saved when the model exposes it as text; Copilot's opaque reasoning cannot be exported as readable text.

If you set COPILOT_HOME, Copilot stores sessions under $COPILOT_HOME/session-state/ instead. Set the same variable for SpecStory so it reads the same place.

specstory watch copilot

Leave this running while using Copilot directly. Stop watching with Ctrl+C.

Run specstory search to find saved work or specstory resume to choose a previous session. Copilot continues one of its own sessions in place with copilot --resume, and can receive a session from another agent as reconstructed conversation text. A reconstructed session keeps the conversation as plain text, and Copilot names it from the first prompt you send after resuming. See search and resume for the picker and supported handoffs.

If Copilot CLI is not detected, check that copilot is on your PATH. If your CLI does not list Copilot CLI in specstory run --help, update SpecStory. To launch Copilot from another location, set copilot_cmd in your config or pass specstory run copilot -c "~/bin/copilot".

If no sessions appear, run the commands from the folder where you started Copilot and confirm that its local history still exists. Copilot prunes old transcripts, and a session that has lost its events.jsonl can no longer be exported. A session containing only ! commands leaves no transcript to save.

See the CLI reference for custom commands, configuration, and debug logging.