toggle

Context layer for your agent. ToggleX captures the user's work sessions, projects, focus scores, and context switches across the web — giving the agent awareness of what the user has actually been doing. Use this skill PROACTIVELY: generate daily digests, nudge stale projects, detect context-switching, spot repeated workflows and propose automations, predict the user's next action based on learned routines, and answer recall questions from memory. Also use when the user asks about their activity, tasks, sessions, productivity, time, or anything work-related. Keywords: what did I do, what was I working on, today, yesterday, my day, activity, sessions, refresh my data, productivity, time tracking, context, pick up where I left off, what was I looking at, stale, pattern, automate, digest, report, focus, scattered, deep work, predict, next task, routine, anticipate, briefing.

# 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

| Action | Command |
|--------|---------|
| Fetch today | `python3 {baseDir}/scripts/toggle.py` |
| Fetch date range | `python3 {baseDir}/scripts/toggle.py --from-date YYYY-MM-DD --to-date YYYY-MM-DD` |
| Fetch + save to memory | `python3 {baseDir}/scripts/toggle.py --persist {baseDir}/../../memory` |
| Cron run (skip cron check) | `python3 {baseDir}/scripts/toggle.py --persist {baseDir}/../../memory --skip-cron-check` |

---

## 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:

```json
{
  "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:

```json
{
  "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

```json
{
  "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

| Field | Description |
|-------|-------------|
| `type` | `"WORK"`, `"BREAK"`, or `"LEISURE"` |
| `workflowType` | Short label for the session (e.g. "Build Investigation and Scripting") |
| `workflowDescription` | Detailed narrative of what the user did. **May contain raw URLs — do not echo these to the user unless asked.** Summarize in your own words. |
| `primaryDomain` | Main website/app (e.g. `"github.com"`, `"claude.ai"`, `"127.0.0.1"`) |
| `productivityScore` | `"0.00"` to `"100.00"` (string). **90+** = sharp, **70–89** = solid, **below 70** = fragmented |
| `startTime` / `endTime` | ISO 8601 UTC timestamps. `endTime` may equal `startTime` for instantaneous actions, or be null if ongoing. |
| `duration` | Session length in seconds (float) |
| `durationMinutes` | Rounded session length in minutes (int) |
| `projectTask.name` | Human-readable task description |
| `projectTask.goal` | What the user was trying to accomplish |
| `projectTask.prompts` | AI-generated follow-up questions relevant to the task. **Use these** — if the user asks "what should I do next on this project?", these are high-quality suggestions directly tied to their recent work. |
| `projectTask.project.name` | Parent project name — use for grouping and stale-project detection |
| `projectTask.project.summary` | Running project summary — useful for briefings and recall |
| `summary.totalContextSwitches` | API-provided count of context switches for the period. **Use this instead of calculating manually.** |
| `summary.totalDurationMinutes` | Total tracked time in minutes |

### 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:

| Error | Likely cause | What to tell the user |
|-------|-------------|----------------------|
| `HTTP error 401` | Invalid or expired API key | "Your Toggle API key isn't working. Get a new one at https://x.toggle.pro/new/clawbot-integration" |
| `HTTP error 403` | Insufficient permissions | "Your API key doesn't have the right permissions. Check your ToggleX integration settings." |
| `HTTP error 429` | Rate limited | "Toggle's API is rate-limiting requests. I'll try again in a few minutes." Implement exponential backoff: wait 1 min, then 2 min, then 5 min. Max 3 retries. Do not run the script more than once per 5 minutes. |
| `HTTP error 5xx` | ToggleX server issue | "ToggleX servers seem to be having issues. I'll try again shortly." |
| `Request failed` / timeout | Network issue | "Couldn't reach ToggleX. Check your internet connection." |
| `TOGGLE_API_KEY is not set` | Missing env var | "Your Toggle API key isn't configured yet. Set it up at https://x.toggle.pro/new/clawbot-integration and add it to your OpenClaw config." |
| JSON parse error | Malformed response | "Got an unexpected response from ToggleX. Usually tempo