Skill: lcajigasm/openrouter-usage-info (version 0.1.0)

--- name: openrouter-usage description: "Track OpenRouter API spending — credit balance, per-model cost breakdown, and spending projections from OpenClaw session logs." metadata: { "openclaw": { "emoji": "💰", "requires": { "bins": ["openrouter-usage"] } } } --- # openrouter-usage Track your OpenRouter spending directly from your OpenClaw agent. Shows credit balance, per-model cost/token breakdown, and spending projections. ## Trigger Use when the user asks about OpenRouter credits, costs, spending, balance, usage, billing, or the `/usage` command. ## Commands ### Full report (recommended — combines everything) ```bash openrouter-usage report # credits + today's usage + projection openrouter-usage report --week # credits + last 7 days openrouter-usage report --month # credits + last 30 days ``` ### Credit balance only ```bash openrouter-usage credits ``` ### Per-model breakdown only ```bash openrouter-usage sessions --today openrouter-usage sessions --week openrouter-usage sessions --month openrouter-usage sessions --date 2026-02-25 openrouter-usage sessions --from 2026-02-01 --to 2026-02-15 ``` ### Filtering and output ```bash openrouter-usage report --agent main # specific agent only openrouter-usage report --format json # JSON output openrouter-usage sessions --today --utc # use UTC instead of local timezone ``` ## Notes - API key auto-discovered from OpenClaw auth store or `OPENROUTER_API_KEY` env var. - Session parsing is fully local — reads `~/.openclaw/agents/*/sessions/*.jsonl`. - Date filters use local timezone by default. Pass `--utc` to override. - Zero dependencies beyond Python 3 stdlib.

path: README.md
content: # openrouter-usage

