copilothistory

Command line tool to extract VS Code's copilot 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.

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 two commands: export and init.

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. | | --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. | | --noDevContainer | | Do not search Dev Container locations as a fallback when no direct workspace storage match is found. | | --enforceDevContainer | | Enforce searching Dev Container locations even when a direct workspace storage match is found. | | --pathPrefixInDevContainer <path> | | Absolute path to the parent folder of the workspace folder inside the dev container (e.g. /workspace). When omitted, all matching dev container workspaces are considered. | | --onlyLatest | | If multiple workspace storage folders are found, only use the most recent one. | | --format <fmt> | -f | Output format: markdown (default), plaintext, or json. | | --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. |

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

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> | Path for the settings file to create. | | --quiet / -q | Quiet mode. | | --verbose / -v | Emit verbose messages. | | --debug | Emit debug messages. |

Settings file

Settings that can be persisted in .copilothistory/settings.json (searched for in the current directory and its parents):

• vscodeDataPath — Custom VS Code data directory.
• noDevContainer — Do not search Dev Container locations as a fallback.
• enforceDevContainer — Always search Dev Container locations instead of direct matches.
• pathPrefixInDevContainer — Absolute path to the parent folder of the workspace inside the dev container.
• onlyLatest — Only use the most recent workspace storage when multiple are found.
• format — Default output format (markdown, plaintext, or json).

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.

Options (ExportOptions)

All options are optional.

| Option | Type | Description | |---|---|---| | output | string | Output file path. Omit to write to stdout. | | workspace | string | Workspace folder to export history for. Defaults to process.cwd(). | | vscodeDataPath | string | Custom VS Code data directory. Defaults to the platform-specific standard path. | | sessionsDir | string | Read JSONL session files directly from this directory, bypassing VS Code workspace storage discovery. | | noDevContainer | boolean | Do not search Dev Container locations as a fallback when no direct workspace storage match is found. | | enforceDevContainer | boolean | Enforce searching Dev Container locations even when a direct workspace storage match is found. | | pathPrefixInDevContainer | string | Absolute path to the parent folder of the workspace folder inside the dev container (e.g. /workspace). | | onlyLatest | boolean | If multiple workspace storage folders are found, only use the most recent one. | | format | "markdown" \| "plaintext" \| "json" | Output format. markdown (default) emits GitHub-flavoured Markdown with collapsible sections. plaintext emits a plain-text report. json emits the raw JSONL records merged into a formatted JSON array. |

Remarks

The copilot history file is usually located a folder User/workspaceStoragein in ~/Library/Application Support/Code (macos), ~/.config/Code (Linux), or %appdata%/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-Files in a folder chatSessions.

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, the path to the workspace is relative to the dev container. There is a trick here: You cannot retrieve the history (via command line) in the terminal of VS Code using the dev container, because the history is stored on the host! The workspace path used in the workspace.json starts with 'vscode-remote://dev-container', followed by the id of the container and the path of the workspace in the container. There are several options do handle dev containers (--noDevContainer or --enforceDevContainer, and --pathPrefixInDevContainer)

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.