Skip to content
/ skills Public

Add intent-guardian skill: real-time task stack with forgetting detection #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
HuilingP wants to merge 1 commit into from
Closed

Add intent-guardian skill: real-time task stack with forgetting detection #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions skills/huiling-one2x/intent-guardian/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Intent Guardian

**Never lose your train of thought again.**

Intent Guardian is an OpenClaw skill that watches your desktop activity, maintains a real-time task stack, and reminds you when you've forgotten what you were doing after an interruption.

## Why This Exists

Knowledge workers are interrupted every 3 minutes on average. After each interruption, there's a significant chance you simply forget what you were doing before. This skill acts as your always-on focus companion that remembers your intentions when you can't.

## Quick Start

```bash
# Install
npx playbooks add skill openclaw/skills --skill intent-guardian

# Start activity sensing (macOS)
bash ~/.openclaw/skills/intent-guardian/scripts/sense_activity.sh &

# Add heartbeat integration (see references/heartbeat-integration.md)
```

## How It Works

1. **Sense** - Polls active window title/app every few seconds (via native OS APIs or ActivityWatch)
2. **Understand** - LLM segments activity stream into logical tasks and infers intent
3. **Track** - Maintains a task stack: what you're doing, what got interrupted, what's completed
4. **Detect** - Identifies when a suspended task was likely *forgotten* (not deliberately abandoned)
5. **Remind** - Sends a gentle, context-rich nudge to get you back on track
6. **Learn** - Builds a personal focus profile from your patterns over time

## Features

- Zero-dependency macOS setup (uses `osascript`)
- Optional ActivityWatch integration for richer data
- Optional screenshot analysis with vision models
- Privacy-first: all data stays local
- Integrates with existing skills (personal-analytics, daily-review, screen-monitor)
- Personalized over time: learns which apps cause you to forget most

## Files

```
intent-guardian/
SKILL.md # Main skill definition
_meta.json # Skill metadata
README.md # This file
scripts/
sense_activity.sh # macOS window polling
sense_activitywatch.sh # ActivityWatch API integration
sense_screen.sh # Optional screenshot capture
get_task_stack.sh # Read current task stack
get_focus_profile.sh # Read focus profile
get_recent_activity.sh # Get recent activity log entries
log_reminder_response.sh # Log user feedback on reminders
daily_focus_report.sh # Generate daily focus summary
cleanup.sh # Clean old data
references/
heartbeat-integration.md # How to set up heartbeat + cron
forgetting-detection.md # Algorithm details for detection
```

## License

MIT
314 changes: 314 additions & 0 deletions skills/huiling-one2x/intent-guardian/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,314 @@
---
name: intent-guardian
version: 1.0.0
description: Watches your desktop activity, maintains a real-time task stack, detects when you forget what you were doing after interruptions, and gently reminds you. Your always-on focus companion.
author: huiling-one2x
tags: [productivity, focus, memory, awareness, context-switch]
tools: [shell, filesystem, memory, chat]
trigger: "intent guardian|task stack|what was I doing|focus guard|track my tasks"
config:
poll_interval_seconds: 5
interruption_threshold_minutes: 5
reminder_cooldown_minutes: 3
max_stack_depth: 20
screen_capture_enabled: false
screen_capture_interval_seconds: 30
vision_model: ""
activitywatch_enabled: true
activitywatch_url: "http://localhost:5600"
notification_channel: "system"
working_hours_start: "09:00"
working_hours_end: "18:00"
excluded_apps: ["Finder", "SystemPreferences", "loginwindow"]
---

# Intent Guardian

**Never lose your train of thought again.**

Intent Guardian continuously monitors your desktop activity, builds a real-time understanding of what you're working on, and detects when you've been derailed by an interruption and forgotten your original task. When that happens, it nudges you back on track.

## The Problem

Knowledge workers are interrupted every 3 minutes on average. After an interruption, it takes ~23 minutes to return to the original task -- and often, you never return at all. Not because the task isn't important, but because you simply *forgot*.

Intent Guardian solves this by maintaining a **task stack** -- a living model of what you're doing, what you were doing, and what got interrupted -- so you don't have to.

## When to Use

- You are a multi-tasker who frequently context-switches between apps and tasks
- You often finish replying to a message and think "wait, what was I doing?"
- You want an AI companion that understands your work rhythm, not just your commands
- You want to build long-term awareness of your own focus patterns

## Core Capabilities

### 1. Real-Time Activity Sensing

Polls the active window title and application name to build a continuous activity stream.

**macOS:**
```bash
bash command:"scripts/sense_activity.sh"
```

**With ActivityWatch (richer data):**
```bash
bash command:"scripts/sense_activitywatch.sh"
```

**With Screen Capture (optional, requires vision model):**
```bash
bash command:"scripts/sense_screen.sh"
```

### 2. Task Stack Maintenance

