# Connect TutorClaw to Your Calendar

This lesson walks you through connecting TutorClaw to your Google Calendar. Take your time — each step is explained clearly. There is nothing to be nervous about, and nothing irreversible will happen to your calendar.

---

## What this lesson does

When you complete this lesson, TutorClaw will be able to see your upcoming events and answer questions about your schedule — right from your local machine.

You will:
- Authorize a secure, read-only connection to your Google Calendar
- Confirm that TutorClaw can see your events
- Understand what local files are created and how to keep them safe

This whole process takes about five minutes.

---

## What Calendar Awareness means

Calendar Awareness is TutorClaw's ability to look at your upcoming events and help you think through your week. When it is enabled, you can ask questions like *"What do I have tomorrow?"* or *"Am I free on Friday afternoon?"* and TutorClaw will read your schedule and respond.

Think of it like giving a personal assistant access to a printed copy of your calendar — they can read it and tell you what is on it, but they cannot write anything new, erase anything, or make any changes on your behalf.

---

## What TutorClaw can and cannot do

This is **read-only** access. TutorClaw can see your calendar, but it cannot touch it.

**TutorClaw can:**
- Read the names, times, and descriptions of events
- Tell you when you are busy or free
- Summarize your day, week, or specific time slots
- Remind you of upcoming appointments when you ask

**TutorClaw cannot:**
- Create new events or appointments
- Edit or modify any existing event
- Delete any event from your calendar
- Send invitations or add guests
- Reschedule or cancel meetings

If you ever ask TutorClaw to book or change an appointment, it will let you know that it does not have that ability.

---

## How to use Google Calendar with TutorClaw

TutorClaw does not replace your Google Calendar. You will continue to use the regular Google Calendar app on your phone, tablet, or computer to manage your schedule. 

Whenever you want to note down:
* Appointments (like a dentist visit)
* Reminders and errands
* Bill due dates
* Birthdays and family events
* Medical appointments
* Other things you want to remember

Simply add them directly into your Google Calendar app as you normally do. Once you put these items on your calendar, TutorClaw can read them in read-only mode. TutorClaw can answer questions about what is coming up on your schedule, but it will never create, edit, or change any of those items.

### A Simple Example:

1. **In Google Calendar:** You open the Google Calendar app and add a new event:
   * **Title:** Dentist appointment
   * **Time:** Tuesday at 10:00 AM

2. **In TutorClaw:** Later, you ask your assistant:
   > *"What appointments do I have this week?"*

3. **Response:** TutorClaw reads your schedule and includes the Tuesday dentist appointment in its reply!

---

## Before you start

Make sure you have these four things ready:

- [ ] **TutorClaw is installed and running** on your computer
- [ ] **You know which Google account** holds the calendar you want to connect
- [ ] **A web browser is available** on your machine (Chrome, Edge, Firefox — any will work)
- [ ] **You have a stable internet connection** to complete the authorization step

That is all you need. No technical knowledge is required.

---

## A quick note about Google's permission screen

When you connect TutorClaw to your Google Calendar, Google will ask you to approve the connection. This is a standard Google security step — Google wants to make sure you are the one granting access, not someone else.

Because TutorClaw runs privately on your own computer rather than as a public web service, Google may show a screen saying the app is **"not verified."** This is normal and expected. It does not mean anything is wrong. It simply means TutorClaw is your own private local tool rather than a large published product that Google has reviewed.

You will have the option to proceed safely past that screen, which Step 2 explains in detail.

