🦞 Proactive Claw

Proactive Claw is a proactive execution engine that collaborates with you and learns from you.

It helps you be more productive by making smart suggestions at the right moment — and (by default) only applying what you approve.

Everything can run locally.

Safety in one glance ✅

✅ Asks before applying changes (default)
✅ Writes only what you approve (no surprise calendar edits)
✅ Local-first core bundle (no external integration helpers)
✅ Everything can run locally (small/local scoring model recommended)
✅ Local state folder is transparent and deletable

Why people install it (what you feel in week 1)

You show up prepared more often.
Your calendar becomes more realistic (buffers appear where they matter).
Deep work blocks stop getting shredded by “just one quick meeting.”
Follow-ups stop slipping.
Proactive Claw learns your style quickly: prep durations, preferred times, what you reject, what you always accept.

In short: it becomes your personal assistant.

Graph A — the simple loop (how it works at a glance)

+--------------------------+        +--------------------------+
| Calendar                 |        | Chat                     |
| Google Calendar/Nextcloud|        | (your control loop)      |
+------------+-------------+        +------------+-------------+
             |  events <-> suggestions           | prompts <-> decisions
             |                                   |
             +-------------------+---------------+
                                 |
                                 v
                  +--------------------------------------+
                  |            Proactive Claw             |
                  |  - notices what's coming              |
                  |  - prioritizes what matters           |
                  |  - suggests prep / buffers / followup |
                  |  - learns from your feedback          |
                  |  - applies only what you approve      |
                  +--------------------------------------+

Key idea: Proactive Claw is proactive, but you remain the decision-maker (by default).

Quick start (2 minutes)

Run readiness checks:

bash scripts/setup.sh --doctor

If dependencies are missing, print one install command:

bash scripts/setup.sh --print-install-cmd google
# or: bash scripts/setup.sh --print-install-cmd nextcloud

Bootstrap calendar connection:

bash scripts/setup.sh

Run a safe preview:

bash scripts/quickstart.sh

Approve a suggestion in chat, then run once:

python3 scripts/daemon.py

Modes (choose your vibe)

Suggest (default): asks before applying changes (max_autonomy_level=confirm)
Background (manual): run local daemon yourself (python3 scripts/daemon.py --loop)
Autonomous (advanced): explicit opt-in only (not recommended until you’ve used it for a while)

Presets (easy setup)

You don’t need to tune dozens of settings. Pick a preset.

Presets are just a starting point. Proactive Claw adjusts to you with every interaction (approvals, edits, rejections), and quickly becomes personal.

A) Calm mode (minimal interruptions)

Choose this if you want only high-value suggestions.

fewer prompts
only important events get prep/buffers

B) Builder mode (deep work protected)

Choose this if you code/build and need long focus blocks.

defends 2–3h deep work windows
suggests moving meetings that fragment focus
stronger buffers + recovery time

C) Meetings-heavy week

Choose this when your schedule is packed.

adds buffers + reset breaks
prevents back-to-back collapse
proposes follow-ups so action doesn’t slip

(If you want, these presets can be expressed as a small copy/paste block in config.json.)

Chat scoring model (built-in; small/local recommended)

Proactive Claw includes a chat scoring model to rank signals (importance, urgency, disruption risk) so it knows:

what matters,
when to ask you,
and when to stay quiet.

Recommendation: use a small model, ideally local (fast, cheap, private).
Your planning model can be bigger; scoring should stay small and fast.

Scenarios (mini transcripts)

1) Presentation tomorrow → prep + buffer

You: Tomorrow I’m presenting the roadmap to the board.
Claw (score = 0.92): High impact. You usually prep ~70 minutes for presentations.
Claw: Want me to reserve 08:40–09:50 for prep + a 10-min buffer before the 10:00 meeting?

2) Deep work protection (developer mode)

Claw (score = 0.78): This meeting would split your deep work block (09:30–12:00).
Claw: Prefer to move it to 13:00, or keep it and add a 20-min recovery buffer after?

3) Back-to-back day → buffers + reset

Claw (score = 0.81): Tomorrow is back-to-back from 10:00–14:00.
Claw: Add 10-min buffers between meetings + a 25-min reset break around midday?

4) Follow-up that tends to slip

You: I promised I’ll send the summary.
Claw (score = 0.66): Time-sensitive.
Claw: Want a 20-min follow-up block right after the meeting (or at 17:10)?

5) It becomes personal fast (recurring pattern)

Claw (score = 0.71): I’ve noticed a pattern for “Client Review” meetings:

