Toggle

Toggle (ToggleX) — The Context Layer

ToggleX gives you awareness of the user's real work activity across the web — which projects, how long, how focused, and what they left unfinished. Unlike skills that only know what the user tells you, Toggle knows what they did.

The script fetches raw JSON from the ToggleX API. You are responsible for all intelligence on top of that data: summarization, pattern detection, nudges, and automations.

{baseDir} throughout this document refers to the root directory of this skill's installation (the folder containing this SKILL.md file). This is standard OpenClaw skill convention.

Quick reference

Endpoint

https://ai-x.toggle.pro/public-openclaw/workflows

Operated by ToggleX (https://x.toggle.pro). Your TOGGLE_API_KEY is sent as an x-openclaw-api-key header. No other data is transmitted.

Getting your API key

Get your TOGGLE_API_KEY from:

https://x.toggle.pro/new/clawbot-integration

Never paste the key into chat. Set it in OpenClaw config:

{
  "skills": {
    "entries": {
      "toggle": {
        "apiKey": "your_key_here"
      }
    }
  }
}

Or export in shell: export TOGGLE_API_KEY=your_key_here

Interpreting the output

The script returns raw JSON. The top-level response looks like:

{
  "userId": "...",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "totalWorkflows": 44,
  "totalDays": 1,
  "workflowsByDate": {
    "YYYY-MM-DD": [ ...workflow entries... ]
  },
  "summary": {
    "totalContextSwitches": 0,
    "totalDurationMinutes": 797
  }
}

Sample workflow entry

{
  "workflowId": "3cd901ef-b708-4869-8ce0-52364ce494e6",
  "date": "2026-02-19",
  "workflowType": "AI Image Generation Debugging, Toggle/OpenClaw Skill Configuration",
  "workflowDescription": "The user began by browsing the OpenClaw GitHub repository...",
  "primaryDomain": "github.com",
  "secondaryDomains": "[\"http://127.0.0.1:18789/agents\",\"https://github.com/openclaw/openclaw\"]",
  "productivityScore": "92.00",
  "productivityNotes": "Reviewing the ClawHub documentation ensured correct skill file structure...",
  "type": "WORK",
  "startTime": "2026-02-19T10:49:12.253Z",
  "endTime": "2026-02-19T11:34:27.809Z",
  "duration": 1746.629,
  "durationMinutes": 29,
  "isBreakPeriod": false,
  "isLeisure": false,
  "isWork": true,
  "sessionCount": 10,
  "activeSessionCount": 10,
  "projectTask": {
    "id": "05f01090-...",
    "name": "OpenClaw Environment: Gateway Configuration & Image Generation Skill Integration",
    "goal": "Configure and validate the local OpenClaw environment...",
    "isDone": false,
    "context": "Local OpenClaw instance; GitHub repositories...",
    "prompts": [
      "What verification steps should I follow to confirm the config changes took effect?",
      "How can I test the skill invocation through the OpenClaw chat interface?"
    ],
    "project": {
      "id": "ab576749-...",
      "name": "Toggle Pro AI Chat Feature Development",
      "description": "End-to-end development of AI Chat functionality...",
      "isActive": true,
      "summary": "The project currently reports 0 of 0 tasks completed..."
    }
  }
}

Data type gotchas

• productivityScore is a string (e.g. "92.00"), not a number. Parse to float before comparing against thresholds.
• secondaryDomains is a stringified JSON array, not an actual array. Parse it with JSON.parse() if you need individual URLs.
• duration is in seconds (float). durationMinutes is a rounded integer approximation.
• projectTask can be null — some WORK entries have no project context. Always check before accessing nested fields.
• Zero-duration entries exist — some WORK entries have duration: 0 and durationMinutes: 0. These are brief interactions (e.g. a single page view). Include them in sequence analysis but don't count them as substantial sessions.
• startTime and endTime are UTC (ISO 8601). Convert to the user's local timezone before grouping by "today" or "yesterday" or displaying times. If the user's timezone is unknown, ask once and store in state.yaml under timezone.

Key fields

Interpretation rules

• Focus on type: "WORK" entries; skip BREAK unless asked; mention LEISURE briefly if present
• Always sort entries by startTime — the API does not return entries in chronological order
• If totalWorkflows is 0, tell the user Toggle wasn't running or captured nothing for that period
• When summarizing, use workflowType as the headline and workflowDescription for detail — but paraphrase the description, don't dump it raw (it contains URLs, OAuth tokens, and internal paths)

Error handling

The script exits with a non-zero code and prints to stderr on failure. Handle these cases:

On first run: If the fetch fails, do NOT proceed with the setup pitch. Diagnose the error first.

On cron runs: If a fetch fails, log the error in {baseDir}/state.yaml under last_error with a timestamp. On the next successful user interaction, mention it briefly: "Heads up — the last background sync failed at [time]. It's working again now."

Persist to memory

python3 {baseDir}/scripts/toggle.py --persist {baseDir}/../../memory

Writes a <!-- toggle-data-start --> / <!-- toggle-data-end --> section inside <date>.md files. One file per day. Existing content outside that section is preserved.

Always use --persist when running via cron or when the user asks to save/refresh data.

Cron setup

The script checks cron status on every run. It reads:

1. {baseDir}/state.yaml — if cron_disabled: true, skips the check.
2. ~/.openclaw/cron/jobs.json — looks for any job with "toggle" in its name.

Standard cron commands

These exact commands are used for all cron setup. Referenced throughout this document — define once here.

Hourly sync:

openclaw cron create \
  --name "Toggle hourly sync" \
  --schedule "0 * * * *" \
  --message "Run: python3 {baseDir}/scripts/toggle.py --persist {baseDir}/../../memory --skip-cron-check"

Daily digest (default 6 PM):

openclaw cron create \
  --name "Toggle daily digest" \
  --schedule "0 18 * * *" \
  --message "Fetch today's Toggle data and generate my end-of-day digest. Run: python3 {baseDir}/scripts/toggle.py --persist {baseDir}/../../memory --skip-cron-check"

Adjust the digest schedule if the user requests a different digest_time.

If user declines cron

Write to {baseDir}/state.yaml:

cron_disabled: true

State file

{baseDir}/state.yaml stores preferences and tracking state. You can read and write it.

User preferences

Tracking state (managed by you, the agent)

PROACTIVE BEHAVIORS

These are the core intelligence features. Do not wait for the user to ask. When data is available — through a cron run, a manual fetch, or persisted memory files — analyze it and act.

1. Daily Digest

Trigger: Cron job at the user's digest_time (default 6:00 PM), OR the first interaction after end of workday if no cron is set.

What to do:

1. Fetch today's data with --persist and --skip-cron-check
2. Produce a short default digest — 3 to 4 lines max:
   • Total work time + session count
   • Top focus area (project with most time)
   • Biggest open item (most-invested project that still has recent, unfinished activity)
   • One notable stat (focus score trend vs yesterday, longest session, or summary.totalContextSwitches)

Default format — keep it tight:

Your day: 5.2h across 4 sessions. Deepest focus on auth migration (2.1h, 94 focus). Stripe webhooks still open — you were 80% through. Context switches down to 3 from 6 yesterday.

If the user asks for more detail, expand to: top 3 focus areas by time, all open items, full focus stats (average score, switch count, longest session), and a tomorrow suggestion.

Comparing to yesterday: If yesterday's data exists in {baseDir}/../../memory/, compare total time, focus score, and context-switch count. Note trends. Skip comparison if no prior data exists.

2. Stale Project Nudges

Trigger: Every time you fetch or read Toggle data, scan for stale projects.

A project is stale when both are true:

• It has more than 2 hours of total accumulated time across all days (a real project, not a one-off visit)
• It has no activity in the last nudge_stale_hours (default: 48 hours)

That's it. Two criteria. Don't try to infer whether a project is "completed" — if it is, the user will dismiss the nudge and you'll record that.

What to do:

1. After any data fetch, compare current projects against persisted memory from previous days
2. Read {baseDir}/../../memory/*.md files for the past 7 days
3. Surface stale projects:

You haven't touched "Landing Page Deploy" in 3 days. Last session: 1.5h on responsive layout. Want me to pull up where you left off?

Rules:

• Maximum 2 stale nudges per interaction
• Check last_nudged in state.yaml — skip if same project nudged within 24h
• Check dismissed_projects — never nudge projects on this list
• If the user says "I dropped that" / "not working on it" / "done with that", add to dismissed_projects

3. Context-Switch Alerts

Trigger: When analyzing current or recent data (last 2 hours), detect scattered behavior.

All three must be true:

1. 3+ different project.name values within a 30-minute window (use startTime to define the window)
2. Average productivityScore across those sessions is below focus_alert_threshold (default: 30)
3. This scattered pattern spans at least focus_alert_window_min minutes (default: 20)

What to do:

You've switched between 5 different things in the last 25 minutes (focus score: 22). Want me to help you lock in on [project with most time today]?

Rules:

• Check last_focus_alert — only alert once per 3-hour window
• Check focus_alert_paused_until — if today ≤ that date, skip entirely
• If user dismisses ("I'm fine" / "intentionally browsing"), set focus_alert_paused_until to tomorrow
• Frame as an offer, never a judgment

4. Pattern Detection & Automation Proposals (Agentify)

Trigger: When 7+ days of persisted data exist in {baseDir}/../../memory/. Run after each daily digest, or when the user asks about patterns or automations.

How to detect patterns:

1. Read memory files for the past pattern_detection_days days (default: 7)
2. For each day, sort sessions by startTime to get the chronological sequence
3. Build sequences of (workflowType, project.name) tuples in time order
4. Identify subsequences that appear on pattern_min_occurrences+ different days (default: 3):
   • Same projects visited in the same order (e.g. GitHub → Notion → Slack)
   • Same workflowType at approximately the same time of day (±1 hour window on startTime)

Important: Do not assume the API returns entries in chronological order. Always sort by startTime before building sequences.

What to propose:

I noticed you check GitHub PR comments, then update Notion, then post in Slack — 4 times this week, ~12 min each. Want me to automate that pipeline?

Rules:

• Check what other skills the user has installed. Only propose full automations if the required skills exist
• If partial: "I see you do X → Y → Z each morning. Can't automate all of it yet, but I can pre-fetch the data so it's ready."
• Check proposed_patterns in state.yaml — don't re-propose the same pattern within 14 days
• If approved, help create the appropriate cron job or workflow