You can also revoke this access at any time by visiting [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and removing TutorClaw from your connected apps. Revoking access does not delete your calendar data.

---

## Step 1: Start the calendar setup

TutorClaw includes a setup process that handles the connection for you.

1. Open the main TutorClaw project folder on your computer.
2. Look for a setup command or script with a name like **`Start Calendar Connection.bat`** or a similar calendar setup option. When in doubt, check any `README` or setup notes included with your installation.
3. Run the setup. A message will appear in the terminal window telling you that a browser window is about to open.
4. Wait a moment — your default web browser will open automatically to a Google sign-in page.

> **Nothing will change on your calendar yet.** This step simply starts the authorization process.

---

## Step 2: Approve read-only Google Calendar access

Your browser will take you through a short Google approval flow. Here is exactly what to expect:

1. **Sign in to Google** if you are not already signed in. Use the account whose calendar you want to connect.

2. **Choose your account** if Google shows multiple accounts. Select the correct one.

3. **Read the "unverified app" warning** — Google may display a caution screen saying something like *"Google hasn't verified this app."*
   - This is expected for private, locally installed tools.
   - Click **Advanced** (it may be a small link near the bottom of the screen).
   - Then click **Go to TutorClaw (unsafe)**. Despite the wording, this is safe — "unsafe" here means Google has not reviewed it as a public commercial product, not that it will harm your computer.

4. **Review the permissions** — Google will show you what TutorClaw is asking to access. Confirm it says something like *"View events on all your calendars"* or *"Read your calendar."* This is the read-only access described in this lesson.

5. Click **Allow** to approve the connection.

> **Important:** If you see a permission request for anything beyond reading or viewing your calendar — such as editing, deleting, or managing — do not approve it. Close the browser and contact support before continuing.

---

## Step 3: Return to TutorClaw

After you click Allow, Google will redirect your browser to a brief confirmation page.

1. Your browser will show a message like: *"Authentication complete. You may close this tab."*
2. Close the browser tab and return to the TutorClaw terminal window on your computer.
3. TutorClaw will automatically detect that authorization succeeded and finish its setup.

**Two local files will be created in your TutorClaw folder:**

| File | What it is |
|---|---|
| `credentials.json` | Identifies your local TutorClaw installation to Google. Think of it as the application's ID card. |
| `token.json` | A private digital key that lets TutorClaw fetch your calendar events. Think of it as a short-lived access pass. |

Both files are stored only on your machine. Neither file contains your Google password. Keep them private — more on this in the Safety section below.

---

## Step 4: Test your calendar connection

Let's make sure everything is working.

1. Open a chat session with TutorClaw.
2. Ask a simple calendar question. For example:
   > *"What do I have on my calendar today?"*

    *(If your assistant has a local persona name, you can address it by name, for example: "Chris, what's on my schedule today?")*

3. TutorClaw should respond with a list of your events for today. If your calendar is empty for today, try asking about tomorrow or this week.

4. If you see your events listed in the response, your setup is complete and working.

---

## Safe questions to ask TutorClaw

Here are examples of things you can comfortably ask once your calendar is connected:

**Daily planning:**
- *"What do I have scheduled for today?"*
- *"What is my first appointment tomorrow?"*
- *"Do I have anything on Friday afternoon?"*

**Availability checks:**
- *"Am I free at 2:00 PM on Thursday?"*
- *"Do I have any conflicts tomorrow morning?"*
- *"Is my afternoon clear this week?"*

**Event details:**
- *"What time is my dentist appointment?"*
- *"What is the description on my Monday meeting?"*
- *"Who organized the team call next week?"*

**Weekly overview:**
- *"Summarize my week."*
- *"What is the busiest day on my calendar this week?"*
- *"Do I have any back-to-back meetings coming up?"*

---

## Troubleshooting

**"Google says the app is not verified"**
This is normal for private local tools. Click **Advanced**, then click **Go to TutorClaw (unsafe)** to continue. Nothing harmful will happen — the warning is simply Google's way of flagging apps that have not gone through its commercial review process.

**"Authentication failed" or "Permission denied"**
Make sure you are signed into the correct Google account in your browser. If you have multiple Google accounts open, sign out of all but the one you want to use, then run the setup again.

**"Token expired" or "Please re-authorize"**
Google access tokens expire after a period of inactivity. If this happens, simply run the calendar setup again. The existing `token.json` will be replaced with a fresh one. Your calendar data is not affected.

**"TutorClaw cannot find any events"**
Check that your events exist on the **primary calendar** of the Google account you authorized. If your events are in a secondary or shared calendar, they may not appear by default. Ask TutorClaw to check your other calendars by name.

**"Browser did not open" or "Setup seems stuck"**
Try opening the setup again. If a browser window does not open automatically, look in the terminal for a URL starting with `http://` and paste it into your browser manually.

**"Port blocked" or "Redirect URI mismatch"**
The authorization process uses a temporary local port on your computer to receive Google's response. If a firewall or security tool is blocking it, try temporarily disabling that tool during setup, then re-enable it afterwards. If you are unsure, ask someone you trust who is familiar with your network settings.

**"I accidentally clicked Deny instead of Allow"**
No problem. Just run the calendar setup script again. You will see the same Google approval screen and can click Allow this time.

---

## Safety reminders

Your calendar credentials and token are private files stored only on your machine. Here is what to keep in mind:

**Do not share these files with anyone:**
- `credentials.json`
- `token.json`
- Any `.env` files in your TutorClaw folder

These files together allow access to your calendar. Treat them the way you would treat a password.

**Do not include them in ZIP packages:**
If you ever share your TutorClaw folder with a friend, a colleague, or a support person, remove `credentials.json` and `token.json` from the folder before compressing or sending it. Your calendar access is personal and should not be bundled into shared packages.

**You can revoke access at any time:**
If you ever want to disconnect TutorClaw from your Google Calendar — for any reason — visit [myaccount.google.com/permissions](https://myaccount.google.com/permissions), find TutorClaw in the list, and click **Remove Access**. You can reconnect later by running the setup again. Revoking access does not delete any calendar data.

**TutorClaw cannot make changes:**
As a reminder, even if TutorClaw has calendar access, it cannot create, edit, delete, reschedule, or cancel events. Your calendar is always under your control.

---

## Success checklist

You are done when you can check every box below:

- [ ] I understand that TutorClaw can only **read** my calendar — it cannot change anything
- [ ] I completed the Google authorization flow in my browser
- [ ] I clicked **Allow** on the Google permissions screen
- [ ] A `token.json` file was created in my TutorClaw folder
- [ ] I tested the connection by asking TutorClaw a calendar question and received a real answer
- [ ] I understand that `credentials.json` and `token.json` are private and should not be shared or zipped with others
- [ ] I know I can revoke access at any time from my Google account settings

Well done. Your assistant can now help you stay on top of your schedule.