The agent maintains a task stack in `memory/skills/intent-guardian/task_stack.json`:

```json
{
"stack": [
{
"id": "task_001",
"intent": "Writing product requirements doc, section 3",
"app": "Google Docs",
"window_title": "Product Requirements v2 - Google Docs",
"started_at": "2026-02-26T14:28:00",
"status": "suspended",
"suspended_at": "2026-02-26T14:31:00",
"suspended_by": "Slack notification from Li Si",
"completion_estimate": 0.6
},
{
"id": "task_002",
"intent": "Replying to Li Si about the API bug",
"app": "Slack",
"window_title": "Slack - #engineering",
"started_at": "2026-02-26T14:31:00",
"status": "completed",
"completed_at": "2026-02-26T14:35:00"
},
{
"id": "task_003",
"intent": "Looking up React useEffect cleanup pattern",
"app": "Chrome",
"window_title": "Stack Overflow - React useEffect cleanup",
"started_at": "2026-02-26T14:35:00",
"status": "active"
}
],
"current_focus": "task_003",
"forgotten_candidates": ["task_001"]
}
```

### 3. Interruption & Forgetting Detection

The agent analyzes the task stack to detect potential forgetting:

**Signals that suggest forgetting:**
- A suspended task has not been resumed for longer than `interruption_threshold_minutes`
- The user has moved through 2+ unrelated contexts since the suspension
- The user shows "wandering" behavior: rapid app-switching without sustained focus
- The suspended task had low completion estimate (was in the middle of something)

**Signals that suggest deliberate abandonment (do NOT remind):**
- The user explicitly closed the application associated with the task
- The task was at a natural completion point (e.g., finished sending an email)
- The user started a clearly intentional new deep-work session

### 4. Gentle Reminders

When forgetting is detected, the agent sends a non-intrusive reminder:

**Simple reminder:**
> "You were working on the product requirements doc (section 3) about 25 minutes ago, before the Slack interruption. Want to go back to it?"

**Smart reminder (with context carried forward):**
> "You left the product requirements doc to look up the useEffect cleanup pattern for Li Si's bug. The answer is: return a cleanup function in useEffect. Ready to bring this back to the doc?"

The second form is more powerful -- it doesn't just remind you what you forgot, it **completes the reason you left**, so you can return to your main task with the answer in hand.

### 5. Long-Term Pattern Learning

Over time, the agent builds a focus profile in `memory/skills/intent-guardian/focus_profile.json`:

```json
{
"user_id": "default",
"updated_at": "2026-02-26",
"patterns": {
"avg_focus_duration_minutes": 12,
"interruption_sources": {
"Slack": { "count": 45, "forget_rate": 0.78 },
"Mail": { "count": 22, "forget_rate": 0.18 },
"Chrome": { "count": 31, "forget_rate": 0.42 }
},
"peak_focus_hours": ["09:00-11:00", "14:00-16:00"],
"high_risk_transitions": [
{ "from": "VSCode", "to": "Slack", "forget_rate": 0.82 },
{ "from": "Google Docs", "to": "Chrome", "forget_rate": 0.55 }
],
"reminder_effectiveness": {
"accepted": 34,
"dismissed": 8,
"ignored": 5
}
}
}
```

This profile is used to personalize detection thresholds and reminder timing.

## Architecture

```
Your Desktop
|
v
[Sensing Layer] ---- scripts/sense_activity.sh (window title, every N sec)
| scripts/sense_activitywatch.sh (ActivityWatch API)
| scripts/sense_screen.sh (optional screenshot + vision)
v
[Activity Log] ---- memory/skills/intent-guardian/activity_log.jsonl
|
v
[Understanding] ---- LLM analyzes activity stream on each Heartbeat:
| - Segments activities into logical tasks
| - Infers intent for each task
| - Detects interruptions and context switches
v
[Task Stack] ---- memory/skills/intent-guardian/task_stack.json
|
v
[Detection] ---- Compares stack state against forgetting heuristics
| Consults focus_profile.json for personalized thresholds
v
[Reminder] ---- Sends reminder via configured notification channel
| Logs user response for feedback loop
v
[Learning] ---- Updates focus_profile.json with new patterns
```

## Heartbeat Integration

Add to your `HEARTBEAT.md`:

```markdown
## Intent Guardian Check
Every heartbeat, run the intent guardian cycle:
1. Read latest activity from memory/skills/intent-guardian/activity_log.jsonl
2. Update task_stack.json with new activities
3. Check for forgotten tasks (suspended > threshold, not resumed)
4. If forgotten task detected, send reminder
5. Log any reminder responses to focus_profile.json
```

## Cron Integration

Add a daily focus report:

```bash
openclaw cron add --name "intent-guardian-daily" --schedule "0 18 * * *" \
--prompt "Generate my daily focus report using intent-guardian data"
```

## Setup

