Metadata-Version: 2.4
Name: yburn
Version: 1.0.1
Summary: Why burn tokens? Audit AI agent cron jobs, replace mechanical ones with local scripts. Includes yburn-health (system monitor) and yburn-watch (uptime monitor).
Author: Jason Haugh
License-Expression: MIT
Project-URL: Homepage, https://github.com/oscarsterling/yburn
Project-URL: Repository, https://github.com/oscarsterling/yburn
Project-URL: Issues, https://github.com/oscarsterling/yburn/issues
Keywords: ai,automation,cron,monitoring,health-check,token-optimization,openclaw,claude-code,devops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# yburn

**Why burn tokens on tasks that don't think?**

Audit your AI agent cron jobs, identify the ones that never needed an LLM, and replace them with local scripts that run in under a second and cost nothing. Plus standalone health monitoring tools that work on any machine.

![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-252%20passing-brightgreen)

```bash
pip install yburn
```

---

## 30-Second Quickstart

```bash
# See what you're burning tokens on
yburn audit

# Check your system health (no tokens, no LLM, instant)
yburn-health

# Monitor your endpoints
yburn-watch https://yoursite.com https://api.yoursite.com/health
```

That's it. Three commands. Zero configuration needed.

---

## The Problem

Real numbers from a live 97-cron OpenClaw deployment (March 2026):

- **51 of 97 crons (53%) were mechanical** - the LLM was doing nothing a shell script couldn't do faster
- **~30 seconds per LLM cron** drops to **under 1 second** with a local script
- Common culprits: system health checks, DB maintenance, git backups, cron audits, uptime monitoring

Your AI agent is spending 30 seconds and burning tokens to check if your disk is full. A Python script does it in 200ms for free.

The community has been discovering this one job at a time. Developers at Moltbook AI manually replaced OpenClaw crons with Python scripts. Others cut AI agent costs by 60% by auditing crons and switching models. Yburn automates what they all did by hand.

---

## What's In The Box

### The Audit Engine (scan, classify, convert, replace, rollback)

Five verbs, one tool, zero tokens after conversion:

```
$ yburn audit

Scanning cron jobs...
Found 97 jobs. Classifying...

  Mechanical:  51 jobs (convertible)
  Reasoning:   16 jobs (kept as-is)
  Unsure:      30 jobs (need your input)

--- MECHANICAL (convertible) ---
  DB Maintenance - Daily Full [enabled]
    Score: mech=16 reason=0 conf=1.00
    Template -> system-diagnostics

  Nightly Backup + Git Commit [enabled]
    Score: mech=17 reason=2 conf=0.79
    Template -> git-backup-status

  Daily Cron Health Report [enabled]
    Score: mech=11 reason=1 conf=0.83
    Template -> cron-health-report
  ...
```

Classification is deterministic keyword scoring. No LLM call needed. The tool that finds your LLM waste does not itself create LLM waste.

### yburn-health: System Health Monitor

Three modes for three audiences. One install.

**Universal (any machine):**
```
$ yburn-health

yburn-health v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ CPU: 12% (10 cores)
✅ Memory: 8.2/16 GB (51%)
✅ Disk /: 45% (234 GB free)
⚠️ Disk /data: 87% (12 GB free)
✅ Load: 1.2, 0.8, 0.5
✅ Uptime: 14 days, 3 hours
✅ Docker: 12 containers (11 running)
✅ Network: reachable (23ms)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: WARNING (1 alert)
```

**OpenClaw users** get gateway, cron, session, and channel health:
```
$ yburn-health --openclaw

... (all universal checks) ...

--- OpenClaw ---
✅ Gateway: running (v0.26.1, up 3d 14h)
✅ Crons: 97 total (92 enabled, 5 disabled)
⚠️ Cron failures: 2 jobs with 3+ consecutive failures
✅ Sessions: 4 active, 0 stuck
✅ Channels: Telegram connected, Discord connected
✅ Memory DB: 142 MB (healthy)
```

**Claude Code users** get scheduled task and session checks:
```
$ yburn-health --claude-code

... (all universal checks) ...

--- Claude Code ---
✅ CLI: claude available (v1.2.3)
✅ Sessions: 3 recent
✅ Scheduled tasks: 5 active, 0 expired
```

### yburn-watch: Endpoint and Uptime Monitor

```
$ yburn-watch https://clelp.ai https://api.example.com/health

yburn-watch v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ https://clelp.ai - 200 OK (285ms)
   SSL: valid, 35 days remaining
✅ https://api.example.com/health - 200 OK (89ms)
   SSL: valid, 45 days remaining
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: ALL UP (2 endpoints)
```

Checks HTTP status, response time, and SSL certificate expiry. Warns at 14 days, critical at 7.

---

## Installation

```bash
pip install yburn
```

Requires Python 3.9+. Works on macOS and Linux (including WSL).

