Time Tracking Calendar Sync

Environment Variables

Personal calendar IDs should be set via environment variables to avoid committing sensitive data:

# Add to .env file in project root
TT_SOURCE_CALENDAR_ID="[email protected]"
TT_BOOKING_CALENDAR_ID="[email protected]"

Configuration File with Env References

The configuration file uses {env.VARIABLE_NAME} syntax to reference environment variables:

{
  "time_tracking": {
    "sync": {
      "calendar": {
        "source_calendar_id": "{env.TT_SOURCE_CALENDAR_ID}",
        "booking_calendar_id": "{env.TT_BOOKING_CALENDAR_ID}",
        "ticket_pattern": "([A-Z]+-\\d+)",
        "account_pattern": "(TD_[A-Z0-9_]+)",
        "jira_base_url": "https://company.atlassian.net/browse",
        "filter": {
          "exclude_title_patterns": ["^\\[PRIVAT\\]"],
          "require_attendees": false,
          "require_accepted": true,
          "exclude_all_day": true
        }
      }
    }
  }
}

Event Filter Configuration

The filter section controls which calendar events are included in booking proposals:

Example: To exclude private appointments and focus time:

"exclude_title_patterns": ["^\\[PRIVAT\\]", "^\\[PERSONAL\\]", "Fokuszeit"]

For detailed filter logic, see time-tracking-booking skill.

Env Reference Syntax

Format: {env.VARIABLE_NAME}

Resolution by Agents:

1. Agent reads config value
2. Detects {env.*} pattern
3. Extracts variable name (e.g., TT_SOURCE_CALENDAR_ID)
4. Resolves value with fallback:
   • First: Check system environment variable (echo $VARIABLE_NAME)
   • Fallback: If empty, read from .env file in project root
5. Replaces pattern with resolved value

Reading from .env file:

# Check system env first
value=$(echo $TT_SOURCE_CALENDAR_ID)

# Fallback to .env file if empty
if [ -z "$value" ] && [ -f .env ]; then
  value=$(grep "^TT_SOURCE_CALENDAR_ID=" .env | cut -d'=' -f2)
fi

Why this order?

• System environment takes precedence (allows CI/CD overrides)
• .env file provides developer-friendly local configuration
• .env should be in .gitignore to avoid committing sensitive data

Behavior when variable not set:

• source_calendar_id: Warning, continue without calendar integration
• booking_calendar_id: Error, sync cannot proceed

Configuration Reference

Extended CSV Schema

The booking-proposal CSV includes additional columns for sync tracking:

date_from,date_to,issue_key,account_key,from,to,duration_hours,raw_hours,tokens,description,source,source_event_id,booking_event_id

Sync Workflow

1. Load Data

1. Read booking-proposal-{date}.csv
2. Read existing events from booking_calendar_id for the date
3. Build mapping: booking_event_id → existing event

2. Process Entries

For each entry in the booking proposal:

IF source = "calendar":
  → SKIP (already exists in source calendar)

IF source = "csv":
  IF booking_event_id is empty:
    → CREATE new event in booking calendar
    → Save returned event_id to CSV
    
  IF booking_event_id exists:
    → Fetch existing event
    → Compare: title, start, end, description
    → IF changed: UPDATE event
    → IF unchanged: SKIP

3. Cleanup Orphaned Events

Events that exist in the booking calendar but are not in the current proposal:

1. Find events in booking calendar for the date
2. Compare with booking_event_ids in CSV
3. Orphaned = events not referenced in CSV
4. ASK USER: "Delete X orphaned events? [list events]"
5. IF confirmed: DELETE orphaned events

4. Update CSV

Write back the CSV with updated booking_event_id values.

Same vs. Different Calendar Sync

The sync behavior depends on whether source and booking calendars are identical:

Typical configuration:

• source_calendar_id: Personal calendar (read meetings)
• booking_calendar_id: Team calendar or separate booking calendar

When calendars are different, all entries (csv + calendar) are synced to the booking calendar, providing a complete overview of booked time in one place.

Logic in agent:

