Run the researcher worker

The researcher (workers/researcher/) is a local worker for a Mac. It drives a model running in LM Studio through tool calls: the model searches the web, opens pages in Chrome, compares what AudienceKit already stores, and proposes venues and events. The worker validates the proposals and upserts them through the research endpoints with a service token.

It isn’t deployed with the API, because it needs your machine’s LM Studio and Chrome.

Set up

1. Create a service token for the audience, as in Automate with service tokens.

2. In LM Studio, load a model that supports tool calling (for example qwen/qwen3-30b-a3b, meta-llama-3.1-8b-instruct or mistralai/devstral-small; 32k context or more works best) and start the local server on http://localhost:1234.

3. Start Chrome with remote debugging so the worker can use your signed-in sessions:

   open -na "Google Chrome" --args --remote-debugging-port=9222

   Or set CHROME_MODE=launch to have the worker start its own Chrome profile.

4. Install and configure the worker:

   cd workers/researcher
   npm install
   cp .env.example .env   # set AUDIENCEKIT_API_URL and AUDIENCEKIT_SERVICE_TOKEN
   npm run build
   node dist/index.js doctor

   doctor checks the token exchange, LM Studio and Chrome.

Run

node dist/index.js plan                      # show what a pass would do
node dist/index.js run --dry-run --limit 1   # run one task and validate the batch without writing
node dist/index.js run                       # a full pass
node dist/index.js run --watch 360           # a pass every six hours

Each pass fetches the audience’s snapshot, then plans a discover task for each locale with fewer than five venues and a verify task for each venue last verified more than STALE_AFTER_DAYS ago. Payloads and a report.json are written under RUNS_DIR.

To run it in the background, install the LaunchAgent in workers/researcher/launchd/com.audiencekit.researcher.plist; the commands are in the file’s header comment.