From Reactive to Proactive: How the Proactive Agent Skill Transforms Your AI
Learn how the proactive-agent skill changes Claude Code from a question-answering tool into an initiative-taking developer. Covers WAL integration, trigger configuration, and practical setup.
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:
- You push a commit
- CI fails
- You notice the failure
- You open Claude Code
- You describe the failure
- The agent helps you fix it
Proactive session:
- You push a commit
- CI fails
- The proactive agent detects the failure via a file system watch or webhook
- The agent analyzes the failure, proposes a fix, and either applies it automatically or surfaces it for your review
- 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
/proactiveslash 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
| Action | What Happens |
|---|---|
analyze_and_propose | Agent analyzes the trigger event and presents a proposed fix for your review |
auto_apply | Agent applies the fix automatically and notifies you of the change |
create_issue | Agent creates a GitHub issue with full context |
notify_only | Agent surfaces the event with context but takes no action |
run_command | Agent runs a specified command and reports output |
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:
- Enable the webhook listener:
{
"monitors": {
"ci_webhook": {
"enabled": true,
"webhook_url": "http://localhost:3847/webhook"
}
}
}
- 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