toggle

What this skill does

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