Tesla Smart Charge

Schedules Tesla charging on specified dates with target battery % and times, managing charge limits during and after sessions for battery health.

thibautrey@thibautrey

Install

openclaw skills install @thibautrey/tesla-smart-charge

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=your@email.com 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=your@email.com 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=your@email.com 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):

Script checks memory/tesla-charge-schedule.json
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
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="your@email.com"

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="your@email.com" 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="your@email.com" 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:

text

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

Tesla Smart Charge

Install

Tesla Smart Charge Optimizer

Security & Dependencies

Quick Start

1. Set Up Schedule

Cron Setup (Recommended)

Option 1: Daily Check at Midnight (Simple)

Option 2: Daily Check + Session Management (Recommended)

How It Works

Schedule File Format

Environment Setup

Tesla Email

Optional: Customize Charger Power

Commands

Check Schedule for Today

Manage Active Session (Run During or After Charge)

Show All Scheduled Charges

Show Last Charge Plan

Examples

Daily 100% Charge (Mon-Fri)

Smart 80% for Battery Health (Every 3 Days)

Variable Targets

Charge Time Estimation

Workflow Tips

Parameters

References

Related skills