LeadDemon agent setup.

Requirements

• Python 3.11 or newer and pipx.
• A LeadDemon account with subscription or demo access.
• A human account owner available once to approve the CLI session.
• A connected HubSpot portal only when CRM comparison is needed.

Step 1

Install the CLI

If pipx is missing, use its operating-system install guide first. The versioned LeadDemon wheel does not require GitHub or repository access.

python3 --version
pipx install https://leaddemon.io/downloads/leaddemon-0.2.0-py3-none-any.whl

Step 2

Authorize the agent

Login opens a short-lived browser approval page. Verify the returned user and HubSpot portal before the agent sends business data.

leaddemon login
leaddemon whoami --json
leaddemon workspace status --json

Step 3

Load operating instructions

The CLI installs a version-matched skill into the current project without cloning LeadDemon.

leaddemon agent init --target codex
# Claude Code:
leaddemon agent init --target claude

For bounded Facebook business research, install the separate skill with leaddemon agent init --skill facebook-prospecting --target codex.

Step 4

Plan before running

Start with free discovery. Customize the target profile and geography in the example run configuration, then inspect the plan before starting.

{
  "run_mode": "lead_universe",
  "run_label": "field_service_test",
  "config_preset": "all_states",
  "max_markets": 3,
  "location_mode": "countries",
  "selected_countries": [
    "US"
  ],
  "coverage_level": "statewide_plus",
  "market_depth": "curated",
  "use_discovery": true,
  "use_google": false,
  "use_yelp": false,
  "vet_offerings": true,
  "enrich_contacts": true,
  "target_description": "Field service software companies",
  "search_terms": "field service software\nmobile workforce software",
  "target_services": "dispatch software\nwork order management",
  "exclusion_terms": "directories\njob boards"
}

leaddemon run plan --config run.json --json
leaddemon run start --config run.json --json
leaddemon run watch RUN_ID --json
leaddemon run download RUN_ID --output ./leaddemon-results --json

Paid providers require a reviewed plan and explicit approval of that exact request count and cost. Never infer spend approval from an earlier run.

Dedupe an existing file

When a user already has prospects, skip discovery. Dry-run the selected CSV or XLSX table locally, then compare it with a fresh pull from the connected HubSpot portal.

leaddemon workspace status --json
leaddemon dedupe prospects.xlsx --sheet Prospects --dry-run --json
leaddemon dedupe prospects.xlsx --sheet Prospects \
  --against hubspot --output ./dedupe-results --json

• net_new.csv contains unmatched records, not outreach clearance.
• dedupe_review.xlsx preserves existing, review, unmatched, and file-duplicate decisions.
• The workflow performs no discovery and no HubSpot writes.

Leave these actions to a human

leaddemon workspace status --json returns the correct account, billing, and connection handoff URLs.

Recover without duplicating work

• Run leaddemon login again when the local refresh session expires.
• After a timeout, inspect leaddemon run list --json before starting anything else.
• Reuse a printed dedupe --request-id only with the identical input.
• Use leaddemon logout to revoke the current CLI session.

Agent-friendly reference: https://leaddemon.io/agents.txt