Docs/Developers/AI Format Reference

AI Format Reference

Complete reference for the x_elysium extension fields in .ot files.

This is the same reference file auto-generated by Elysium in your OpenTime folder when BYOAI is enabled. It documents all standard OpenTime v0.2 fields and Elysium-specific extensions. Audience: plugin developers and AI tools reading or writing Elysium schedules.

Overview

.ot files are YAML documents. Each file contains a header and a list of schedule items.

opentime_version: "0.2"
default_timezone: "America/New_York"
generated_by: "Elysium 1.0"
created_at: "2026-01-01T00:00:00Z"
items:
  - type: task
    id: "abc-123"
    title: "Write report"
    status: todo

Document root fields

Field	Required	Description
opentime_version	Yes	Always "0.2"
items	Yes	List of schedule items
default_timezone	No	IANA timezone (e.g. "America/New_York") — used for items without explicit timezone
generated_by	No	App name and version
created_at	No	ISO8601 UTC timestamp

Data types

Type	Format	Example
date	YYYY-MM-DD	"2026-03-15"
datetime	ISO8601 with timezone offset	"2026-03-15T09:00:00-05:00"
time	HH:MM 24-hour	"09:00", "14:30"
progress	number 0.0–1.0	0.5

Item types

Elysium supports 7 item types. Each item requires type and id.

Type	Description	Required fields
goal	Single-step intention/outcome	type, id, title, kind
task	Atomic action	type, id, title, status
habit	Recurring behavior	type, id, title
reminder	Lightweight notification	type, id, title, time
event	Block of time	type, id, title, start, end
appointment	Event with attendees	type, id, title, start, end, attendees
project	Container for other items (Elysium: Odyssey)	type, id, title, kind

x_elysium extensions

Elysium stores additional data under an x_elysium key on each item. External tools should preserve these fields unchanged. You may add or modify them to control Elysium-specific behavior.

x_elysium on goal / project

Field	Type	Description
priority	string	"low" \| "medium" \| "high" \| "urgent"
difficulty	string	"easy" \| "medium" \| "hard"
start_date	date	When to start working on this goal
next_due_day	date	Next calculated due date
target_duration_value	number	Estimated duration amount
target_duration_unit	string	"minutes" \| "hours" \| "days"
target_duration_per	string	Recurrence period for the duration
repeats_enabled	bool	Whether goal repeats
repeats_count	int	How many times per period
repeats_per	string	"day" \| "week" \| "month" \| "year"
repeats_mode	string	Repeat mode
repeats_weekdays	string	Comma-separated weekday abbreviations
repeats_end_type	string	"never" \| "date" \| "occurrences"
repeats_end_date	date	End date for repeating goal
repeats_end_occurrences	int	Max occurrences
series_id	string	UUID linking occurrences of a repeating goal
occurrence_index	int	Which occurrence this is (0-based)
category_name	string	Display name of the category
time_of_day_type	string	"anytime" \| "morning" \| "afternoon" \| "evening" \| "custom"
custom_start_time	time	"HH:MM" — custom time block start
custom_end_time	time	"HH:MM" — custom time block end
is_all_day	bool	Whether shown as all-day
is_auto_scheduled	bool	Whether Elysium auto-scheduled this item
auto_reschedule_enabled	bool	Allow auto-rescheduling on miss
started_at	datetime	When work began
completed_at	datetime	When marked complete
steps	array	Sub-steps (see Steps schema)
notifications	array	Notification schedule (see Notifications schema)
shortcut_name	string	Name of the linked Apple Shortcut to run
shortcut_enabled	bool	Whether the shortcut runs automatically on start
apps	array	Apps to open when this item starts (see Apps schema)

x_elysium on task

Same fields as goal except no steps array. Includes difficulty; priority is a number (1–10) here rather than a string. All scheduling, repeat, notification, shortcut, and apps fields apply.

x_elysium on habit

Field	Type	Description
habit_type	string	"boolean" \| "count" \| "duration" \| "numeric"
target_value	number	Target amount for count/numeric/duration habits
target_unit	string	Unit for target (e.g. "minutes", "reps")
sessions_per_day	int	How many sessions per day
total_completions	int	Lifetime completion count
total_slips	int	Lifetime miss count
increment_enabled	bool	Progressive overload enabled
increment_value	number	Amount to increment per period
visibility_type	string	"always" \| "scheduled"
notifications	array	Notification schedule
shortcut_name	string	Name of the linked Apple Shortcut
shortcut_enabled	bool	Whether the shortcut runs automatically
apps	array	Apps to open when this habit starts

x_elysium on reminder

Field	Type	Description
location	string	Location for location-based reminder
priority	string	"low" \| "medium" \| "high"
is_all_day	bool	All-day reminder
custom_start_time	time	"HH:MM"
custom_end_time	time	"HH:MM"
notifications	array	Notification schedule

x_elysium on event

Field	Type	Description
location_notes	string	Additional location details
transportation_details	string	How to get there
travel_time_before	int	Minutes of travel time before event
travel_time_after	int	Minutes of travel time after event
cancelled	bool	Whether event is cancelled
cancellation_reason	string	Why it was cancelled
event_type	string	Category of event
needs_prep	bool	Whether prep tasks should be created
event_status	string	"scheduled" \| "completed" \| "cancelled"
notifications	array	Notification schedule
shortcut_name	string	Name of the linked Apple Shortcut
shortcut_enabled	bool	Whether the shortcut runs automatically
apps	array	Apps to open when this event starts

x_elysium on appointment

Field	Type	Description
notes_from_provider	string	Notes from the service provider
cancellation_notes	string	Notes about cancellation
appointment_status	string	"scheduled" \| "completed" \| "cancelled"
booking_reference	string	Confirmation/booking number
appointment_type	string	Category of appointment
notifications	array	Notification schedule
shortcut_name	string	Name of the linked Apple Shortcut
shortcut_enabled	bool	Whether the shortcut runs automatically
apps	array	Apps to open when this appointment starts

