efficientcontext/contextpilot/contextpilot-savings

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).

1. ~/.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:

``bash python3 <script> --all-time ``

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

``bash python3 <script> --since-hours 1 ``

• JSON / raw data — if the user asks for machine-readable output, raw data,

or to feed a dashboard:

``bash python3 <script> --format json ``

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

The script prints events, chars saved, telemetry tokens saved, the time window, and average tokens per event.

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?".