ProspectAI Desktop Agent

A lightweight CLI that connects to your ProspectAI workspace and runs LinkedIn automation (connect, message, comment, scrape) through a real headless browser. No Chrome extension needed.

Runs on macOS and Windows. Requires Node.js 18+.

Quick Start

# 1. Install
npm install -g prospect-ai-agent

# 2. Pair with your workspace (get code from Campaigns > Desktop Agent)
prospect-ai-agent pair <CODE> -s https://your-app-url.com

# 3. One-time LinkedIn login (opens a browser window)
prospect-ai-agent login

# 4. Start the agent (runs headless in background)
prospect-ai-agent start

Or run without installing:

npx prospect-ai-agent pair <CODE> -s https://your-app-url.com
npx prospect-ai-agent login
npx prospect-ai-agent start

How It Works

ProspectAI Web App (control plane)     Desktop Agent (execution layer)
┌──────────────────────────────┐       ┌──────────────────────────────┐
│  Campaigns UI                │       │  CLI (commander)             │
│  - Create campaigns          │       │  - pair / login / start      │
│  - Approve AI comments       │       │  - run / status / unpair     │
│  - View connected agents     │       │                              │
│                              │       │  Agent Daemon                │
│  Automation APIs             │ <──── │  - Heartbeat (60s)           │
│  - GET  /next-job            │       │  - Poll for jobs (5 min)     │
│  - POST /report              │       │  - Launch headless browser   │
│  - POST /heartbeat           │       │  - Execute job via Playwright│
│  - GET/POST /cookies         │       │  - Close browser after task  │
└──────────────────────────────┘       └──────────────────────────────┘

The agent polls for pending automation jobs, launches a headless Chromium browser only when there's work, executes the task, and closes the browser. Session cookies are encrypted and synced with the server.

Commands

| Command | Description | |---|---| | pair <CODE> -s <URL> | Pair this device with your ProspectAI workspace | | login | One-time LinkedIn authentication (opens headed browser) | | start | Start background daemon (heartbeat + job polling) | | start --interval 10 | Start with custom poll interval (1–30 minutes, default 5) | | run | Execute one pending job immediately and exit | | status | Show current device configuration | | unpair | Disconnect this device and remove local config |

Supported Job Types

| Type | Description | |---|---| | connect | Send a LinkedIn connection request | | message | Send a LinkedIn direct message | | scrape_connections | Sync your LinkedIn connections list | | scrape_posts | Fetch latest post per prospect (for comment campaigns) | | comment | Post an approved comment on a LinkedIn post |

Setup Steps

1. Pair with workspace

Generate a pairing code from the Campaigns page in ProspectAI (Desktop Agent button), then:

prospect-ai-agent pair ABC123 -s https://your-app-url.com

This saves a JWT token and device info to ~/.bluehans-agent/config.json.

2. Authenticate with LinkedIn

prospect-ai-agent login

A headed browser opens. Log in to LinkedIn normally. Once you reach the feed, the agent captures your session cookies, encrypts them, and closes the browser. This is a one-time step.

3. Start the agent

prospect-ai-agent start

The agent runs continuously:

• Sends heartbeat every 60 seconds
• Polls for jobs every 5 minutes (configurable with --interval)
• Launches headless Chromium per task, closes after completion
• Reports results back to ProspectAI

Press Ctrl+C to stop.

Local Data

All data stored in ~/.bluehans-agent/:

| Path | Contents | |---|---| | config.json | JWT token, device ID, server URL | | cookies.enc | Encrypted LinkedIn session cookies |

Troubleshooting

"Not paired" — Run pair with a fresh code from the app.

"No cookies available" — Run login to authenticate with LinkedIn.

Heartbeat failing (401) — JWT expired (30-day lifespan). Run unpair then pair again.

Jobs not executing — Ensure campaigns are in Active status. Check with status command.

Security

• Agent JWT tokens expire after 30 days; re-pair to renew
• Revoke any device instantly from ProspectAI Settings
• LinkedIn cookies are encrypted with AES-256-GCM
• Only structured job types are executed (no arbitrary code)
• Browser launches headless and closes after each task

License

Private — for use with ProspectAI only.