An [OpenClaw](https://github.com/openclaw/openclaw) skill to track your OpenRouter API spending.

## Features

- **Full spending report** — Credit balance + per-model breakdown + projection in one command
- **Per-model cost breakdown** — Cost, tokens, cache stats per model from session logs
- **Date filtering** — `--today`, `--week`, `--month`, `--date`, `--from/--to`
- **Spending projection** — Estimates how long your credits will last
- **Multi-agent support** — Filter by agent with `--agent`
- **Local timezone** — Date filters use your local timezone by default
- **JSON output** — Machine-readable output for automation
- **Zero dependencies** — Python 3 stdlib only
- **Auto key discovery** — Reads API key from env var or OpenClaw auth store

## Install

```bash
git clone https://github.com/ZarpAIbot/openrouter-usage
cd openrouter-usage
./install.sh
```

The installer will:
1. Create a `openrouter-usage` CLI wrapper in `~/.local/bin/`
2. Optionally link it as an OpenClaw workspace skill
3. Warn you if `~/.local/bin` isn't in your PATH

## Usage

```bash
# Full report: credits + today's usage + projection
openrouter-usage report

# Report for a different period
openrouter-usage report --week
openrouter-usage report --month

# Credit balance only
openrouter-usage credits

# Per-model breakdown with various date filters
openrouter-usage sessions --today
openrouter-usage sessions --week
openrouter-usage sessions --month
openrouter-usage sessions --date 2026-02-25
openrouter-usage sessions --from 2026-02-01 --to 2026-02-15

# Filter by agent
openrouter-usage report --agent main

# JSON output
openrouter-usage report --format json

# Use UTC instead of local timezone
openrouter-usage report --today --utc
```

### Example output

```
═══ OpenRouter Credits ═══
  Total:      $10.0000
  Used:       $2.3200
  Remaining:  $7.6800
  Usage:      23.2%

═══ Usage by Model (today) ═══

  openai/gpt-5.2-chat
    Cost: $0.1823 (78.5%)  |  Requests: 42
    Tokens: 128,450 in / 34,200 out
    Cache: 89,000 read / 12,300 write

  google/gemini-2.0-flash
    Cost: $0.0498 (21.5%)  |  Requests: 15
    Tokens: 45,600 in / 12,800 out

  ──────────────────────────────
  TOTAL: $0.2321  |  57 requests  |  221,050 tokens

📊 Projection: ~$0.2321/day avg → credits last ~33 days
```

## API Key

The script looks for your OpenRouter API key in this order:
1. `OPENROUTER_API_KEY` environment variable
2. OpenClaw agent auth store (`~/.openclaw/agents/*/agent/auth.json`)

If you use OpenClaw with OpenRouter, the key is already configured — no extra setup needed.

## How it works

- **`credits`** — Calls OpenRouter's `/api/v1/credits` endpoint (falls back to `/api/v1/auth/key`)
- **`sessions`** — Parses OpenClaw's session JSONL files locally (no API calls). Extracts `usage.cost` data that OpenRouter includes in every completion response.
- **`report`** — Runs both, adds a daily spending projection based on your historical average.

## Compatibility

- Python 3.8+
- OpenClaw 2026.2.x+ (tested with v2026.2.23)
- macOS, Linux (anywhere Python 3 runs)

## License

MIT


path: install.sh
content: #!/bin/bash
set -euo pipefail

# ── openrouter-usage installer ───────────────────────────────────────────────
# Creates a CLI wrapper and optionally links as an OpenClaw workspace skill.

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT_PATH="${SCRIPT_DIR}/scripts/openrouter_usage.py"
BIN_DIR="${HOME}/.local/bin"
BIN_NAME="openrouter-usage"
SKILL_DIR="${HOME}/.openclaw/workspace/skills"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

echo "╔══════════════════════════════════════╗"
echo "║  openrouter-usage installer          ║"
echo "╚══════════════════════════════════════╝"
echo ""

# Check Python 3
if ! command -v python3 &>/dev/null; then
    echo -e "${RED}Error: python3 is required but not found.${NC}"
    exit 1
fi

# Ensure script is executable
chmod +x "${SCRIPT_PATH}"

# ── 1. Create CLI wrapper ────────────────────────────────────────────────────

mkdir -p "${BIN_DIR}"

cat > "${BIN_DIR}/${BIN_NAME}" << WRAPPER
#!/bin/bash
exec python3 "${SCRIPT_PATH}" "\$@"
WRAPPER
chmod +x "${BIN_DIR}/${BIN_NAME}"

echo -e "${GREEN}✓${NC} CLI installed: ${BIN_DIR}/${BIN_NAME}"

# Check PATH
if [[ ":${PATH}:" != *":${BIN_DIR}:"* ]]; then
    echo ""
    echo -e "${YELLOW}⚠ ${BIN_DIR} is not in your PATH.${NC}"
    echo "  Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):"
    echo ""
    echo "    export PATH=\"\${HOME}/.local/bin:\${PATH}\""
    echo ""
fi

# ── 2. Link as OpenClaw skill (optional) ─────────────────────────────────────

if [ -d "${HOME}/.openclaw" ]; then
    echo ""
    read -r -p "Link as OpenClaw workspace skill? [Y/n] " response
    response="${response:-Y}"
    if [[ "${response}" =~ ^[Yy]$ ]]; then
        mkdir -p "${SKILL_DIR}"
        LINK_TARGET="${SKILL_DIR}/${BIN_NAME}"

        if [ -L "${LINK_TARGET}" ] || [ -d "${LINK_TARGET}" ]; then
            rm -rf "${LINK_TARGET}"
        fi

        ln -s "${SCRIPT_DIR}" "${LINK_TARGET}"
        echo -e "${GREEN}✓${NC} Skill linked: ${LINK_TARGET} → ${SCRIPT_DIR}"

        # Suggest disabling model-usage if it exists
        if grep -q '"model-usage"' "${HOME}/.openclaw/openclaw.json" 2>/dev/null; then
            echo ""
            echo -e "${YELLOW}Tip:${NC} If you use OpenRouter (not Codex/Claude Code), consider disabling"
            echo "  the bundled model-usage skill to avoid conflicts:"
            echo ""
            echo '    "skills": { "entries": { "model-usage": { "enabled": false } } }'
        fi

        echo ""
        echo "  Restart the daemon to pick up the new skill:"
        echo "    openclaw daemon restart"
    fi
fi

# ── 3. Verify ────────────────────────────────────────────────────────────────

echo ""
if command -v "${BIN_NAME}" &>/dev/null; then
    echo -e "${GREEN}✓${NC} Ready! Try: ${BIN_NAME} report"
else
    echo -e "${GREEN}✓${NC} Installed. After updating PATH, try: ${BIN_NAME} report"
fi


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)