The flagship tools (`yburn-health`, `yburn-watch`) use stdlib only. Zero dependencies. The audit engine uses `requests` and `pyyaml` (installed automatically).

---

## How The Audit Engine Works

```
scan -> classify -> convert -> replace -> (rollback if needed)
```

1. **Scan:** Reads your cron jobs via `openclaw cron list` (or any JSON file with `--file`).

2. **Classify:** Scores each job against weighted keyword sets. Mechanical signals: shell commands, file ops, status checks. Reasoning signals: analysis, drafting, strategy, synthesis. No LLM call needed.

3. **Convert:** Matches mechanical jobs to built-in templates. Generates standalone Python scripts that replicate the job without an LLM. Preview before confirming.

4. **Replace:** Disables the original LLM cron, activates the script-based equivalent on the same schedule. Tracks everything for rollback.

5. **Rollback:** One command restores the original. `yburn rollback <job-id>`. Originals are never deleted.

---

## Full Command Reference

### Audit

```bash
yburn audit                    # Scan and classify all cron jobs
yburn audit --verbose          # Show reasoning jobs too
yburn audit --threshold 2      # Lower threshold (more jobs classified)
yburn audit --file jobs.json   # Audit from a JSON file
```

### Convert

```bash
yburn convert <job-id>         # Convert one job to a local script
yburn convert --all            # Convert all mechanical jobs
yburn convert --all --dry-run  # Preview without writing files
```

### Replace

```bash
yburn replace <job-id>         # Swap original cron for script version
yburn replace <job-id> --yes   # Skip confirmation
yburn replace <job-id> --dry-run
```

### List, Test, Rollback

```bash
yburn list                     # Show all active replacements
yburn test <job-id>            # Run converted script once, show output
yburn rollback <job-id>        # Restore original cron
```

### Health and Watch

```bash
yburn-health                   # System health (universal)
yburn-health --openclaw        # + OpenClaw checks
yburn-health --claude-code     # + Claude Code checks
yburn-health --json            # JSON output for piping
yburn-health --processes nginx,postgres  # Watch specific processes

yburn-watch https://example.com          # Check one URL
yburn-watch url1 url2 url3               # Check multiple
yburn-watch --json                       # JSON output
yburn-watch --timeout 5                  # Custom timeout (seconds)
yburn-watch --warn-ms 2000              # Response time warning threshold
```

---

## Alert Channels

Both `yburn-health` and `yburn-watch` support sending alerts via:

- **stdout** (default)
- **Telegram** (`YBURN_TELEGRAM_TOKEN` + `YBURN_TELEGRAM_CHAT_ID`)
- **Discord** (`YBURN_DISCORD_WEBHOOK`)
- **Slack** (`YBURN_SLACK_WEBHOOK`)

Set via environment variables or `~/.yburn/health.yaml` / `~/.yburn/watch.yaml`.

---

## Exit Codes

All tools use consistent exit codes for scripting and CI:

| Code | Meaning |
|------|---------|
| 0    | Healthy / all up |
| 1    | Warnings present |
| 2    | Critical issues |

```bash
yburn-health || echo "Something needs attention"
```

---

## Template Library

Five built-in templates for the most common mechanical cron patterns:

| Template | Replaces |
|----------|----------|
| `system-diagnostics` | Disk, CPU, memory, uptime, process checks |
| `cron-health-report` | Cron status audits, failure counts |
| `git-backup-status` | Git add/commit/push, repo state checks |
| `api-endpoint-check` | HTTP health checks, OAuth validation |
| `file-watcher` | File change detection, size monitoring |

Custom templates go in `~/.yburn/templates/`. See `yburn/templates/TEMPLATE_SPEC.md`.

---

## Supported Platforms

| Platform | Status |
|----------|--------|
| macOS    | Full support |
| Linux    | Full support |
| WSL      | Full support (Linux mode) |
| Windows  | Planned for v2 |

**Agent frameworks:**

| Framework | Status |
|-----------|--------|
| OpenClaw  | Native integration (`openclaw cron list`) |
| Claude Code | Health checks via `--claude-code` flag |
| Any JSON  | `yburn audit --file jobs.json` |

---

## Test Suite

```
$ pytest
252 passed in 1.68s
```

---

## What's Next

- More templates (OAuth checker, DB maintenance, log scanner)
- Interactive audit flow with guided prompts
- Auto-detection of cron system (OpenClaw, crontab, systemd, Claude Code)
- Token savings tracking over time
- Community template contributions

---

## Contributing

Contributions welcome, especially:

- New templates for common mechanical cron patterns
- Scanner adapters for other agent frameworks
- Classification signal improvements

```bash
git clone https://github.com/oscarsterling/yburn.git
cd yburn
pip install -e '.[dev]'
pytest
```

Please open an issue before submitting a large PR.

---

## License

MIT. See `LICENSE`.

---

*Built because 53% of our cron jobs were burning tokens on work that doesn't think.*
