kpsVibe Viewer

kpsVibe Viewer is a lightweight, self-hosted web server that indexes all your VS Code Copilot Chat sessions stored locally on disk and serves them through a clean browser interface.

How it works

The viewer scans your workspaceStorage folder for Copilot JSONL session files, parses and indexes each message into SQLite, then serves a single-page web app on a local HTTP/HTTPS port. Incremental sync keeps the index up-to-date without re-reading the entire history every time.

Main views

System Requirements

Finding your chatSessions folder

kpsVibe automatically detects all installed editors (VS Code, VS Code Insiders, VSCodium, Cursor, Windsurf) on startup — no configuration needed. You can also set chat.chat_sessions_paths in config.json to a specific path or an array of paths. Typical locations:

• Windows VS Code: %APPDATA%\Code\User\workspaceStorage
• Windows Cursor: %APPDATA%\Cursor\User\workspaceStorage
• Windows VSCodium: %APPDATA%\VSCodium\User\workspaceStorage
• Linux VS Code: ~/.config/Code/User/workspaceStorage
• macOS VS Code: ~/Library/Application Support/Code/User/workspaceStorage

Installation on Windows

1. Download kpsvibe-windows.zip from the Downloads section
2. Extract the zip — you get kpsvibe.exe and config-example.json
3. Copy config-example.json to config.json in the same folder
4. Edit config.json: chat.chat_sessions_paths is optional — leave it empty and kpsVibe auto-detects VS Code, Cursor, VSCodium and Windsurf
5. Open a terminal in that folder and run:

.\kpsvibe.exe

Auto-start as a Windows Service (optional)

kpsVibe Viewer has a built-in Windows Service installer — no third-party tools needed. Run the commands below from an Administrator prompt:

Install and start automatically with Windows:

kpsvibe.exe --install-service

Or install as manual start (you start it yourself):

kpsvibe.exe --install-service --demand

Once installed, manage the service with:

kpsvibe.exe --start-service      # start the service
kpsvibe.exe --stop-service       # stop the service
kpsvibe.exe --uninstall-service  # remove from Windows

Installation on Linux

1. Download the Linux binary from the Downloads section
2. Make it executable:

chmod +x kpsvibe

3. Copy config-example.json to config.json in the same folder and edit it
4. Run the server:

./kpsvibe --config config.json

Run as a systemd service (recommended)

Create /etc/systemd/system/kpsvibe.service:

[Unit]
Description=kpsVibe Viewer
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/kpsvibe
ExecStart=/opt/kpsvibe/kpsvibe --config /opt/kpsvibe/config.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Statically linked — no extra packages needed

Basic Configuration (config.json)

The single configuration file config.json covers the server, logging and chat-indexing settings. Copy config-example.json to config.json and edit as needed.

Complete structure with defaults

{
    "server": {
        "listen":  "0.0.0.0",
        "port":    8380,
        "threads": 0,
        "tls": {
            "enabled":   false,
            "cert_file": "cert.pem",
            "key_file":  "key.pem"
        }
    },
    "logging": {
        "file":    "kpsvibe.log",
        "json":    false,
        "console": true
    },
    "chat": {
        "chat_sessions_path":   "",
        "db_path":              "chat_viewer.db",
        "web_root":             "web",
        "resync_on_start":      true,
        "content_preview_chars": 1000,
        "index_fields": ["role","timestamp","model","has_tool_calls","has_references"]
    }
}

Server options

Logging options

Chat indexing options

TLS / HTTPS

Enable HTTPS by setting server.tls.enabled = true and providing a certificate + key. HTTP continues to work on server.port; HTTPS listens on a separate port (default 8381).

Using the Viewer

Session list (left sidebar)

All indexed sessions appear in the left sidebar, ordered by last activity. Use the filter input to narrow down by session name. Click a session to open it.

Message view

Each message shows the role badge (user/assistant), model name, a timestamp, and — for JSONL-backed sessions — an L:N badge indicating the line number of that message inside the source JSONL file.

Global search

Type in the top search bar and press Enter (or click the 🔍 button). Results are ranked by relevance and link directly to the matching message context.

Syncing

Click the global ⟳ Sync button (top-right) to re-index all changed session files. Within an open session, use the per-session Sync button to force a full re-index of only that file.

Sharing a session

Click Share in the session toolbar to copy a direct URL to the current session to the clipboard. Anyone with network access to the server can open it.

API Endpoint Reference

All HTTP endpoints exposed by the viewer. The server binds to http://localhost:8380 by default.

curl quick reference

Security & Authentication

kpsVibe Viewer binds to all interfaces (0.0.0.0) by default so you can access it from other devices on your local network. This is convenient but means that anyone on the same network can browse your entire AI chat history.

Optional username/password login

If you want to require a login before anyone can view the chat history, set credentials via the command line. Once set, every browser visit will show a sign-in page. The credentials are stored in the SQLite database and survive a DB reset (only chat data is cleared — credentials are kept).

Set credentials

kpsvibe --set-auth <username> <password>

The password is stored as a SHA-256 hash — it is never saved in plain text. Run this command again to change the password.

Remove credentials

kpsvibe --clear-auth

After clearing, the viewer returns to open-access mode. Existing browser sessions are invalidated immediately.

DB reset and credentials

The Reset DB button in the viewer (or POST /api/db/reset) only deletes indexed chat messages and sessions. It never touches the auth_config table, so your credentials are preserved across resets.

Security banner

When no password is configured and the viewer is accessed from a hostname other than localhost or 127.0.0.1, a red warning banner is shown at the top of the page reminding you to secure the installation.

HTTPS with a Self-signed Certificate

kpsVibe Viewer supports HTTPS out of the box. You can point it at a commercially-signed certificate or generate a quick self-signed one for local/intranet use.

Generate a self-signed certificate

The command below uses OpenSSL (pre-installed on Linux and macOS; available via Win32 OpenSSL or winget install ShiningLight.OpenSSL on Windows) to create a 4096-bit RSA certificate valid for 365 days:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

This produces two files: cert.pem (the certificate) and key.pem (the private key). Store them somewhere safe and accessible to the kpsvibe process.

Point kpsvibe at the certificate

Add the tls_cert, tls_key, and tls_port fields to your config.json:

{
  "server": {
    "port": 8380,
    "tls_cert": "cert.pem",
    "tls_key":  "key.pem",
    "tls_port": 8443
  }
}

Trusting the certificate in your browser

Because the certificate is self-signed, your browser will show a security warning the first time you open https://<host>:8443. This is expected. In Chrome/Edge choose Advanced → Proceed to <host>; in Firefox choose Accept the Risk and Continue. You only need to do this once per browser profile.

Other Use Cases

Beyond browsing recent sessions, kpsVibe is also useful in these less-obvious scenarios.