contextpilot-savings

name	contextpilot-savings
description	Use when a user asks how many tokens (or how much context/cost) ContextPilot has saved, or wants a ContextPilot savings status/summary inside Hermes Agent — e.g. "how much did ContextPilot save?", "show ContextPilot token savings", "ContextPilot status", "savings in the last 24h / all time", or "give me the raw savings JSON". This skill runs the metadata-only `scripts/contextpilot_savings.py` reporter and summarizes its output in plain language. It is read-only and observe-only — it never changes ContextPilot code or config, never enables routing/dropping/summarization, never creates cron jobs, branches, or pull requests, and never reads conversation messages, tool outputs, system prompts, reasoning, or raw session ids.
version	1.0.0
author	ContextPilot
license	MIT
metadata	{"hermes":{"tags":["contextpilot","hermes","telemetry","token-savings","observability","read-only"],"related_skills":[],"category":"observability","safety":"read-only"}}

ContextPilot Savings (Hermes)

This is a small, read-only skill: when a user wants to know how many tokens ContextPilot has saved, run the lightweight savings reporter and explain the result in plain language. That is the entire job — measure and report, nothing else.

Scope: show savings/status only. This skill never modifies ContextPilot code or config, never enables context routing/dropping/summarization, never schedules background jobs, and never edits the repository or opens code-change requests. If a user wants any of that, this is the wrong tool — stop and tell them so.

When to use this skill

• "How many tokens did ContextPilot save?"
• "Show me ContextPilot token savings" / "ContextPilot status".
• "Savings in the last 24 hours" / "savings all time".
• "Give me the raw savings data / JSON."

Privacy boundary (read this first)

The only thing this skill is allowed to read is the metadata-only telemetry file (~/.hermes/contextpilot/telemetry.jsonl), and it reads it only through scripts/contextpilot_savings.py. That file contains nothing but numeric counters (timestamps, chars saved, tokens saved).

Do not, under any circumstances:

• read ~/.hermes/state.db, conversation messages, or message content,
• read system prompts, skill prompts, or reasoning fields,
• read raw tool-call payloads or tool outputs,
• read or print raw session ids.

If you are ever tempted to inspect any of the above to "explain" the savings, don't — the script's metadata summary is the complete, safe answer.

How to run it

Step 1 — Locate the script

Use whichever of these exists (check in this order):

1. scripts/contextpilot_savings.py — when you are in a ContextPilot repo or plugin checkout (current working directory).
2. ~/.hermes/plugins/ContextPilot/scripts/contextpilot_savings.py — when ContextPilot was installed as a Hermes plugin.

Pick the first one that exists and use that path as <script> below.

Step 2 — Run the reporter

Default (last 24 hours):

python3 <script> --since-hours 24

Vary the command to match the request:

• All time — if the user asks for total/lifetime savings:

  python3 <script> --all-time
  

• A different window — e.g. last hour:

  python3 <script> --since-hours 1
  

• JSON / raw data — if the user asks for machine-readable output, raw data, or to feed a dashboard:

  python3 <script> --format json
  

  (Combine with --all-time or --since-hours N as needed.)

The script prints events, chars saved, estimated tokens saved, the time window, and average tokens per event. It imports no Hermes internals.

Step 3 — Summarize in plain language

Read the script's output and give the user a short, friendly summary: roughly how many tokens ContextPilot saved, over what window, and the event count. If they asked for JSON, show the JSON and add a one-line readout. Do not invent numbers — only report what the script printed.

When there are no savings yet

If the script reports no telemetry file or zero events in the window, tell the user (in plain language) to:

1. Enable ContextPilot in Hermes (hermes plugins → toggle contextpilot).
2. Restart Hermes.
3. Repeat a workload that reads the same content more than once (e.g. read a file, then read it again) — savings only fire when content repeats across turns.

You can also suggest --all-time to widen the window in case recent activity just fell outside the last 24 hours.

Installation note

For normal use, installing or copying this skill does not require a --force flag — only reach for --force if a skill installer reports an existing-name collision you intend to overwrite. The skill itself runs a single read-only Python command; it needs no special privileges.

Out of scope (do not do these)

This skill is deliberately narrow. It must not:

• modify ContextPilot source code or configuration,
• enable or tune context routing, dropping, or summarization,
• schedule background or recurring runs,
• edit the repository, run a test/merge workflow, or open code-change requests,
• train or evaluate any router, or run a propose/apply improvement loop.

If the user wants deeper monitoring (state.db metadata, opportunity scanning), point them at docs/guides/hermes-monitor.md. For integration mechanics, point them at docs/guides/hermes.md. This skill only answers "how much did ContextPilot save?".