costguard

Drive Costguard — a read-only cost auditor for CI minutes, cron schedules,

and cloud provider billing (GitHub Actions, Vercel, Supabase, Railway, Netlify, Neon, Cloudflare, and more).

It finds waste, estimates the monthly dollar cost, and can surgically auto-fix

CI workflow files. It never writes to provider accounts, never pushes git, and

never prints tokens.

Map the user's request to one Costguard CLI call and run it from the repo root.

Command launcher

Costguard reads a workspaces.json registry from the **current working

directory**, so run it from a project that has one (or run registry init

first). Pick the launcher that matches your context; below, `costguard

<subcommand>` means whichever you use.

If installed via plugin

When this skill is loaded from the Costguard plugin, run the bundled build — it

ships a prebuilt dist/cli/index.js, so no build step is needed. Locate the

plugin root (the dir containing dist/cli/index.js):

• Claude Code — it is ${CLAUDE_PLUGIN_ROOT}:

  node "${CLAUDE_PLUGIN_ROOT}/dist/cli/index.js" <subcommand> ...

• Codex — walk up from this SKILL.md to the dir holding

.codex-plugin/plugin.json:

  node "<plugin-root>/dist/cli/index.js" <subcommand> ...

If using npx (no plugin)

No checkout and no build — run the published CLI directly:

npx -y -p @costguard/costguard-mcp costguard <subcommand> ...

Or, if costguard is on PATH (npm i -g @costguard/costguard-mcp), use it

directly: costguard <subcommand> .... Heads-up: npx -y @costguard/costguard-mcp

(no -p, no subcommand) starts the MCP server, whereas `npx -y -p

@costguard/costguard-mcp costguard <subcommand>` runs the CLI.

1. Audit for waste (the main action)

costguard audit <workspace...>            # named workspaces
costguard audit --all                     # every registered workspace
costguard audit <ws> --providers all      # + read-only cloud billing checks
costguard audit <ws> --ci-only            # static CI checks only
costguard audit <ws> --crons-only         # cron checks only
costguard audit <ws> --site               # + read-only live-site checks (site URL from registry)
costguard audit <ws> --substitutions      # + cross-tool cheaper-alternative suggestions
costguard audit <ws> --json               # JSON instead of Markdown

Prints a report: each finding has a severity, an estimated monthly USD cost, a

detail, and a fix suggestion. Report stdout verbatim.

2. Scan / registry / report

costguard scan                # discover CI + cron files under the registry root
costguard registry list       # show registered workspaces
costguard registry init       # create a workspaces.json in the cwd
costguard report              # re-render the last saved audit run

3. Auto-fix CI files (dry-run first)

costguard fix <ws>            # dry-run: print a unified-diff preview, write nothing
costguard fix <ws> --apply    # write the surgical edits to disk (idempotent)
costguard fix <ws> --pr       # also emit local PR artifacts (no push)

Default is dry-run. Only deterministic ADD-rule fixers run (timeout,

concurrency, paths-ignore). Costguard never pushes; --open-pr is gated and

refuses without an explicit token.

4. Monthly cost digest

costguard digest             # render the digest from the last run (dry-run)
costguard digest --post      # delivery adapter (inert unless configured)

5. Auto-discover providers

Detect which providers a repo uses — from config files, package.json deps, and

env-var names (never values, never secrets). Covers all 13 wired providers

plus inngest.

costguard discover [dir]     # list detected providers + evidence (default dir: .)
costguard discover . --json  # JSON: { dir, providers, detections }
costguard discover . --write # union-merge detected providers into ./workspaces.json (non-destructive)

6. Live-site cost checks

Read-only, GET-only checks on a live URL (no browser, no form submit, no auth

replay). Flags transfer weight, oversized images, missing compression, weak cache

headers, and render-blocking scripts. The $/mo headline is the single

site/transfer-weight line — sourced when the host bills transfer (Vercel/Netlify),

or an explicit $0 performance note (Cloudflare Pages static / unknown host).

Per-asset findings (oversized-image, missing-compression) put their dollar share