same_calendar = (source_calendar_id == booking_calendar_id)

IF source = "calendar":
  IF same_calendar:
    → SKIP
  ELSE:
    → CREATE/UPDATE in booking_calendar_id

Event Format

Title

[{ISSUE_KEY}] {Description}

Examples:

• [SOSO-286] Time-Tracking Booking-Proposal implementiert
• [PMO-31] PMO Jour Fixe Stakeholder

For entries without ticket:

• [-] Team-Meetings und Koordination

Description

{Description}

Issue: {ISSUE_KEY}
Account: {ACCOUNT_KEY}
Raw Hours: {RAW_HOURS}h
Tokens: {TOKENS}
Link: {JIRA_BASE_URL}/{ISSUE_KEY}

Example:

Time-Tracking Booking-Proposal implementiert

Issue: SOSO-286
Account: TD_KS_1100_KI_Arbeitsweise
Raw Hours: 0.28h
Tokens: 44,878
Link: https://techdivision.atlassian.net/browse/SOSO-286

For entries without ticket, omit the Issue and Link lines.

Event Attributes

Change Detection

Changes are detected by comparing the current CSV entry with the existing calendar event:

If any field differs → UPDATE the event.

Error Handling

• API Error: Abort immediately and report error
• Missing Config: Report "Please configure sync.calendar in opencode-project.json"
• Missing CSV: Report "Please run /time-tracking.booking-proposal first"

Example Sync Output

## Calendar Sync: 2026-01-29

| Action | Ticket | Time | Description |
|--------|--------|------|-------------|
| CREATE | SOSO-286 | 08:15-08:35 | Time-Tracking impl |
| CREATE | SOSO-3 | 08:35-08:40 | JF Philipp/Tim |
| SKIP | - | 09:30-10:00 | JF Philipp & Tim (source=calendar) |
| UPDATE | PMO-31 | 14:00-14:25 | PMO Jour Fixe (time changed) |

**Summary:**
- Created: 2 events
- Updated: 1 event
- Skipped: 1 entry (source=calendar)
- Deleted: 0 events

**CSV updated:** .opencode/time_tracking/bookings/booking-proposal-2026-01-29.csv

Integration with Booking-Proposal

The /time-tracking.booking-proposal command integrates calendar events:

Calendar Event Filtering

When source_calendar_id is configured:

1. Fetch events for the target date
2. Filter criteria:
   • User's response status = accepted
   • NOT all-day events (must have dateTime, not just date)
3. For each event:
   • Extract issue_key using ticket_pattern from description
   • Extract account_key using account_pattern from description
   • Use global_default.account_key as fallback
   • Set source = "calendar"
   • Set source_event_id = event.id

Merge Logic

1. Calendar events are "fixed" (exact times preserved)
2. CSV worklogs fill gaps sequentially
3. Overlap allowed: CSV entries can run parallel to calendar events
4. Lunch break only applies to CSV worklogs, not calendar events

Event-ID Preservation

When regenerating a booking proposal:

1. Check if booking-proposal-{date}.csv exists
2. Load existing booking_event_id values
3. Match entries by (from, to, issue_key)
4. Preserve booking_event_id for matched entries

This ensures that /sync-calendar can UPDATE existing events instead of creating duplicates.

Google Workspace MCP Tools

The sync uses these MCP tools:

Create Event Parameters

{
  calendar_id: config.booking_calendar_id,
  summary: "[SOSO-286] Description",
  start_time: "2026-01-29T08:15:00+01:00",
  end_time: "2026-01-29T08:35:00+01:00",
  description: "...",
  transparency: "transparent"  // Shows as "Free"
}

Limitations

The Google Workspace MCP tool does not support:

• visibility (private/confidential) - events are default visibility
• colorId - events use default calendar color

References

• time-tracking-csv - CSV format and field definitions
• time-tracking-booking - Booking proposal generation
• /time-tracking.booking-proposal - Generate booking CSV
• /time-tracking.sync-calendar - Sync to Google Calendar
• @calendar-sync - Agent for calendar synchronization