# Xerg — Agent Skill

Use Xerg to audit, track, and optimize AI agent inference spend.

## When to use this skill

- After deploying agents or making changes that affect model usage
- To check if agents are wasting money on retries, oversized models, or idle loops
- To push audit results to the hosted Pro dashboard for trend tracking
- In CI pipelines to gate deploys on waste thresholds

## Install

```bash
npm install -g @xerg/cli
```

## Commands

### Run a local audit
```bash
xerg audit
```
Analyzes OpenClaw logs in the default locations and prints a spend report with waste findings.

### Audit a remote host
```bash
xerg audit --remote user@vps.example.com
```
Pulls logs from a remote host over SSH, analyzes locally. Zero installation on the server.

### Push to dashboard
```bash
xerg audit --push
```
Pushes audit results to https://xerg.ai/dashboard. Requires an active Pro workspace and `XERG_API_KEY`.

### Check before sending
```bash
xerg audit --push --dry-run
```
Prints the exact payload that would be sent, without sending it.

### CI gating
```bash
xerg audit --fail-above-waste-rate 0.25
```
Exits with code 3 if the waste rate exceeds the threshold. Use in CI to block deploys.

### JSON output for programmatic use
```bash
xerg audit --json
```
Full structured output including findings and recommendations.

## Environment variables

- `XERG_API_KEY`: API key for pushing audits (get it from your Pro workspace in xerg.ai/dashboard/settings)
- `XERG_API_URL`: Override API base URL (default: https://api.xerg.ai)

## What Xerg detects

- **Model waste**: Using expensive models (GPT-4, Opus) for tasks achievable with cheaper ones
- **Retry storms**: Excessive retries multiplying cost without adding value
- **Context bloat**: Sending unnecessarily large contexts that inflate token costs
- **Idle loops**: Agents polling or looping without productive output
- **Optimization opportunities**: Model downgrades, context trimming, loop collapsing

## Links

- Documentation: https://xerg.ai/docs
- Dashboard: https://xerg.ai/dashboard (Pro)
- GitHub: https://github.com/xergai/xerg
- npm: https://www.npmjs.com/package/@xerg/cli