in detail and carry estMonthlyUsd: 0 (no double-count); a $0 performance-only

page never raises a high finding, so it never fails CI on cost alone.

costguard site <url>         # Markdown report
costguard site <url> --json  # JSON findings

audit --site runs the same checks for any workspace whose workspaces.json

entry has a site URL. audit --substitutions adds cross-tool

<provider>/cheaper-alternative suggestions (e.g. a static Vercel/Netlify Pro

site → Cloudflare Pages), each with a sourced saving, migration effort, and

lock-in caveat.

Provider billing checks

--providers <ids|all> adds read-only billing checks for the providers listed

on each workspace in workspaces.json. Tokens are read from the environment /

.env only. A provider whose token env var is absent is skipped, not

failed. Supported: github, supabase, railway, netlify, neon, vercel,

sentry, upstash, atlas, cloudflare, fly, render, datadog (+ inngest

detection).

7. MCP tools (for AI coding agents)

Costguard also ships a bundled MCP server that exposes the same engine over a

host-agnostic tool surface (Claude Code, Codex, any MCP host). It wraps the same

read-only engine functions — no new behavior, same posture. In Claude Code it is

declared by .claude-plugin/.mcp.json and launched from the bundled build:

{ "mcpServers": { "costguard": { "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"] } } }

In the plugin, the server runs from the committed dist/mcp/server.js — no

install step.

Codex MCP config

For Codex, add one of these to ~/.codex/config.toml. Use npx for a

no-checkout install (pulls the published package), or the bundled build if you

run Codex from the plugin:

# npx — no checkout
[mcp_servers.costguard]
command = "npx"
args = ["-y", "@costguard/costguard-mcp"]

# bundled plugin build
[mcp_servers.costguard]
command = "node"
args = ["<plugin-root>/dist/mcp/server.js"]

Tools:

| Tool | Posture |

|---|---|

| audit_workspace | read-only; returns a Findings envelope (includeSite adds site checks) |

| discover_providers | read-only; env-var NAMES only, never values |

| audit_site | read-only, GET-only |

| plan_fix | dry-run; returns unified diffs only, writes nothing |

| apply_fix | writes local CI files; REFUSES unless confirmApply:true; never pushes git |

| plan_live_checks | plans a live billing read (see below); emits a snippet only with consent |

| ingest_live_reading | parses a returned billing figure into a Finding |

8. Live billing checks (--live) — opt-in, consent-gated

--live extends the read-only posture above: it adds **browser-driven reads

over your already-logged-in session, performed by the playwriter** MCP server

under the agent's orchestration. This is a genuine posture change and is treated

as one — off by default, opt-in, and consent-gated. costguard's own tools

still never drive a browser and never see credentials: plan_live_checks only

emits a read-only snippet (navigation + reading rendered billing figures — no

clicks, typing, form submits, credential replay, cookies, localStorage,

sessionStorage, or screenshots), and ingest_live_reading only parses the

returned figure. The browser action is performed by playwriter, authorized by you.

API-first / browser-fallback: plan_live_checks is API-first when a provider

module exists and its API token resolves from the environment (a deterministic

env-NAME check, no network probe) — in that case prefer audit_workspace. Only

when there is no usable API token does it fall back to a browser playbook.

Three consent gates (all required): (1) the host's MCP tool-call consent;

(2) costguard's own per-run confirmation — plan_live_checks returns a

consentNotice the agent MUST surface, and emits the actionable snippet only when

called with confirmLive:true; (3) playwriter's own consent before it executes.

Graceful degrade: if playwriter is not connected, the agent cannot run the

snippet; ingest_live_reading returns a kind:"diagnostic" Finding (excluded

from cost totals) and the audit never blocks.

Notes

• All provider calls are read-only (GET / read-only GraphQL). No POST/PUT/PATCH/

DELETE to provider accounts.

• Estimated dollar costs are best-effort and depend on plan/tier; treat them as

directional, not invoices.

• Requires node on PATH. The bare costguard command is optional when the

skill runs from the plugin — use the plugin-root node launcher above.