AutoBroker

AutoBroker v0.1.0 is a local-first helper for getting real new-car quotes from dealers. It runs on your Mac, keeps your shopping data local, and helps you move from "I know the car I want" to "I have comparable out-the-door quotes."

Quick Setup

1. Install the basics

You need:

• macOS 12 or newer
• uv for Python setup
• Node.js 22 LTS for the local dashboard bundle
• Google Chrome for dealer websites and inventory pages
• A supported agent runner — either Claude Code (the claude CLI) or the Codex CLI (codex). Install and sign in to whichever you plan to use before step 3.

2. Clone and install

git clone https://github.com/ryanxwy/AutoBroker.git
cd AutoBroker
uv --project autobroker sync
(cd ui && npm install)

3. Choose an agent runner

AutoBroker can run the quote pipeline with either Claude or Codex/OpenAI.

• Claude: follow quickstart/auth-setup.md for subscription OAuth or an Anthropic API key.
• Codex/OpenAI: sign in with codex login, then verify the local driver with:

uv --project autobroker run autobroker doctor --codex

The repo includes project configs for both providers. Browser automation uses chrome-devtools-mcp by default, with Playwright MCP as the explicit fallback.

4. Connect Gmail

AutoBroker uses your own Gmail OAuth client. Follow the BYO OAuth walkthrough:

quickstart/gmail-byo.md

This keeps Gmail credentials under your local macOS account instead of a shared hosted service.

5. Start the dashboard

uv --project autobroker run autobroker up

Open:

http://127.0.0.1:8100

The dashboard and backend run together on that local address. AutoBroker builds the UI bundle if needed and stores pipeline state in a local SQLite database.

What AutoBroker Does

AutoBroker helps you run a new-car quote workflow:

1. Define the vehicle you want.
2. Find nearby dealers.
3. Prepare quote requests.
4. Submit approved dealer forms.
5. Read dealer replies from Gmail.
6. Extract out-the-door quote details.
7. Compare quotes and prepare follow-ups.
8. Close out or reset the search when you are done.

It is local-first: your database, logs, Gmail tokens, and shopping state stay on your machine.

Local Dashboard

The dashboard is the main place to operate AutoBroker. Use it to:

• See the active search profile and dealer list.
• Start pipeline steps from "Run skill".
• Watch progress as the agent works.
• Review approvals before anything visible goes to a dealer.
• Compare extracted quotes once replies arrive.

The dashboard is not a hosted service. It is a local web app served by autobroker up at http://127.0.0.1:8100.

Daily Workflow

Phase 1: Start or reset a search

Run pipeline_reset only when you want to wipe the current local pipeline data and start over. AutoBroker asks for a typed YES before the reset proceeds.

Then run search_profile_intake to capture the car you want: year, make, model, trim, location, and buyer context.

Phase 2: Discover dealers

Run dealer_geosearch to find nearby dealers for the active search. This uses browser navigation and local database writes, so it should not interrupt you for approval.

Phase 3: Request quotes

Run dealer_web_lead_submit when you are ready to contact dealers. AutoBroker can scout dealer websites and prepare form submissions, but it must ask you before submitting any dealer form or sending any outbound Gmail message.

Phase 4: Check replies

Run dealer_inbox_check during the day to pull relevant Gmail replies. This reads Gmail and writes local routing state, so it should not interrupt you for approval.

Then run dealer_reply_extract to turn dealer replies into structured quote records.

Phase 5: Compare and audit quotes

Run quote_pipeline after replies are extracted. It can call quote audit, quote comparison, incentive refresh, follow-up drafting, and digest steps as needed.

Use quote_compare when you want a direct ranked view of current quotes.

Phase 6: Follow up or close out

Run negotiation_followup to draft replies from the quote context. AutoBroker must ask before sending any email.

Run dealer_closeout_email when you are ending a search and want to politely tell active dealers.

Run daily_digest to summarize the current state.

Approval Boundaries

AutoBroker is designed to keep normal local work moving without stopping for every read, page visit, or database row.

Should not interrupt

These are normal local workflow actions:

• Reading or writing local SQLite pipeline data.
• Reading Gmail threads and attachments.
• Navigating public dealer websites.
• Using Google Maps or dealer pages for discovery.
• Updating local watermarks, logs, labels, and dashboard state.

Must ask first

These are hard gates:

• Sending outbound Gmail.
• Submitting a dealer web form.
• Running irreversible dealer_hygiene database writes.
• Running pipeline_reset, which requires a typed YES.

If a dealer can see it, or if local state can be irreversibly removed or suppressed, AutoBroker asks first.

Responsible Use & Disclaimer

AutoBroker automates services that belong to other people and companies. You are responsible for using it lawfully and within the terms of service of everything it touches — the Gmail API, Google Maps, and each dealer's website. Review those terms before you run any outbound step.

• Placeholder phone by default. To limit unsolicited sales calls, AutoBroker fills dealer forms with a placeholder phone number ((555) 010-0000) instead of your real one. To be reached on your real number, tell search_profile_intake you want dealers to call your real phone (this sets the search profile's phone_policy to real); otherwise the placeholder is used on every form.
• Your budget stays private. AutoBroker never puts your budget or target price into dealer-facing forms or messages.
• Every outbound action is gated. Sending Gmail and submitting dealer forms always require your explicit confirmation — see Approval Boundaries.
• Provided "as is." AutoBroker is released under the MIT License with no warranty. Dealer responses, quote accuracy, and any consequences of submitting forms or sending email are your responsibility. Use at your own risk.

Agent and Browser Support

AutoBroker supports Claude and Codex/OpenAI providers.

Browser automation uses isolated MCP browser sessions:

• chrome-devtools-mcp is the default browser backend.
• Playwright MCP is a supported explicit fallback and can be used by Codex too.
• Both browser paths are isolated from your personal Chrome profile.

Validation Model

AutoBroker has deterministic checks for Python services, config, manifests, and the React dashboard. The full quote pipeline is different: it is LLM-driven, Gmail/Keychain-backed, browser-stateful, and permission-gated. That live workflow is validated through the manual harness under harness/, not through a fake deterministic test:e2e.

Useful Commands

uv --project autobroker run autobroker up
uv --project autobroker run autobroker doctor
uv --project autobroker run autobroker status

Common pipeline skills:

Skill	When to use it
search_profile_intake	Start a new vehicle search
dealer_geosearch	Find dealers
dealer_web_lead_submit	Prepare and submit approved quote requests
dealer_inbox_check	Check Gmail for dealer replies
dealer_reply_extract	Extract quote details from replies
quote_compare	Compare current quotes
negotiation_followup	Draft approved follow-up emails
daily_digest	Summarize the current pipeline state
pipeline_reset	Start over after typed confirmation

Documentation

The root README stays focused on first-run usage. Additional project docs are indexed at docs/README.md.

• Security policy
• Contributing
• Code of conduct