you prefer 30-min prep the same day
10-min buffer before
no meetings after 18:00
Claw: Want me to propose this pattern whenever a new “Client Review” appears (still asking you to approve)?

Graph B — technical architecture (backend = Google OR Nextcloud)

TECHNICAL ARCHITECTURE (backend = Google OR Nextcloud)

             +----------------------------------------------+
             |        Calendar backend (choose ONE)         |
             |  +-----------------------+  OR  +----------+ |
             |  | Google (OAuth/API)    |      | Nextcloud| |
             |  +-----------------------+      | (CalDAV) | |
             |                                 +----------+ |
             +-----------------------+----------------------+
                                     ^
        events / changes (propose+apply, Actions only)       |
                                     |
                                     v
+----------------------+      +------------------------------------------+      +----------------------+
|  OpenClaw Chat UI    | <--> |           Proactive Claw Core            | <--> |  Local state         |
| prompts <-> decisions|      | 1) Ingest: events + chat signals         |      | config/token/SQLite  |
| feedback loop        |      | 2) Score: urgency/importance (local rec) |      | logs (optional)      |
+----------------------+      | 3) Plan : prep + buffers + follow-ups    |      +----------------------+
                              | 4) Approve (default): ask/confirm in chat|
                              | 5) Apply : write approved changes        |
                              | 6) Learn : from your approvals/edits     |
                              +------------------------------------------+
                                     ^
                                     |
                           Optional (explicit opt-in)
                                     |
                                     v
                              +----------------------+
                              | Optional daemon      |
                              | periodic scan/suggest|
                              +----------------------+

Setup

0) Requirements

python3 available on your machine
Google backend: credentials.json (OAuth client)
OR
Nextcloud backend: CalDAV URL + app password (or token)

1) Validate dependencies + bootstrap config

bash scripts/setup.sh --doctor
bash scripts/setup.sh --print-install-cmd google
# install dependencies manually
bash scripts/setup.sh

2) Choose your calendar backend

Option A — Google Calendar (OAuth)

You provide:

credentials.json (OAuth client)

Proactive Claw creates:

token.json after OAuth

Option B — Nextcloud (CalDAV)

You provide:

CalDAV base URL
app password

3) Configure behavior

Interactive wizard:

python3 scripts/config_wizard.py

Safe defaults:

python3 scripts/config_wizard.py --defaults

4) Core boundaries (this package)

Includes: scripts/daemon.py for manual local runs.
Excludes from published bundle: cross-skill connectors, team awareness, daemon installers, optional remote OAuth bootstrap, voice bridge, and llm rater.
No background installer is shipped in this package.

FAQ

Will this mess up my calendar?

By default: no. Proactive Claw suggests changes in chat and applies only what you approve (max_autonomy_level = confirm).

Where does it store data?

Locally under: ~/.openclaw/workspace/skills/proactive-claw/

Does everything run locally?

Yes — it can. The scoring model is recommended to be small/local. The calendar backend still connects to your chosen provider because that’s where your calendar lives.

Can I use it without Google?

Yes — use Nextcloud (CalDAV).

Does core include daemon installer helpers?

No. Core includes scripts/daemon.py for manual runs. No launchd/systemd installer is published in this package.

What does “learning” mean here?

It learns your preferences from your approvals/edits over time: prep durations, preferred times, buffer sizes, meeting types that matter, and deep work rules.

What is the chat scoring model?

A lightweight model that assigns numeric scores (e.g., 0.66, 0.92) to decide what matters and when to prompt you. Recommended: small/local model.

Troubleshooting (by symptom)

“Too many prompts” → use Calm mode; reject a few times; it will adapt
“Not proactive enough” → run python3 scripts/daemon.py --loop for continuous local scanning
“Prep blocks are wrong length” → edit them twice; it will converge
“OAuth issues” → re-run setup; revoke token and re-auth if needed

Uninstall

Delete: ~/.openclaw/workspace/skills/proactive-claw/
Revoke Google OAuth access if you used Google: myaccount.google.com/permissions

Glossary

Prep block: time reserved before an event to prepare
Buffer: short gap that prevents schedule collisions
Deep work: uninterrupted focus block
Daemon: background loop process (python3 scripts/daemon.py --loop)
Score: 0–1 number indicating importance/urgency

To improve this 100×, here’s what would help:

Your config key list (or config.example.json) so I can turn presets into copy/paste blocks safely.
Whether you want scores displayed as 0.92 or 92/100 (both numeric; one is friendlier).
If you want an “Advanced” section for autonomous mode or prefer to keep it out of the main doc.