intent-guardian

# 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 S...

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