### Minimal Setup (macOS, no dependencies)

1. Install the skill:
```bash
npx playbooks add skill openclaw/skills --skill intent-guardian
```

2. The skill uses native macOS commands (`osascript`) to get the active window.
No additional software required.

3. Add the Heartbeat integration above to your `HEARTBEAT.md`.

### Enhanced Setup (with ActivityWatch)

1. Install [ActivityWatch](https://activitywatch.net/) for richer window-level tracking.
2. Set `activitywatch_enabled: true` in skill config.
3. ActivityWatch provides detailed per-window timelines including URLs and document titles.

### Full Setup (with Screen Capture)

1. Set `screen_capture_enabled: true` and configure `vision_model`.
2. Requires a vision-capable model (Claude, Gemini, Qwen3-VL).
3. Screenshots are captured locally, analyzed locally or via API, and **never stored permanently**.

## Privacy & Security

- **All data stays local.** Activity logs, task stacks, and focus profiles are stored as local files in your OpenClaw memory directory.
- **No raw screenshots are persisted.** If screen capture is enabled, frames are analyzed and immediately discarded. Only the semantic summary is kept.
- **Excluded apps are respected.** Configure `excluded_apps` to prevent tracking specific applications.
- **Working hours enforced.** Sensing only runs during configured `working_hours_start` to `working_hours_end`.
- **You own the data.** All files are human-readable JSON/JSONL. Review, edit, or delete at any time.

## Configuration Reference

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `poll_interval_seconds` | int | 5 | How often to check the active window |
| `interruption_threshold_minutes` | int | 5 | Minutes before a suspended task is flagged as potentially forgotten |
| `reminder_cooldown_minutes` | int | 3 | Minimum time between reminders to avoid nagging |
| `max_stack_depth` | int | 20 | Maximum tasks to track in the stack |
| `screen_capture_enabled` | bool | false | Enable periodic screenshot analysis |
| `screen_capture_interval_seconds` | int | 30 | Interval for screenshots (if enabled) |
| `vision_model` | string | "" | Model for screenshot analysis (e.g., "gemini", "claude") |
| `activitywatch_enabled` | bool | true | Use ActivityWatch for richer activity data |
| `activitywatch_url` | string | "http://localhost:5600" | ActivityWatch server URL |
| `notification_channel` | string | "system" | Where to send reminders ("system", "telegram", "slack", etc.) |
| `working_hours_start` | string | "09:00" | Start of active tracking window |
| `working_hours_end` | string | "18:00" | End of active tracking window |
| `excluded_apps` | list | ["Finder", "SystemPreferences", "loginwindow"] | Apps to ignore |

## Example Interactions

**User:** "What was I doing before I got sidetracked?"
**Agent reads task_stack.json, responds:**
> "Before the Slack interruption at 14:31, you were writing section 3 of the product requirements doc in Google Docs. You were about 60% through. Want to jump back?"

**User:** "Show me my task stack"
**Agent responds with current stack visualization:**
> ```
> Task Stack (3 items):
> [ACTIVE] Looking up React useEffect cleanup (Chrome) - 17 min
> [COMPLETED] Replying to Li Si about API bug (Slack) - 4 min
> [SUSPENDED] Writing product requirements doc, section 3 (Google Docs) - 25 min ago !!
> ```

**User:** "How's my focus today?"
**Agent reads activity log and focus profile:**
> "Today you've had 6 deep work sessions averaging 18 minutes each. You were interrupted 11 times, mostly by Slack (7 times). You forgot to return to your original task 4 times -- I caught 3 of those. Your peak focus was 09:30-10:45."

**Proactive (via Heartbeat):**
> "Heads up -- you've been away from the quarterly report (Excel) for 40 minutes since that phone call. It's due tomorrow. Want to wrap up the current task and go back to it?"

## Integration with Other Skills

Intent Guardian works well alongside these existing skills:

| Skill | Integration |
|-------|-------------|
| `personal-analytics` | Feed focus_profile data into analytics for richer weekly reports |
| `daily-review` | Include task completion stats and interruption counts in daily reviews |
| `deepwork-tracker` | Auto-start deepwork timer when sustained focus is detected |
| `screen-monitor` | Use screen_analyze for richer context when vision model is configured |
| `rememberall` | Convert suspended tasks into time-based reminders as fallback |
| `get-focus-mode` | Suppress reminders when macOS Focus mode is active |

## Roadmap

- [ ] Cross-device sync (remind on phone about tasks left on laptop)
- [ ] Team mode (with consent: "Zhang San is waiting for your review, 2 days now")
- [ ] Proactive task delegation ("I can draft that email reply while you focus on the doc")
- [ ] Calendar-aware urgency ("The quarterly report meeting is in 2 hours, and you're only 60% done")
- [ ] Intent hierarchy (L1-L4 goal tracking, not just immediate tasks)

## License

MIT
Loading