copilothistory

Command line tool to extract VS Code's Copilot chat history for a workspace folder

Installation

Global Installation

The simplest way to install the tool is by installing it globally:

npm install -g copilothistory

You can run the tool by simply calling copilothistory anywhere on the command line.

If you want to use it as a library, just use

npm install copilothistory

The project is written in TypeScript, i.e. type information (and maps) are provided.

Developer Installation

If you want to change the tool, you may want to create a clone, and inside the folder of the clone run

npm install
npm run build
npm link

You can run the tool by simply calling copilothistory anywhere on the command line.

Uninstall

In order to uninstall the tool, just call

npm uninstall -g copilothistory

(npm unlink -g copilothistory does the same, as unlink is just an alias for uninstall)

Usage

copilothistory provides the following commands:

• export: Exports GitHub Copilot Chat history in JSON, markdown, or plain text format
• info: Shows information about the workspace storages and the chat history (still in progress)
• init: Generates a settings file

(Almost) all commands support some basic options:

| Option | Short | Description | |---------------------|-------|------------------------------------------------------------------------------------------------------| | --settings <file> | | Settings file to use. Defaults to .copilothistory/settings.json in the current or a parent folder. | | --quiet | -q | Quiet mode — emit only errors. | | --verbose | -v | Emit verbose messages. | | --debug | | Emit debug messages. |

export — Export Copilot chat history

Reads the VS Code Copilot chat session files for a workspace and prints the conversation history to the console or a file.

copilothistory export [options]

| Option | Short | Description | |---------------------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | --output <path> | -o | Output file path. Omit to print to the console (default). | | --workspace <path> | -w | Workspace folder to export history for. Defaults to the current working directory. | | --vscodeDataPath <path> | | Custom VS Code data directory. Defaults to the platform-specific standard path. | | --sessionsDir <path> | | Read JSONL session files directly from this directory, bypassing VS Code workspace storage discovery. | | --noRemote | | Do not search remote locations (Dev Container or WSL) as fallback when no direct workspace storage match is found (default false) | | --enforceRemote | | Enforce searching remote locations even when a direct workspace storage match is found (default false) | | --remoteType | | Filter for type of remote environment, e.g. "dev-container" or "wsl". Default empty, i.e. all types. | | --remotePath <path> | | Prefix in remote container, e.g. "/home/dev" for absolute path "/home/dev/workspace" or "projects" for relative path matching all "**/projects/workspace" ; if empty, all workspaces in remote matching the workspace folder name are considered. Default empty. | | --caseSensitive | | Compare files and paths in a case-sensitive manner (default false) | | --onlyLatest | | If multiple workspace storage folders are found, only use the most recent one. Default false. | | --format <fmt> | -f | Output format: markdown (default), plaintext, or json. |

Examples

Export the history for the current workspace to the console (as Markdown by default):

copilothistory export

Export as plain text:

copilothistory export --format plaintext

Export as raw JSON (the original JSONL records merged into a formatted JSON array):

copilothistory export --format json

Export to a file:

copilothistory export -o history.md

Export the history for a specific workspace folder:

copilothistory export -w /path/to/my/project

info — Show information

This command is primarily for debugging purposes. It shows information about workspace storages. It supports the same options as export, except for --format and --output.

init — Create a settings file

Creates a .copilothistory/settings.json file in the current directory with all available settings and their default values. You can then edit that file to persist your preferred options.

copilothistory init --generate-settings

| Option | Description | |-----------------------|-----------------------------| | --generate-settings | Generate the settings file. |

Settings file

Settings that can be persisted in .copilothistory/settings.json (searched for in the current directory and its parents). You can define default values for almost all options.

Use

copilothistory init --generateSettings

to generate a documented initial version.

The tool searches for the settings in the current folder, then in its parent and so on. Additionally, it searches for a settings file in the user's home folder. All found settings are merged; the closer a settings file is to the current working directory, the higher its priority.

Library API

copilothistory can also be used programmatically as a Node.js library. It uses the log-functions provided from cmdfiles, so you may configure these if needed.

Installation

npm install copilothistory

exportCopilotHistory(options)

Reads the VS Code Copilot chat session files for a workspace and returns the conversation history as a string. When output is specified the history is also written to that file. The history is never written to stdout by this function — stdout output is only performed by the CLI.

import { exportCopilotHistory } from "copilothistory";

// Retrieve history as a Markdown string (default)
const history = await exportCopilotHistory({
    workspace: "/path/to/my/project",
});
if (history) {
    console.log(history);
} else {
    console.log("No history found.");
}

// Plain-text format
const plainHistory = await exportCopilotHistory({
    workspace: "/path/to/my/project",
    format: "plaintext",
});

// Raw JSON format (original JSONL records as a formatted JSON array)
const jsonHistory = await exportCopilotHistory({
    workspace: "/path/to/my/project",
    format: "json",
});

// Or export directly to a file
await exportCopilotHistory({
    workspace: "/path/to/my/project",
    output: "history.md",
});

Returns Promise<string> — the full history as a formatted string, or an empty string if no chat history exists for the workspace. When output is specified the content is also written to that file.

Throws Error if the options are invalid (e.g. noDevContainer and enforceDevContainer used together) or if a Dev Container environment prevents host-side discovery.

Remarks

Copilot history files are usually located in a User/workspaceStorage folder inside ~/Library/Application Support/Code (macOS), ~/.config/Code (Linux), or %appdata%/Code, e.g. C:\Users\john\AppData\Roaming\Code, (Windows). This can be changed with vscodeDataPath. For each workspace, a workspace storage folder is created, in which a file workspace.json can be found. In this file, the actual workspace location is stored. If there are any chat sessions, they are stored in JSONL (or JSON!) files in a chatSessions folder.

Retrieving the history is a bit tricky, due to the following reasons:

• There may be several workspace storage folders for the same workspace (e.g., because a folder has been removed and newly created). In order to not retrieve the wrong history, only workspace storage folders are examined which have been modified after the workspace folder has been created. Also, with --onlyLatest, it can be enforced to only use the latest workspace storage folder, which is usually the one you are currently using.
• If a workspace is opened in a dev container or WSL (Windows Subsystem for Linux), the path to the workspace is relative to the container. There is a problem here: You cannot retrieve the history (via command line) in the terminal of VS Code inside the container, because the history is stored on the host! The workspace path used in workspace.json starts with vscode-remote://, followed by the container type and ID, e.g., dev-container+... (where ... is the long ID of the Docker container) or wsl+ubuntu. There are several options to handle remote containers (--noRemote or --enforceRemote, --remoteType and --remotePath).

So the history is usually retrieved from all workspace storage folders changed after the workspace folder has been created.

Also note that the history is not necessarily immediately saved after the chat has been changed. So it is probably best to exit VS Code or have a manual check.

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0 which is available at https://www.eclipse.org/legal/epl-2.0.

It contains some small functions (in src/detectEnvironment.ts) from MIT-licensed packages (copied here to reduce the number of micro-dependencies)..