crospector

Autonomous purchase journey verification for e-commerce.

crospector navigates to a product URL, adds it to cart, and verifies the result. No hardcoded flows — a vision-language model sees the page and decides what to do at every step. Every run produces forensic evidence (annotated screenshots, accessibility trees, network logs). Every run makes the next run better through a seven-layer self-improvement loop.

AGPL-3.0. crospector.com

Install

npm install -g crospector

Requires Node.js 18+. That's it.

Usage

crospector purchase https://www.amazon.com/dp/B0D1XD1ZV3

On first run, crospector prompts you to log in with your email (same account as crospector.com). New accounts go on a waitlist — you'll receive an email when your access is confirmed.

Once approved, crospector runs on our cloud infrastructure. No GPU, no Python, no model downloads required on your machine.

Outcomes

| Exit code | Outcome | Meaning | |---|---|---| | 0 | JOURNEY_COMPLETE | Product verified in cart | | 2 | PRODUCT_NOT_AVAILABLE | Out of stock, discontinued, or region-locked | | 1 | JOURNEY_FAILED | Navigation could not complete the flow |

Commands

crospector purchase <URL>    Run a purchase journey
crospector login             Log in to your crospector account
crospector logout            Log out
crospector whoami            Show current account and status

Self-host

Run crospector on your own infrastructure. No account required.

Requirements

| | Minimum | Recommended | |---|---|---| | GPU VRAM | 6 GB (INT4) | 10 GB (INT8) | | RAM | 16 GB | 32 GB | | CPU | 4 cores | 8 cores | | Disk | 50 GB | 200 GB | | Python | 3.11+ | 3.12+ | | Node.js | 18+ | 22+ |

Runs on NVIDIA (CUDA 11.8+), AMD (ROCm), and Apple Silicon (Metal).

Install and run

npm install -g crospector
crospector purchase https://www.amazon.com/dp/B0D1XD1ZV3 --self-hosted

First run takes ~5 minutes to set up the local runtime (automatic, one-time):

• Python virtual environment at ~/.crospector/venv/
• Ollama (local LLM runtime)
• Qwen2.5-VL-7B model (~4.5 GB)
• Camoufox browser binary

Self-hosted commands

crospector purchase <URL> --self-hosted    Run a purchase journey
crospector benchmark --self-hosted         Run the benchmark suite
crospector improve --self-hosted           Run the overnight improvement loop
crospector consolidate --self-hosted       Consolidate agent memory

Self-hosted options

--self-hosted      Run locally instead of crospector cloud
--path <dir>       Evidence storage directory (default: ~/.crospector/data)
--no-headless      Show the browser window
--max-steps <N>    Maximum navigation steps (default: 30)
--verbose          Debug logging

Docker

docker build -t crospector .
docker run --gpus all -v ~/.crospector/data:/data crospector purchase https://www.amazon.com/dp/B0D1XD1ZV3

Build from source

For developers who want to modify or extend crospector.

git clone https://github.com/crospector/crospector.git
cd crospector/python

# Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Install Ollama + model
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5vl:7b

# Run directly via Python
python -m crospector.cli purchase https://www.amazon.com/dp/B0D1XD1ZV3

Project structure

crospector/
  bin/crospector.js       Global CLI entry point (npm)
  lib/auth.js             Cognito authentication (cloud mode)
  lib/setup.js            Python/Ollama environment setup (self-hosted mode)
  python/
    crospector/
      cli.py              Python CLI entry point
      browser.py           Camoufox browser provider
      navigation.py        Goal-driven navigation loop
      vlm.py               Qwen2.5-VL via Ollama
      som.py               Set-of-Mark visual prompting
      evidence.py          Forensic evidence capture
      verify.py            Outcome verification
      diagnostic.py        Failure diagnosis
      rsi.py               Trajectory scoring and filtering
      memory.py            Episodic/semantic/working memory
      prompts.py           VLM prompt templates
      config.py            Configuration management
      output.py            Result formatting
    pyproject.toml         Python package definition
  package.json             npm package definition
  CROSPECTOR.md            Technical design document

How it works

crospector is a goal-driven web agent. The VLM (Qwen2.5-VL-7B) makes ALL navigation decisions. There are no CSS selectors, no platform-specific patterns, no hardcoded element targeting. The VLM sees annotated screenshots and decides what to do.

Navigation loop:

1. Capture screenshot from stealth browser (Camoufox)
2. Inject Appstract DOM signatures + overlay SoM labels on interactive elements
3. Send annotated screenshot + accessibility tree to VLM
4. VLM decides: what page am I on, what should I do next, which element to interact with
5. Execute the action via Playwright on Camoufox
6. Capture evidence (screenshot, HTML, accessibility tree, agent reasoning)
7. Repeat until goal reached or failure

Self-improvement: Every run feeds a seven-layer data flywheel:

1. Per-step reward scoring (OpenClaw-RL PRM)
2. Failure diagnosis and routing (TraceSIR-inspired)
3. Trajectory quality filtering (DigiRL + SSDF)
4. Overnight prompt optimization (autoresearch)
5. VLM fine-tuning from clean trajectories (DigiRL LoRA)
6. Agent knowledge accumulation (CrewAI training)
7. Memory consolidation (MemVerse-inspired)

Architecture

| Component | Choice | License | |---|---|---| | Browser | Camoufox (C++ Firefox fork) | MPL-2.0 | | Navigation | Browser Use (ReAct agent loop) | MIT | | VLM | Qwen2.5-VL-7B via Ollama | Apache 2.0 | | Grounding | Set-of-Mark prompting + Appstract | MIT | | Multi-agent | CrewAI (4 specialist agents) | MIT | | Verification | OSWorld getter/metric architecture | Apache 2.0 | | Model distribution | HuggingFace Hub | Apache 2.0 |

See CROSPECTOR.md for the complete technical design document with SOTA references.

Evidence

Every journey (self-hosted) produces a complete evidence trace at ~/.crospector/data/evidence/<journey-id>/:

20260316_143022_a1b2c3d4/
  manifest.json             Journey metadata
  journey.json              Complete step log
  journey.webm              Full video with real mouse cursor
  checksums.sha256          Integrity hashes
  steps/
    001/
      screenshot.png        Raw screenshot
      screenshot_annotated.png  SoM-labeled screenshot
      original.html         Page HTML
      signed.html           Appstract-annotated HTML
      accessibility.json    Accessibility tree
      vitals.json           Web vitals (LCP, CLS, FID, ...)
      cookies.json          Cookie state
      storage.json          localStorage + sessionStorage
      agent/
        prompt.txt          VLM input
        response.json       VLM decision
        reasoning.txt       VLM reasoning chain
    002/
      ...

License

AGPL-3.0-only. See LICENSE.

crospector is free software. You can use it, modify it, and distribute it under the terms of the GNU Affero General Public License v3. If you run a modified version as a network service, you must make your source code available to users of that service.

Dependencies use MIT, Apache 2.0, and MPL-2.0 licenses. See license-map.md for the complete dependency license audit.