From Reactive to Proactive: How the Proactive Agent Skill Transforms Your AI

There are two modes an AI coding assistant can operate in.

Reactive: You notice a problem. You describe it to the agent. The agent responds.

Proactive: The agent notices the problem. The agent starts working on it. You review the solution.

Most AI tools default to reactive. The proactive-agent skill flips that default.

This tutorial explains what proactive agents do differently, how the WAL (Write-Ahead Log) integration works, and how to configure the skill for your workflow.

What Proactive Means in Practice

Reactive assistance is useful. Proactive assistance is transformative. Here's the difference:

Reactive session:

1. You push a commit
2. CI fails
3. You notice the failure
4. You open Claude Code
5. You describe the failure
6. The agent helps you fix it

Proactive session:

1. You push a commit
2. CI fails
3. The proactive agent detects the failure via a file system watch or webhook
4. The agent analyzes the failure, proposes a fix, and either applies it automatically or surfaces it for your review
5. You get a notification: "CI was failing on line 47 of auth.test.ts. I've fixed the type mismatch. Review the change?"

The same amount of work gets done. You spend less of your own attention on it.

Installation

clawhub install proactive-agent

This installs:

• The proactive agent runtime (runs as a background process)
• The /proactive slash command for configuration
• WAL integration hooks
• Default trigger definitions

Start the agent:

/proactive start

You'll see:

Proactive Agent v2.4.0 starting...
  ✓ WAL monitor active
  ✓ File system watcher active
  ✓ CI webhook listener active (port 3847)
  ✓ 8 triggers loaded

Agent is running. Use /proactive status to check activity.

How the WAL Integration Works

WAL stands for Write-Ahead Log. In database terms, it's the log of every change before it's committed — a record of what's happening in real time.

The proactive agent implements the same concept for your development environment. It maintains a WAL of:

• File system changes (which files were modified, created, deleted)
• Git operations (commits, branch switches, merges)
• Test run results (pass/fail, which tests changed state)
• Build outputs (success/failure, warnings)
• External events (CI webhooks, deployment results)

Every entry in the WAL is evaluated against your trigger definitions. When a trigger fires, the agent acts.

This is fundamentally different from polling. The WAL captures events as they happen — no delay, no missed changes.

WAL Structure

{
  "timestamp": "2026-03-20T14:32:11Z",
  "event_type": "test_failure",
  "source": "jest",
  "data": {
    "failed_tests": ["auth.test.ts > should refresh expired token"],
    "error": "TypeError: Cannot read property 'refreshToken' of undefined",
    "file": "src/lib/auth.ts",
    "line": 47
  },
  "context": {
    "recent_commits": ["fix: update auth types"],
    "files_changed": ["src/lib/auth.ts", "src/types/auth.ts"]
  }
}

The agent receives this WAL entry and evaluates it against triggers. If the test_failure trigger is active, the agent starts analyzing.

Triggers: Defining When the Agent Acts

Triggers are the rules that tell the agent when to take initiative. The skill ships with 8 default triggers, and you can create your own.

Default Triggers

View them:

/proactive triggers list

Active triggers (8):

  test-failure          — Activate when tests fail after a code change
  type-error            — Activate when TypeScript compilation fails
  security-alert        — Activate when npm audit finds high-severity vulnerabilities
  unused-import         — Activate when linting finds unused imports in changed files
  console-log-commit    — Activate when console.log is staged in a commit
  large-commit          — Activate when a commit modifies more than 20 files
  merge-conflict        — Activate when merge conflicts are detected
  todo-comment          — Notify when TODO/FIXME comments are added to code

Trigger Configuration

Each trigger has configurable behavior:

// .claude/proactive.config.json
{
  "triggers": {
    "test-failure": {
      "enabled": true,
      "action": "analyze_and_propose",
      "auto_apply": false,
      "notify": true,
      "conditions": {
        "min_failures": 1,
        "ignore_patterns": ["*.snap"],
        "only_in_branches": ["main", "develop"]
      }
    },
    "type-error": {
      "enabled": true,
      "action": "analyze_and_propose",
      "auto_apply": true,
      "notify": true,
      "conditions": {
        "max_errors_to_auto_fix": 3
      }
    },
    "security-alert": {
      "enabled": true,
      "action": "create_issue",
      "auto_apply": false,
      "notify": true,
      "severity_threshold": "high"
    }
  }
}

Action Types

For your first week, use analyze_and_propose for everything. Move to auto_apply only for triggers you trust completely (like removing unused imports or fixing lint errors).

Writing Custom Triggers

Add domain-specific triggers in .claude/proactive.triggers.json:

{
  "custom_triggers": [
    {
      "name": "migration-without-rollback",
      "description": "Activate when a database migration is added without a rollback",
      "watch": {
        "event": "file_created",
        "pattern": "migrations/*.ts"
      },
      "condition": "file_content_missing('down()') || file_content_missing('rollback')",
      "action": "analyze_and_propose",
      "message": "New migration detected without a rollback function. Please review."
    },
    {
      "name": "api-route-without-auth",
      "description": "Activate when a new API route is created without auth middleware",
      "watch": {
        "event": "file_created",
        "pattern": "app/api/**/*.ts"
      },
      "condition": "file_content_missing('getServerSession') && file_content_missing('withAuth')",
      "action": "analyze_and_propose",
      "message": "New API route may be missing authentication. Review before committing."
    }
  ]
}

These custom triggers reflect your project's specific concerns — the things that cause bugs on your codebase specifically.

WAL Monitoring: What the Agent Watches

Configure what the agent monitors:

{
  "monitors": {
    "filesystem": {
      "enabled": true,
      "watch_paths": ["src/", "app/", "lib/", "tests/"],
      "ignore_patterns": ["node_modules/", ".next/", "*.log", "dist/"]
    },
    "git": {
      "enabled": true,
      "watch_events": ["pre-commit", "post-commit", "post-merge"]
    },
    "test_runner": {
      "enabled": true,
      "runner": "jest",
      "watch_mode": false
    },
    "build": {
      "enabled": true,
      "detect_from": "package.json scripts"
    },
    "ci_webhook": {
      "enabled": false,
      "webhook_url": "http://localhost:3847/webhook",
      "secret": "your-webhook-secret"
    }
  }
}

CI Webhook Integration

To make the agent react to CI failures in real time, set up a webhook:

1. Enable the webhook listener:

{
  "monitors": {
    "ci_webhook": {
      "enabled": true,
      "webhook_url": "http://localhost:3847/webhook"
    }
  }
}

1. In GitHub Actions, add a webhook notification step:

- name: Notify Proactive Agent
  if: failure()
  uses: distributhor/workflow-webhook@v3
  env:
    WEBHOOK_URL: ${{ secrets.PROACTIVE_AGENT_WEBHOOK }}
    WEBHOOK_SECRET: ${{ secrets.PROACTIVE_AGENT_SECRET }}
    WEBHOOK_DATA: '{"event": "ci_failure", "run_id": "${{ github.run_id }}", "branch": "${{ github.ref_name }}"}'

Now when CI fails on a push, the agent gets notified within seconds and starts analyzing — even before you've noticed the failure.

Balancing Proactivity and Interruption

The risk of a proactive agent is that it interrupts you constantly. A well-configured agent catches important issues without becoming noise.

Quiet Hours

{
  "schedule": {
    "quiet_hours": {
      "enabled": true,
      "start": "22:00",
      "end": "08:00",
      "timezone": "UTC"
    },
    "batch_notifications": true,
    "batch_interval_minutes": 30
  }
}

With batch_notifications, instead of interrupting you every time a trigger fires, the agent collects events and presents a summary every 30 minutes.

Priority Levels

Assign priorities to triggers so you can filter notifications:

{
  "triggers": {
    "security-alert": { "priority": "critical" },
    "test-failure": { "priority": "high" },
    "type-error": { "priority": "high" },
    "unused-import": { "priority": "low" },
    "todo-comment": { "priority": "info" }
  },
  "notification_threshold": "high"
}

With notification_threshold: "high", you only get interrupted for high and critical events. Low-priority issues are logged but don't interrupt your flow.

Checking Agent Activity

/proactive status

Proactive Agent Status

Uptime: 4h 23m
Events processed: 47
Triggers fired: 8
Actions taken: 5
  → 3 proposed fixes (2 applied by you, 1 pending)
  → 1 GitHub issue created
  → 1 notify-only event

Recent activity:
  14:28 — test-failure: 2 failing tests in auth.test.ts → proposed fix
  13:15 — security-alert: 1 high severity vuln in lodash → GitHub issue created
  11:42 — type-error: 3 TypeScript errors after merge → auto-fixed

View the full action log:

/proactive log
/proactive log --trigger test-failure
/proactive log --since "2026-03-20"

Pausing and Stopping

During focused work when you don't want interruptions:

/proactive pause 2h    # Pause for 2 hours
/proactive resume      # Resume early
/proactive stop        # Stop the agent completely

Next Steps

• Install proactive-agent from the marketplace
• Combine with self-improving-agent — the proactive agent fires the reflection cycle automatically after addressing issues
• Add persistent memory so the proactive agent learns which triggers are most important to you over time
• Read the ClawHub CLI guide for skill management