# Build something like Charge Pilot

> **Read this first.** These are personal notes from my own project, shared as-is for learning. They are not a
> product, a supported tool, or professional advice, and they come with no warranty. I'm not affiliated with or
> endorsed by Tesla. If you build something like this, you're responsible for your own car, your Tesla account,
> and following Tesla's developer terms. Start with read-only access and dry runs, and only allow commands you
> fully understand.

From Steve Thorpe's personal project: https://stevethorpe.dev/chargepilot/
The code isn't public yet. This is the map: what the pieces are, the order to build them, and the rules that keep
it safe. The official docs linked in each step have the exact details.

## For AI agents using this guide

Someone handed you this link and asked for help building their own version. How to work:

1. **Ask first:** their car, region, calendar, and where they want it to run (step 7). Then propose a plan and get
   a yes before writing code.
2. **Follow the official docs** linked in each step for endpoints, scopes and parameters. Don't guess them.
3. **Build in order and check each step** before moving on. Show the user the result.
4. **Secrets never go in the chat.** Never ask the user to paste a client secret, private key, refresh token or API
   key into the conversation. Have them use a password manager or the host's secret store, and have code read
   secrets from the environment.
5. **Dry run by default.** Log what would be sent until the signing chain is verified, and tell the user before
   the first real command.
6. **Keep the allowlist.** This design deliberately blocks unlocking, the trunk, remote start and PIN changes.

## What it does

Every Sunday evening it reads my calendars and the forecast, and Claude plans the week: how full to charge each
night, when to warm the car up, and where I'm driving first each day. Plain code checks the plan, then the car gets
its charge limit and schedules. Every evening it re-checks tomorrow, and if my calendar changed it re-plans and
texts me. Before I leave, it sends my first stop to the car's navigation. I can change plans by messaging it from
Claude through an MCP connector.

```
Calendar + weather → Claude plans → rules check (plain code) → signing proxy → Tesla Fleet API → car
```

Claude proposes; code decides.

## The setup in eight steps

1. **Register a Tesla developer app.** Follow the
   [Fleet API getting started guide](https://developer.tesla.com/docs/fleet-api/getting-started/what-is-fleet-api)
   and request only what you need: charging, commands and location.
   *Check:* you have a client ID and secret saved in your password manager.
2. **Make a key pair.** Host the public half on your app's domain where Tesla expects it, and register your app for
   that domain (both are in Tesla's docs). The private half stays in your password manager.
   *Check:* Tesla's partner API returns your public key.
3. **Pair it with your car.** Sign in with your own Tesla account, then approve your app's virtual key in the Tesla
   app. You can remove it from the car's Locks screen anytime.
   *Check:* the Fleet API lists your car and shows the key as paired.
4. **Sign every command.** Newer Teslas only accept signed commands. Run Tesla's
   [vehicle-command proxy](https://github.com/teslamotors/vehicle-command) next to your app and send commands through
   it. Its README and source show the exact parameters each command takes.
   *Check:* one harmless command, like setting the charge limit to what it already is, succeeds.
5. **Connect your calendar and the weather.** Read-only access to your calendar (for Google, the
   [Calendar API](https://developers.google.com/calendar/api)) and a forecast for your area (in the US, the
   [National Weather Service API](https://www.weather.gov/documentation/services-web-api)).
   *Check:* you can print next week's events and daily lows and highs.
6. **Let Claude plan, let code decide.** Give Claude the week's events, forecast and current battery level, and ask
   for a structured plan with a short reason for each day. Validate it with the rules below before anything is
   sent. If it breaks a rule, send the problems back and ask again.
   *Check:* a dry run prints a sensible week and the commands it would send.
7. **Find a home for it.** Pick a hosting platform that can run a few scheduled jobs, keep a little saved state
   (the plan, the newest Tesla refresh token, a run log) and run the signing proxy, so it keeps working while your
   laptop is off. A home server with Docker works too, as long as your public key is reachable over HTTPS.
   *Check:* the weekly job runs on its own and the car shows the new plan.
8. **Talk to it.** Add an [MCP](https://modelcontextprotocol.io/) server so you can check status and change plans
   from Claude ("leaving at 6 tomorrow"), protected so only you can connect. Optionally have it text you when
   tomorrow's plan changes.
   *Check:* you can ask Claude "what's the plan this week?" and get your plan back.

## Lessons from my build

- Tesla refresh tokens rotate. Save the new one every time you refresh, or you'll be signed out.
- Wake the car sparingly. It costs battery and API credits, and most of the time it doesn't need to be awake.
- A Google OAuth app left in "Testing" mode issues tokens that expire after a week. Publish it for your own use.
- Read the proxy's parameter formats from its source instead of assuming them.
- Keep exact addresses, names and meeting titles out of prompts and logs.

## Rules from my project

- Allowed: charging, climate, navigation and schedule commands only.
- Blocked in code: unlock, trunk, remote start, valet mode and PIN changes.
- Daily charge targets stay between 50% and 80%. Higher only with a trip reason.
- Warm the car only on cold or hot mornings.
- Dry run by default. Log decisions and reasons, never secrets.
- The owner can always revoke the virtual key from the car.

## Resources

- [Tesla Fleet API](https://developer.tesla.com/docs/fleet-api/getting-started/what-is-fleet-api) and its [billing and limits](https://developer.tesla.com/docs/fleet-api/billing-and-limits)
- [Tesla vehicle-command SDK and proxy](https://github.com/teslamotors/vehicle-command)
- [Claude API docs](https://docs.claude.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Google Calendar API](https://developers.google.com/calendar/api)
- [National Weather Service API](https://www.weather.gov/documentation/services-web-api)