Skip to main content
plugin

cache-stats — GitHub Copilot plugin: what it does, how to install

cache-stats — a canvas plugin that shows live prompt-cache reuse, expiry, token composition, and AI Credit cost for the active GitHub Copilot session. It refreshes locally every two seconds.

MIT updated 2026-10-11

Install into GitHub Copilot · Command from the source All methods and platforms ↓
copilot plugin install cache-stats@awesome-copilot
Open on GitHub

What cache-stats does

The canvas has three views. Live Cache covers expiry state, reuse, and what a prefix rebuild would cost; Composition splits fresh input, cache reads, cache writes, output, and reasoning tokens; Turn History surfaces cold starts and rebuild costs per turn. Everything is read from ~/.copilot/session-store.db in read-only mode.

Cost is computed in AI Credits from each row's token_details_json, so figures follow the model that actually served the call rather than hard-coded prices. A turn gets flagged REBUILT when its entry call reads no cached prefix yet writes a substantial one.

You need a Copilot client with canvas-extension support, a Node.js runtime exposing node:sqlite, and a local session store with assistant_usage_events. The canvas is served from an ephemeral 127.0.0.1 port with no model calls, remote assets, or telemetry, so without those three pieces in place the stats simply will not appear.

What it helps with

  • see how much of the prompt is served from cache mid-session
  • track AI Credit cost of the session without model calls
  • break tokens down into input, cache reads and writes, output, and reasoning
  • spot turns where the cached prefix had to be rebuilt
  • watch cache expiry via the session.usage_checkpoint event

Example prompts for the agent

  • Open the cache stats canvas
  • Show me turn history and which turns were REBUILT
  • How much has this session cost in AI Credits so far?

How to install cache-stats

Command from the source

copilot plugin install cache-stats@awesome-copilot

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about cache-stats

How do I install cache-stats in GitHub Copilot?

Run copilot plugin install cache-stats@awesome-copilot, then ask Copilot to open the cache stats canvas.

What does cache-stats show?

A local canvas with prompt-cache reuse and expiry, per-category token composition, and session cost in AI Credits, refreshed every two seconds while the session runs.

Does cache-stats consume tokens or send data anywhere?

No. It opens ~/.copilot/session-store.db read-only and serves the canvas from an ephemeral 127.0.0.1 port, without model calls, remote assets, or telemetry.

Source text

SKILL.md · MIT
# Cache Stats

A local-first GitHub Copilot canvas for understanding prompt-cache reuse, expiry,
token composition, and AI Credit cost while a session is still active.

![An illustrative Cache Stats canvas showing live cache health and AI Credit exposure](assets/preview.png)

> Preview data is illustrative and does not contain session information.

The one-bit HyperCard stack has three focused views:

- **Live Cache** shows expiry state, reuse, and the cost exposed if the reusable
  prompt prefix must be rebuilt.
- **Composition** separates fresh input, cache reads, cache writes, output, and
  reasoning tokens.
- **Turn History** makes cold starts and rebuild costs visible turn by turn.

The canvas refreshes locally every two seconds. Opening and using it consumes no
model tokens.

## Install

In a GitHub Copilot session, ask:

> Install this extension: https://github.com/arafattehsin/cache-stats-extension

Then ask:

> Open the cache stats canvas

Before marketplace approval, install the public repository directly:

```shell
copilot plugin install arafattehsin/cache-stats-extension
```

After marketplace approval, install it from Awesome Copilot:

```shell
copilot plugin install cache-stats@awesome-copilot
```

## Requirements

- A GitHub Copilot client with canvas-extension support
- A Node.js runtime with the built-in `node:sqlite` module
- A local Copilot session store containing `assistant_usage_events`

## Privacy

Cache Stats reads `~/.copilot/session-store.db` in read-only mode and serves the
canvas from an ephemeral `127.0.0.1` port. It does not modify the session store,
call a model, load remote assets, or send telemetry.

The local canvas API includes the active session ID and database path in its
response for diagnostics. That endpoint is available only through the loopback
server created for the open canvas instance.

## How the numbers work

`input_tokens` is the complete prompt for one model call:

```text
fresh input = input_tokens - cache_read_tokens - cache_write_tokens
```

Per-token billing rates come from each row's `token_details_json`, so baseline
cost, actual cost, savings, and rebuild exposure follow the model that served
the call instead of relying on hard-coded prices. Costs are shown in AI Credits
(AIC), converted from the store's nano-AIU values at 1 AI Credit = 1e9 nano-AIU.

A turn starts with one user-initiated call and includes its agent, sub-agent,
and compaction follow-ups. A turn is marked `REBUILT` when its entry call reads
no cached prefix but writes a substantial one. Live expiry comes from Copilot's
`session.usage_checkpoint` event, using the cache entry for the model the main
conversation called last.

## Development

```shell
npm install
npm run check
copilot plugin install .
```

Reinstall the local plugin after changing source files because Copilot caches
installed plugin content.

## Package layout

| Path | Role |
| --- | --- |
| `plugin.json` | Agent Plugins v1 manifest and Copilot catalog metadata |
| `copilot-extension.json` | Direct canvas-extension install metadata |
| `extension.mjs` | Direct-install bridge to the packaged extension |
| `com.github.copilot/extensions/cache-stats/` | Spec-namespaced canvas extension package |
| `assets/preview.png` | Anonymized catalog preview |
| `scripts/` | Package and embedded-UI checks |
| `docs/PUBLISHING.md` | Public release and Awesome Copilot submission guide |

## Environment overrides

- `COPILOT_CACHE_STATS_DB` - explicit path to the session store
- `COPILOT_HOME` - alternate Copilot home directory

## License

[MIT](LICENSE)

© Arafat Tehsin · MIT · arafattehsin/cache-stats-extension

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open