Steps schema

Available on goal items via x_elysium.steps.

steps:
  - id: "step-uuid"
    title: "Step title"
    completed: false
    order: 0
    priority: "medium"
    due_date: "2026-03-15"       # optional
    estimate_minutes: 30          # optional

Notifications schema

Available on most item types via x_elysium.notifications.

notifications:
  - enabled: true
    timing: "on_time"             # "on_time" | "minutes_before" | "hours_before" | "days_before" | "custom"
    has_alarm: true
    custom_minutes: 15            # only when timing is "minutes_before"

Apps schema

Apps to automatically open (and optionally position) when an item starts. Available via x_elysium.apps.

Field	Type	Required	Description
app_name	string	Yes	Display name (e.g. "Xcode")
app_path	string	Yes	Full .app bundle path (e.g. "/Applications/Xcode.app")
bundle_identifier	string	No	macOS bundle ID (e.g. "com.apple.dt.Xcode")
window_layout	string	No	How to position the window — see layout values below
target_monitor_index	int	No	Monitor index: 0 = primary, 1 = second. Omit for primary
custom_x	number	No	Left edge as fraction of screen width (0.0–1.0); only for custom layout
custom_y	number	No	Top edge as fraction of screen height (0.0–1.0)
custom_width	number	No	Width as fraction of screen width (0.0–1.0)
custom_height	number	No	Height as fraction of screen height (0.0–1.0)

window_layout values:

previous · fullScreen · leftHalf · rightHalf · topHalf · bottomHalf · leftThird · centerThird · rightThird · leftTwoThirds · rightTwoThirds · topThird · middleThird · bottomThird · topTwoThirds · bottomTwoThirds · leftQuarter · rightQuarter · leftThreeQuarters · rightThreeQuarters · topLeftQuarter · topRightQuarter · bottomLeftQuarter · bottomRightQuarter · custom

apps:
  - app_name: "Xcode"
    app_path: "/Applications/Xcode.app"
    bundle_identifier: "com.apple.dt.Xcode"
    window_layout: "leftHalf"
    target_monitor_index: 0
  - app_name: "Simulator"
    app_path: "/Applications/Xcode.app/Contents/Developer/Applications/Simulator.app"
    window_layout: "rightHalf"

Complete YAML example

opentime_version: "0.2"
default_timezone: "America/Chicago"
generated_by: "Elysium 1.0"

items:
  - type: project
    id: "proj-launch-2026"
    title: "Q1 Product Launch"
    kind: project
    progress: 0.3
    target_date: "2026-03-31"
    tags: [work, priority]
    x_elysium:
      priority: high
      start_date: "2026-01-01"

  - type: goal
    id: "goal-mvp"
    title: "Complete MVP"
    kind: goal
    target_date: "2026-02-28"
    progress: 0.5
    project_id: "proj-launch-2026"
    x_elysium:
      priority: high
      time_of_day_type: morning
      custom_start_time: "09:00"
      custom_end_time: "12:00"
      steps:
        - id: "step-1"
          title: "Write API docs"
          completed: false
          order: 0

  - type: task
    id: "task-api-docs"
    title: "Write API documentation"
    status: in_progress
    due: "2026-01-20"
    estimate_minutes: 90
    goal_id: "goal-mvp"
    project_id: "proj-launch-2026"
    x_elysium:
      priority: "8"
      time_of_day_type: morning
      is_auto_scheduled: true

  - type: habit
    id: "habit-review"
    title: "Daily planning review"
    pattern:
      freq: daily
    window:
      start_time: "08:00"
      end_time: "08:30"
    streak:
      current: 5
      longest: 21
    x_elysium:
      habit_type: boolean
      visibility_type: always

  - type: event
    id: "event-standup"
    title: "Team standup"
    start: "2026-01-10T09:00:00-06:00"
    end: "2026-01-10T09:30:00-06:00"
    recurrence: "FREQ=WEEKLY;BYDAY=MO,WE,FR"
    location: "Conference Room A"
    x_elysium:
      event_type: work
      travel_time_before: 5

  - type: appointment
    id: "appt-dentist"
    title: "Dentist checkup"
    start: "2026-01-20T14:00:00-06:00"
    end: "2026-01-20T15:00:00-06:00"
    attendees: ["Dr. Smith"]
    provider: dentist
    location: "123 Medical Plaza"
    x_elysium:
      appointment_type: medical
      booking_reference: "REF-12345"

  - type: reminder
    id: "rem-review"
    title: "Review weekly goals"
    time: "2026-01-10T17:00:00-06:00"
    repeat: "FREQ=WEEKLY;BYDAY=FR"
    x_elysium:
      priority: medium

Rules for AI tools

1.
Always include type and id — These are required on every item.
2.
IDs must be stable — Use UUIDs or descriptive strings. Never reuse an ID for a different item.
3.
Datetimes must include a timezone offset — e.g. -05:00 or Z. Never write a naive datetime.
4.
To complete an item — Set status: done (tasks) or add completed_at under x_elysium. Do not delete the item.
5.
To delete an item — Set a deleted_at field under x_elysium with the current datetime. Elysium will soft-delete it on next import.
6.
Preserve unknown x_* fields — If you see x_elysium or any other x_ key you don't recognize, copy it unchanged.
7.
New items get imported — On the next auto-import cycle. Existing items (matched by id) are updated only if updateExisting mode is active.
8.
Per-item mode — If the folder contains multiple elysium-*.ot files (one per item type), write each item to the correct file. If single-file mode, everything goes in one file.

← Bring Your Own AI

Plugin API →