Skill: thibautrey/tesla-smart-charge (version 1.1.1)

--- name: tesla-smart-charge description: Smart Tesla charging scheduler with charge limit management. Runs daily to check a schedule file and charge only on configured dates. Automatically manages charge limits during sessions (default 100%) and after sessions (default 80%). Use when you need to: (1) Charge your Tesla on specific planned dates, (2) Manage charge limits for battery health, (3) Calculate optimal charging start times, (4) Set up recurring daily checking with flexible charge scheduling. --- # Tesla Smart Charge Optimizer Schedule Tesla charging to reach target battery % by a specific time. Runs daily via cron to check a schedule file and only charges on configured dates. ## Security & Dependencies **Required:** - Environment variable: `TESLA_EMAIL` (your Tesla account email) - Skill dependency: `tesla` skill must be installed and properly configured with Tesla API credentials **Security improvements (v1.1.0+):** - ✅ No shell injection risk: Uses argument lists instead of shell=True - ✅ Email validation: TESLA_EMAIL is validated before use - ✅ Input validation: Charge limits are validated (0-100% range) - ✅ Secure env passing: Credentials passed via environment variables, not string interpolation - ✅ Explicit dependencies: Metadata declares required env vars and skill dependencies ## Quick Start ### 1. Set Up Schedule Copy the example schedule file: ```bash cp skills/tesla-smart-charge/references/tesla-charge-schedule-example.json \ memory/tesla-charge-schedule.json ``` Edit `memory/tesla-charge-schedule.json` with your planned charge dates: ```json { "charges": [ { "date": "2026-02-01", "target_battery": 100, "target_time": "08:00" }, { "date": "2026-02-03", "target_battery": 80, "target_time": "07:00" } ] } ``` ## Cron Setup (Recommended) ### Option 1: Daily Check at Midnight (Simple) ```bash clawdbot cron add \ --name "Tesla daily charge check" \ --schedule "0 0 * * *" \ --task "TESLA_EMAIL=[REDACTED_SECRET] python3 /path/to/skills/tesla-smart-charge/scripts/tesla-smart-charge.py --check-schedule" ``` ### Option 2: Daily Check + Session Management (Recommended) For better charge limit management, run both: **At midnight (initialize daily charge):** ```bash clawdbot cron add \ --name "Tesla daily charge check" \ --schedule "0 0 * * *" \ --task "TESLA_EMAIL=[REDACTED_SECRET] python3 /path/to/skills/tesla-smart-charge/scripts/tesla-smart-charge.py --check-schedule" ``` **Every 30 minutes during active hours (manage session limits):** ```bash clawdbot cron add \ --name "Tesla session management" \ --schedule "*/30 8-23 * * *" \ --task "TESLA_EMAIL=[REDACTED_SECRET] python3 /path/to/skills/tesla-smart-charge/scripts/tesla-smart-charge.py --manage-session" ``` The second job ensures charge limits are properly updated throughout the day: - ✅ During session: Maintains 100% (or user-specified) limit - ✅ After session: Applies 80% (or user-specified) limit for battery health ## How It Works **Each day at midnight (or whenever cron runs):** 1. Script checks `memory/tesla-charge-schedule.json` 2. If today's date is in the charges array → executes charge plan - Fetches current battery level - Calculates optimal start time - **Sets charge limit to session limit (default 100%)** - Displays charge details - Shows **next scheduled charge date** 3. If today is NOT scheduled → applies post-charge limit - **Sets charge limit to default 80%** (or user-specified) - Still displays **next scheduled charge date** **Session Management:** - **During charge session:** Charge limit = `charge_limit_percent` (default 100%) - **After charge session expires:** Charge limit = `post_charge_limit_percent` (default 80%) **Result:** One cron job that handles both charging and limit management — no need to create new jobs for each date! ## Schedule File Format ```json { "charges": [ { "date": "2026-02-01", "target_battery": 100, "target_time": "08:00", "charge_limit_percent": 100, "post_charge_limit_percent": 80 }, { "date": "2026-02-03", "target_battery": 80, "target_time": "07:00", "charge_limit_percent": 100, "post_charge_limit_percent": 80 } ] } ``` **Fields:** - `date`: YYYY-MM-DD format (when to charge) - `target_battery`: Target battery % (default: 100) - `target_time`: HH:MM when charging should complete (default: 08:00) - `charge_limit_percent`: Charge limit **during session** (default: 100%, optional) - `post_charge_limit_percent`: Charge limit **after session ends** (default: 80%, optional) ## Environment Setup ### Tesla Email ```bash export TESLA_EMAIL="[REDACTED_SECRET]" ``` ### Optional: Customize Charger Power Default: 2.99 kW (home charger, ~13A @ 230V) Adjust in cron task or when calling manually: ```bash --charger-power 3.7 # 16A @ 230V --charger-power 7.4 # 32A @ 230V (dual-phase) ``` ## Commands ### Check Schedule for Today ```bash TESLA_EMAIL="[REDACTED_SECRET]" python3 scripts/tesla-smart-charge.py --check-schedule ``` Output: - ✅ If scheduled: Shows charge plan + charge limits + next date - ❌ If not scheduled: Shows next scheduled date + applies default 80% limit ### Manage Active Session (Run During or After Charge) ```bash TESLA_EMAIL="[REDACTED_SECRET]" python3 scripts/tesla-smart-charge.py --manage-session ``` This command: - Checks if today's charge session is active - **During session:** Sets charge limit to session limit (default 100%) - **After session:** Sets charge limit to post-charge limit (default 80%) - **No session:** Applies default 80% limit **Tip:** Run this hourly or every 30 minutes during active charging days for real-time limit management. ### Show All Scheduled Charges ```bash python3 scripts/tesla-smart-charge.py --show-schedule ``` ### Show Last Charge Plan ```bash python3 scripts/tesla-smart-charge.py --show-plan ``` ## Examples ### Daily 100% Charge (Mon-Fri) ```json { "charges": [ {"date": "2026-02-02", "target_battery": 100, "target_time": "08:00"}, {"date": "2026-02-03", "target_battery": 100, "target_time": "08:00"}, {"date": "2026-02-04", "target_battery": 100, "target_time": "08:00"}, {"date": "2026-02-05", "target_battery": 100, "target_time": "08:00"}, {"date": "2026-02-06", "target_battery": 100, "target_time": "08:00"} ] } ``` ### Smart 80% for Battery Health (Every 3 Days) ```json { "charges": [ {"date": "2026-02-01", "target_battery": 80, "target_time": "07:00"}, {"date": "2026-02-04", "target_battery": 80, "target_time": "07:00"}, {"date": "2026-02-07", "target_battery": 80, "target_time": "07:00"} ] } ``` ### Variable Targets ```json { "charges": [ {"date": "2026-02-01", "target_battery": 100, "target_time": "08:00"}, {"date": "2026-02-02", "target_battery": 80, "target_time": "07:00"}, {"date": "2026-02-03", "target_battery": 60, "target_time": "06:00"} ] } ``` ## Charge Time Estimation Charge time is calculated as: ``` energy_needed_kwh = (battery_capacity × (target - current) / 100) / charge_efficiency charge_time_hours = energy_needed_kwh / charger_power_kw start_time = target_time - charge_time_hours - margin_minutes ``` Where: - `battery_capacity`: Vehicle battery size (kWh, default: 75) - `charger_power_kw`: Your charger's power (kW, default: 2.99) - `charge_efficiency`: ~0.92 (typical AC charging) - `margin_minutes`: Buffer before target (default: 5 min) **Example:** 75 kWh battery at 50%, charging to 100% by 08:00 with 2.99 kW: - Energy needed: (75 × 50% / 100) / 0.92 = 40.8 kWh - Charge time: 40.8 / 2.99 ≈ 13.6 hours - Start time: 08:00 - 13.6h - 5min ≈ 18:25 previous day ## Workflow Tips **Add new charges:** Edit `memory/tesla-charge-schedule.json` — cron picks up changes on next run **Plan ahead:** Add weeks of charges in advance, script handles date logic **One cron job:** No need to create separate jobs — one daily check does it all **See what's next:** Each run displays the next scheduled charge date ## Parameters When calling manually with `--target-time`: ```bash python3 scripts/tesla-smart-charge.py \ --target-time "HH:MM" \ --target-battery 100 \ --charger-power 2.99 \ --battery-capacity 75 \ --margin-minutes 5 ``` For schedule-based operation, use `--check-schedule` (reads from JSON file). ## References - **CRON_SETUP.md** - Full cron integration guide - **API_REFERENCE.md** - Advanced parameters and formulas - **tesla-charge-schedule-example.json** - Schedule file template


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