Description

Track, analyze, and optimize AI and infrastructure costs with budgeting, spend forecasts, token usage scans, and optimization suggestions.

README (SKILL.md)

cost-guardian — AI & Infrastructure Cost Tracker

Name: Cost Guardian
Author: mariusfit

Track, analyze, and optimize the total cost of running your AI agent and infrastructure. Budget alerts, spend forecasts, and concrete optimization recommendations.

Commands

Initialize

python scripts/cost-guardian.py init

Creates config and database in ~/.openclaw/workspace/costs/.

Track a Cost Entry

# Track API spend
python scripts/cost-guardian.py track --provider openai --amount 12.50 --currency USD --period monthly --category api

# Track infrastructure cost
python scripts/cost-guardian.py track --provider hetzner --amount 5.00 --currency EUR --period monthly --category hosting

# Track one-time cost
python scripts/cost-guardian.py track --provider cloudflare --amount 10.00 --currency USD --period once --category domain

# Track electricity
python scripts/cost-guardian.py track --provider electricity --amount 15.00 --currency EUR --period monthly --category power

Scan Token Usage from Gateway Logs

# Scan recent gateway logs for token consumption per model
python scripts/cost-guardian.py scan-tokens

# Scan specific days
python scripts/cost-guardian.py scan-tokens --days 7

Set Budget

# Monthly budget
python scripts/cost-guardian.py budget --monthly 50.00 --currency EUR

# Budget with alert threshold (alert at 80%)
python scripts/cost-guardian.py budget --monthly 50.00 --alert-pct 80

Cost Report

# Current month report
python scripts/cost-guardian.py report

# Weekly report
python scripts/cost-guardian.py report --period week

# JSON output
python scripts/cost-guardian.py report --json

# Specific month
python scripts/cost-guardian.py report --month 2026-02

Optimization Recommendations

# Get optimization suggestions
python scripts/cost-guardian.py optimize

# JSON output
python scripts/cost-guardian.py optimize --json

Forecast Spend

# Forecast next 3 months
python scripts/cost-guardian.py forecast

# Forecast next N months
python scripts/cost-guardian.py forecast --months 6

# JSON output
python scripts/cost-guardian.py forecast --json

Manage Subscriptions

# Add a subscription
python scripts/cost-guardian.py sub add --name "OpenRouter" --amount 20.00 --currency USD --cycle monthly --renews 2026-03-15 --category api

# List subscriptions
python scripts/cost-guardian.py sub list

# Remove a subscription
python scripts/cost-guardian.py sub remove --name "OpenRouter"

# Check upcoming renewals
python scripts/cost-guardian.py sub upcoming --days 14

Status Dashboard

# Quick status overview
python scripts/cost-guardian.py status

# JSON output  
python scripts/cost-guardian.py status --json

Output Modes

All commands support:

Human-readable (default) — colored terminal output
JSON (--json) — structured data for programmatic use

Cron Integration

Add to OpenClaw cron for automated cost tracking:

Daily: scan-tokens to track API usage
Weekly: report --period week for digest
Monthly: report + forecast for full analysis
On-demand: optimize when looking to cut costs

Data Storage

All data stored in ~/.openclaw/workspace/costs/:

config.json — budget settings, preferences
costs.db — SQLite database (entries, subscriptions, token scans)

Zero Dependencies

Pure Python 3 stdlib — no pip install needed. Uses sqlite3, json, datetime, pathlib.

Usage Guidance

This skill appears coherent for cost tracking and token-scanning. Before installing or running it: (1) review the full scripts/cost-guardian.py source yourself (or in a sandbox) to confirm there are no unexpected network calls or obfuscated code; (2) confirm the gateway log paths it will scan (default ~/.openclaw/logs and /var/log/openclaw) so it does not read unrelated sensitive logs; (3) run init and first scans with limited filesystem permissions if possible; (4) back up any existing ~/.openclaw/workspace/costs/ data you care about. If you need higher assurance, request a full trace of any network activity the script performs when executed.

Capability Analysis

Type: OpenClaw Skill Name: cost-guardian Version: 1.0.0 The OpenClaw AgentSkills skill bundle 'cost-guardian' appears benign. The `SKILL.md` provides clear, non-malicious instructions for cost tracking and optimization. The Python script `scripts/cost-guardian.py` primarily interacts with a SQLite database and configuration files within the designated `~/.openclaw/workspace/costs/` directory. It scans gateway logs from specified directories (defaulting to `~/.openclaw/logs`) for token usage, but only reads and parses these files without executing their content or exfiltrating data. All database operations use parameterized queries, mitigating SQL injection risks. There is no evidence of data exfiltration, malicious execution, persistence mechanisms, prompt injection attempts against the agent, or obfuscation.

Capability Assessment

✓ Purpose & Capability

Name/description (cost tracking, token scans, budgets) align with the included script and SKILL.md: the script stores costs, scans gateway log directories for token usage, produces reports and budgets. No unrelated credentials or services are requested.

ℹ Instruction Scope

Instructions are specific to running the bundled Python script and its subcommands (init, track, scan-tokens, report, optimize). The script reads log files from a small set of expected OpenClaw gateway/log locations (e.g., ~/.openclaw/logs, /var/log/openclaw). This is expected for token scanning but means it will read any files found there — those logs can contain sensitive data, so verify the log paths before running.

✓ Install Mechanism

No install spec — instruction-only plus a pure-Python script that uses only the stdlib. Nothing is downloaded or written outside the user's data directory (~/.openclaw/workspace/costs/) except where it reads logs. This is low-risk for supply-chain installs.

✓ Credentials

The skill does not require credentials or privileged environment variables. It honors COST_GUARDIAN_DIR if set and uses NO_COLOR for output; these are reasonable and limited. No unrelated secrets are requested.

✓ Persistence & Privilege

Does not request always:true or system-wide privileges. It stores its database and config under ~/.openclaw/workspace/costs/ and creates files there when initialized — this is consistent with its purpose.

Version History

v1.0.0

Initial release: AI & infrastructure cost tracking with budget alerts, token scanning, subscriptions, forecasting, and optimization recommendations. 9 commands, JSON output, zero dependencies.

Metadata

Slug cost-guardian

Version 1.0.0

License —

All-time Installs 2

Active Installs 2

Total Versions 1

Frequently Asked Questions

What is Cost Guardian?

Track, analyze, and optimize AI and infrastructure costs with budgeting, spend forecasts, token usage scans, and optimization suggestions. It is an AI Agent Skill for Claude Code / OpenClaw, with 456 downloads so far.

How do I install Cost Guardian?

Run "/install cost-guardian" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Cost Guardian free?

Yes, Cost Guardian is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Cost Guardian support?

Cost Guardian is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Cost Guardian?

It is built and maintained by mariusfit (@mariusfit); the current version is v1.0.0.

More Skills

Cost Guardian