burnbar-operator

name	burnbar-operator
description	Use when asked about AI-agent spend, token usage, session history, workflow patterns, or cost investigations. Grounds all answers in OpenBurnBar/BurnBar local data via prompt context and MCP tools.
version	1.0.0
author	OpenBurnBar
license	AGPL-3.0-only
metadata	{"hermes":{"tags":["burnbar","openburnbar","ai-agents","token-usage","spend-analysis","session-recall","workflow","debugging","observability","cost"],"related_skills":["systematic-debugging"]}}

BurnBar Operator

You have direct access to this developer's OpenBurnBar database — a local SQLite store that captures every AI agent session, token usage event, cost, and conversation transcript across all providers (Claude Code, Factory Droid, Codex, Kimi, MiniMax, etc.).

When to Use This Skill

Activate for any question about:

• Spend / cost — "How much have I spent on Claude this week?" / "What's burning the most money?"
• Session recall — "What was I working on yesterday?" / "Find sessions where I fixed quota bugs"
• Workflow coaching — "Where am I wasting tokens?" / "Which projects cost the most per session?"
• Debug investigations — "Why did cost spike on Tuesday?" / "Show me the session where XYZ broke"

Mobile Skill Runs

Hermes skills that can become long-running BurnBar work should dispatch as Skill Runs instead of plain chat. Skill Runs are preview-first, then the phone/tablet writes a users/{uid}/cli_agent_mission_requests/{id} document that the trusted Mac claims. iOS, iPadOS, and Android then follow the same live event timeline in Mission Console.

Skill IDs

Use these stable sourceSkillID values when a run maps cleanly to a product skill:

Skill	sourceSkillID	User job
What Happened?	what_happened	Explain the last session or time window in plain English.
Burn Forensics	burn_forensics	Find the spend spike, noisy model, or quota drain and cite evidence.
Pattern Miner	pattern_miner	Detect repeated workflow/cost patterns across recent sessions.
Compare Agents	compare_agents	Compare providers/runtimes on quality, spend, or latency for a job.
Next Action Coach	next_action_coach	Turn messy session history into the next concrete action.
Handoff Builder	handoff_builder	Build a resume-ready brief for another agent/runtime.
Regression Watch	regression_watch	Watch for a recurring failure or behavior drift and report it.
Run Pulse	run_pulse	Stream a concise live pulse while the Mac is executing a mission.

Dispatch Contract

Every mobile-originated Skill Run request should include:

• sourceSkillID: one of the values above when applicable.
• sourceSurface: ios-insights, ios-hermes-square, ipad-hermes-square, android-insights, or android-hermes-square.
• deliveryMode: action_only, full_stream, or muted.
• parentHermesThreadID: optional thread/session ID when the run is a continuation of a Hermes conversation.
• schemaVersion: 3.

Every event can include:

• eventImportance: quiet, normal, action_required, or terminal.
• skillStepID: stable step token such as queued, reading_ledger, awaiting_approval, writing_artifact, or done.
• deliveryMode: copied from the request so companion surfaces can decide whether to show every event or only action/final events.

Delivery modes are user-customizable from the iOS/iPadOS and Android agent subscription sheets:

• action_only: quiet default; interrupt only for approval prompts and final results.
• full_stream: show the full live timeline as the Mac writes events.
• muted: no alerts; the run remains available in Mission Console.

Evidence Sources

Two layers, used in order of specificity:

Source	When to use
BurnBar prompt context	Simple questions answerable from recent sessions/spend already in the system prompt
openburnbar_local MCP tools	Exact counts, timelines, session transcripts, cross-session patterns

MCP Tools Reference

Tools are registered with the prefix mcp_openburnbar_local_:

Tool	Use for
mcp_openburnbar_local_burnbar_list_providers	Enumerate tracked providers (Claude Code, Codex, Factory Droid, etc.)
mcp_openburnbar_local_burnbar_recent_usage	Exact cost/token rows ordered by date; primary tool for spend questions
mcp_openburnbar_local_burnbar_project_summary	Pre-aggregated per-project cost + session summary over a time window
mcp_openburnbar_local_burnbar_search_conversations	FTS search over session transcripts; use for recall and debug
mcp_openburnbar_local_burnbar_semantic_search_conversations	Local semantic search over indexed chunks when deterministic embeddings are present
mcp_openburnbar_local_burnbar_cloud_semantic_search_conversations	Hosted encrypted semantic search; requires cloud auth/vault env and decrypts snippets locally
mcp_openburnbar_local_burnbar_cloud_get_conversation_body	Decrypt full hosted encrypted session text from a cloud search hit
mcp_openburnbar_local_burnbar_index_project	Build the local Project Code Memory index through the daemon write path
mcp_openburnbar_local_burnbar_search_code	Search indexed local project code; snippets are wrapped as untrusted content
mcp_openburnbar_local_burnbar_code_context_pack	Build a token-budgeted context pack from indexed code
mcp_openburnbar_local_burnbar_get_symbol	Find symbols with exact_lsp, static_tree_sitter, or lexical_fallback tier evidence
mcp_openburnbar_local_burnbar_find_references	Find references for a symbol with tier evidence and stale-index degradation
mcp_openburnbar_local_burnbar_call_graph	Traverse bounded call graph edges from indexed code
mcp_openburnbar_local_burnbar_index_status	Inspect Project Code Memory index readiness, encryption, parser, and semantic status
mcp_openburnbar_local_burnbar_memory_doctor	Diagnose memory/code schema, daemon write mode, and code-memory production readiness
mcp_openburnbar_local_burnbar_get_conversation	Full transcript for a specific session by ID
mcp_openburnbar_local_burnbar_chat_messages	Prior in-app assistant chat history (continuity questions)
mcp_openburnbar_local_burnbar_resolve_db_path	Debug: confirm which DB file is being read
mcp_openburnbar_local_burnbar_record_hermes_usage	Write: append an exact usage row to OpenBurnBar's daemon ledger
mcp_openburnbar_local_burnbar_resolve_usage_ledger_path	Debug: show the ledger path the writer will use

burnbar_record_hermes_usage is the only write tool — it never touches the SQLite DB. It is daemon-first: when a local OpenBurnBar daemon is running it goes through the daemon.usage.record RPC so the daemon's idempotency cache stays consistent; when the daemon is offline it falls back to an append on the ledger file. Use it when:

• you want OpenBurnBar to know about a Hermes call you just made (cost guardrails, end-of-session summaries, post-run reports)
• the OpenBurnBar daemon may be offline (the tool still appends to the ledger so the next app launch picks it up)
• the upstream provider returned exact usage you can pass through (set confidence="exact"); for fallbacks set confidence="low_confidence_estimate"

Operating Procedure

Step 1 — Classify the request

Identify the primary job:

• recall/explain — "What was I doing?", "Find the session where..."
• quantify/analyze — "How much did X cost?", "Which model is most expensive?"
• investigate/pattern-find — "Why did X happen?", "What patterns show up across sessions?"
• coach/recommend — "Where am I wasting tokens?", "How can I reduce spend?"

Step 2 — Check prompt context first

If the answer is visible in the ambient BurnBar context (recent sessions list, weekly spend mix, latest assistant message), answer directly and label it:

[source: BurnBar prompt context]

Step 3 — Escalate to MCP for exact evidence

Use MCP tools when:

• Exact numbers are needed (not approximations from prompt context)
• Searching session transcripts
• Analyzing beyond the 7-day window in prompt context
• Cross-session pattern detection

Decision tree:

recall/explain:
  → burnbar_search_conversations(query)
  → burnbar_get_conversation(id) for transcript

quantify/analyze:
  → burnbar_recent_usage(limit=100) then aggregate in reasoning
  → burnbar_project_summary(project_name, days) for project-level rollup

investigate:
  → burnbar_search_conversations to find candidate sessions
  → burnbar_get_conversation for deep transcript dives
  → burnbar_search_code / burnbar_get_symbol when the question is about local source truth

coach/recommend:
  → burnbar_recent_usage to establish baseline
  → burnbar_project_summary per top project
  → synthesize patterns, then recommend

Step 4 — Compose the response

Every BurnBar-grounded response must include:

1. Direct answer — lead with the answer, not "I found..."
2. Evidence — 2–5 bullets citing specific sessions, costs, or patterns from tool results
3. Source label — state [source: BurnBar prompt context] or [source: MCP — burnbar_recent_usage]
4. Operator next steps (optional) — if the user might want to act, suggest what Hermes can do next

Step 5 — Operator actions (when asked to act)

If the user asks Hermes to act on findings (draft a budget rule, create a report file, set a reminder):

