LoopAgent v1

A read-only WhatsApp agent for an agency owner. It reads approved client groups through a linked device, turns client requests into tasks, runs a reply clock and a fix clock on each, and alerts you (Windows toast plus phone push) when a clock breaks. It never sends a WhatsApp message.

Built from "WhatsApp loop-closer agent: build spec v1". A line-by-line walkthrough of the code is in the Claude Doc shared with this code.

Folder layout on the laptop

C:\LoopAgent\
  app\          this code (loopagent\, tools\, tests\, requirements.txt ...)
  venv\         the Python virtual environment
  config.yaml   static settings (copied from config.example.yaml by the installer)
  data\         agent.db, whatsapp.db (the linked-device session), media\, status.json
  logs\         worker.log, supervisor.log (10 x 10 MB each, rotating)

Install (Windows 11, once)

1. Install Python 3.12 (64-bit) from python.org. Tick "Add python.exe to PATH".

2. Copy this folder to C:\LoopAgent\app.

3. In PowerShell:

   py -3.12 -m venv C:\LoopAgent\venv
   C:\LoopAgent\venv\Scripts\pip install -r C:\LoopAgent\app\requirements.txt
   cd C:\LoopAgent\app
   C:\LoopAgent\venv\Scripts\python -m loopagent.install --root C:\LoopAgent

   The installer asks for the Jev API key and healthchecks.io details (all stored in Windows Credential Manager, never in files), creates your owner record, optionally imports staff from a CSV like staff.example.csv, registers the LoopAgent task in Task Scheduler and starts it.

4. On your phone, install the ntfy app and subscribe to the alert topic the installer printed.

5. Open http://127.0.0.1:8765/health and scan the QR code from WhatsApp > Linked devices > Link a device.

6. On the Groups page, approve your client groups. Tracking starts at approval.

7. Leave alerts in shadow mode (the default) for about 5 working days, mark Jev's answers right or wrong on task pages, then turn on live alerts in Settings.

The first voice note downloads the Whisper "small" model (about 480 MB) into data\models.

Everyday use

The tray icon is green, amber or red. Its menu: Open dashboard, Pause alerts for 1 hour, switch power mode, Restart worker, Quit.

Run things by hand (from C:\LoopAgent\app):

..\venv\Scripts\python -m loopagent.worker --root C:\LoopAgent       # the worker alone, with a console
..\venv\Scripts\python -m tools.replay --root C:\LoopAgent --since 2026-10-01 --set act=0.90

The replay tool copies the database, applies your threshold changes to the copy, and prints which past decisions would change. Add --reask to ask Jev again with today's questions (this costs API calls).

Tests

pip install -r requirements-dev.txt        # on Linux/macOS the Windows-only packages are skipped
python -m pytest tests -q

The suite (76 tests) covers working-time arithmetic, every state transition, the thresholds, bursts, phone tokens, redaction, all 12 end-to-end scenarios from the spec, every dashboard page, a real worker start and stop, and the replay tool. It runs with a fake clock, a scripted Jev and recording notification channels, so it needs no network, no WhatsApp and no Windows.

Check these first on the laptop

These could not be tested away from Windows and a real WhatsApp account:

1. Pairing: the QR appears on the Health page, scanning links, the tray turns green.
2. A test message in an approved group appears as a task within two minutes (look at the Jev call on the task page).
3. Health > Send a test notification: a toast appears, and a push arrives on the phone.
4. A phone button (Snooze 1h) acts on the task and a confirmation push arrives.
5. Task Scheduler: the task starts at log on and after unlock, and only one tray icon appears.
6. Sleep the laptop for 10 minutes with a message sent meanwhile: after waking, the message is processed and any overdue alerts come as one bundle.
7. The tray power switch: with "stay awake when plugged in", powercfg /requests lists pythonw.exe under SYSTEM while on mains power.
8. healthchecks.io: the check shows pings every 5 minutes, and its schedule matches your business hours.