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:

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:

{
  "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)

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):

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):

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):

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

{
  "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

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:

--charger-power 3.7      # 16A @ 230V
--charger-power 7.4      # 32A @ 230V (dual-phase)

Commands

Check Schedule for Today

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)

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

python3 scripts/tesla-smart-charge.py --show-schedule

Show Last Charge Plan

python3 scripts/tesla-smart-charge.py --show-plan

Examples

Daily 100% Charge (Mon-Fri)

{
  "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)

{
  "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

{
  "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:

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