1. Complete BurnBar analysis first (read-only)
2. Explicitly separate: "Based on BurnBar data [facts], I'm now going to [action]..."
3. Use Hermes's normal tools (terminal, file, web, etc.) for the action

Response Contract

• Never invent sessions, costs, or transcript content. If MCP returns no results, say so plainly.
• Never guess token counts or costs — only cite what MCP tools return.
• Always label the evidence source (prompt context vs MCP tool name).
• BurnBar data is read-only — never attempt to modify the SQLite database.
• For MCP connection errors, fall back to prompt context and note the degraded state.

Safety / Non-Goals

• Do NOT read from sources outside OpenBurnBar tables
• Do NOT cross-reference external billing dashboards — local data only
• Do NOT expose full conversation transcripts unless the user explicitly requests them
• Do NOT write to the BurnBar database

Example Prompts

Spend analysis:

• "What did I spend on AI agents this week? Break it down by provider."
• "Which project cost the most in April?"
• "Show me my top 10 most expensive sessions."
• "Am I spending more or less than last week?"

Session recall:

• "Find sessions where I was debugging quota issues."
• "What was I working on last Tuesday?"
• "Did I ever work on the ProviderQuota UI? Show me the sessions."
• "Find the session where I first touched the CLIBridge file."

Workflow coaching:

• "Based on my last 30 sessions, where am I spending tokens inefficiently?"
• "Which provider gives me the best output per dollar?"
• "Which model do I use most and is it the cheapest option?"

Debug investigations:

• "My Claude spend spiked yesterday — what was I doing?"
• "Show me all sessions longer than 2 hours from this month."
• "Why did Factory Droid cost more than Claude last week?"

When MCP Is Not Available

If openburnbar_local MCP tools are not connected, say:

"The openburnbar_local MCP server is not available. I can answer from the BurnBar prompt context already in this conversation, but for exact counts, cost breakdowns, or session transcripts you'll need to connect the MCP server. See ~/.hermes/skills/software-development/burnbar-operator/SKILL.md for setup instructions."

Then answer from prompt context with appropriate uncertainty bounds.

Setup Reference

The MCP server lives at tools/openburnbar-mcp/server.py inside the OpenBurnBar repo. It requires a Python venv:

cd /path/to/OpenBurnBar/tools/openburnbar-mcp
./setup.sh

Hermes config.yaml entry (already configured if this skill is active):

mcp_servers:
  openburnbar_local:
    command: "/path/to/OpenBurnBar/tools/openburnbar-mcp/.venv/bin/python"
    args: ["/path/to/OpenBurnBar/tools/openburnbar-mcp/server.py"]
    timeout: 30
    connect_timeout: 20

Hermes Proxy (optional)

tools/openburnbar-mcp/hermes_proxy.py is a stdlib-only OpenAI-compatible sidecar that runs in front of hermes gateway run and writes usage rows to the OpenBurnBar ledger automatically. Point OpenBurnBar mobile/desktop at the proxy instead of Hermes directly to capture spend even when the macOS app is asleep:

python3 tools/openburnbar-mcp/hermes_proxy.py \
    --listen 127.0.0.1:8643 \
    --upstream http://127.0.0.1:8642 \
    --provider-id hermes \
    --project-name "Hermes (proxy)"

Use --no-estimate to skip recording when the upstream response does not include usage (the default records a low_confidence_estimate row instead).

Creative plugin workflows

Once burnbar_record_hermes_usage is available, Hermes can do things the read-only skill could not:

• Spend-aware answers — call burnbar_recent_usage before responding to long queries, abort if today's Hermes spend exceeds the user's stated budget, and explain why.
• Cost guardrails — annotate responses with the running total Hermes has spent in this session (use session_id consistently to keep ledger rows groupable).
• Session memory — record an explicit provider_id="hermes" row at the end of every Hermes turn, even when no model token usage is available, with confidence="derived_exact" and a cost=0. OpenBurnBar will still surface the session in the dashboard so the user can recall it.
• "Why did this spike?" investigations — when the user asks why their spend spiked, query burnbar_recent_usage, find the largest delta, then use burnbar_search_conversations to pull the matching transcript and summarize the root cause.
• Post-run summaries — at the end of a long Hermes run, write a final row with confidence="exact" and project_name=<the user's project>, then optionally open the OpenBurnBar dashboard so the user can audit the run.
• Mobile direct-host usage — if OpenBurnBar mobile points at the proxy, Hermes itself does not need to do anything: the proxy records exact usage on each request automatically.