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:

CODEBLOCK0

Edit memory/tesla-charge-schedule.json with your planned charge dates:

CODEBLOCK1

Cron Setup (Recommended)

Option 1: Daily Check at Midnight (Simple)

CODEBLOCK2

Option 2: Daily Check + Session Management (Recommended)

For better charge limit management, run both:

At midnight (initialize daily charge):
CODEBLOCK3

Every 30 minutes during active hours (manage session limits):
CODEBLOCK4

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. 1. Script checks INLINECODE3
2. If today's date is in the charges array → executes charge plan

1. 3. If today is NOT scheduled → applies post-charge limit

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

CODEBLOCK5

Fields:

• - date: YYYY-MM-DD format (when to charge)
• INLINECODE7: Target battery % (default: 100)
• INLINECODE8: HH:MM when charging should complete (default: 08:00)
• INLINECODE9: Charge limit during session (default: 100%, optional)
• INLINECODE10: Charge limit after session ends (default: 80%, optional)

Environment Setup

Tesla Email

CODEBLOCK6

Optional: Customize Charger Power

Default: 2.99 kW (home charger, ~13A @ 230V)

Adjust in cron task or when calling manually:

CODEBLOCK7

Commands

Check Schedule for Today

CODEBLOCK8

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)

CODEBLOCK9

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

CODEBLOCK10

Show Last Charge Plan

CODEBLOCK11

Examples

Daily 100% Charge (Mon-Fri)

CODEBLOCK12

Smart 80% for Battery Health (Every 3 Days)

CODEBLOCK13

Variable Targets

CODEBLOCK14

Charge Time Estimation

Charge time is calculated as:

CODEBLOCK15

Where:

• - battery_capacity: Vehicle battery size (kWh, default: 75)
• INLINECODE12: Your charger's power (kW, default: 2.99)
• INLINECODE13: ~0.92 (typical AC charging)
• INLINECODE14: 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:

CODEBLOCK16

For schedule-based operation, use --check-schedule (reads from JSON file).

References

• - CRONSETUP.md - Full cron integration guide
• APIREFERENCE.md - Advanced parameters and formulas
• tesla-charge-schedule-example.json - Schedule file template