Skillget

hubspot-sales-agent

mcp
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • exec() — Shell command execution in src/db.ts
  • process.env — Environment variable access in src/tools/gmail.ts
  • network request — Outbound network request in src/tools/gmail.ts
  • process.env — Environment variable access in src/tools/hubspot.ts
  • network request — Outbound network request in src/tools/hubspot.ts
  • exec() — Shell command execution in src/tools/webfetch.ts
  • network request — Outbound network request in src/tools/webfetch.ts
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This tool is an autonomous sales agent that automates outbound workflows. It bridges HubSpot and Gmail to research leads, generate personalized email drafts, classify inbox replies, and track pipeline progress.

Security Assessment
The tool requires access to highly sensitive data, specifically HubSpot CRM records and full Gmail API integration. To function, it makes necessary outbound network requests and reads environment variables for API authentication. The most critical security finding is the presence of shell command execution (`exec()`) in `src/db.ts` (likely for managing its local SQLite database) and `src/tools/webfetch.ts` (likely for fetching external data). While no hardcoded secrets were found and the tool explicitly states it does not send emails without human review, unsanitized shell execution introduces an elevated risk of code injection. Overall risk: Medium.

Quality Assessment
The codebase is very new and recently maintained, with its last push occurring today. It uses the standard, permissive MIT license. However, community trust and visibility are currently very low, evidenced by only 5 GitHub stars. Because it is an early-stage project with minimal public scrutiny, potential bugs or security edge cases might not yet be identified by the open-source community.

Verdict
Use with caution — while the tool has a clear license and avoids sending unauthorized emails, its early-stage low visibility and use of risky shell execution commands warrant a thorough private code review before connecting it to critical business accounts.
SUMMARY

Autonomous sales agent — bulk outreach, inbox classification, research-driven personalization, lead recovery. HubSpot + Gmail. Runs on any local agent harness.

README.md

HubSpot Sales Agent

Your autonomous sales team — lead scoring, cold outreach, research-driven personalization, inbox classification, and pipeline recovery.
Runs on any local agent harness.

Node.js 18+ MIT License HubSpot Gmail Harness-agnostic

What Is This?

A modular, autonomous sales agent that automates the outbound workflow. It reads contacts and deals from HubSpot, generates personalized email drafts in Gmail, classifies replies, and tracks everything in a local SQLite database. It never sends emails on its own — it prepares drafts for human review.

Industry-agnostic (works for any vertical via a configurable research layer) and harness-agnostic (runs on Claude Code, Cursor, Continue, or any local harness via plain CLI tools). Full design rationale in docs/architecture.md.

5-Minute Quickstart

Get from zero to your first draft in five minutes.

1. Clone + install (1 min)

git clone https://github.com/Dominien/hubspot-sales-agent.git
cd hubspot-sales-agent && npm install

Choose your path:

Path A — MCP (recommended, fastest)

If your harness supports MCP (Claude Code, Cursor, Continue, Windsurf):

2a. Connect MCP servers (1 min)

  • Add the HubSpot MCP server and Gmail MCP server in your harness settings
  • Auth is handled by the MCP servers — no .env file needed

3a. Run your first skill in PREVIEW mode (1 min)

Paste into your agent session:

Read skills/follow-up-loop.md and CLAUDE.md in PREVIEW MODE.
Process max 5 contacts — show me each draft, no Gmail calls, no tracker writes.

Path B — CLI (universal fallback)

If your harness doesn't support MCP, or you prefer debugging via terminal:

2b. Add credentials (2 min — see docs/setup.md for the full walkthrough)

cp .env.example .env
# Fill in your HubSpot Private App token (pat-xxx) and 3 Google OAuth vars

Note: HubSpot deprecated API keys. You need a Private App token — create one at HubSpot Settings → Integrations → Private Apps. See docs/setup.md for the full walkthrough.

3b. Verify (30 sec)

npx tsx src/tracker.ts read    # prints [] → ready

4b. Run your first skill in PREVIEW mode (1 min)

Paste into your agent session:

Read skills/follow-up-loop.md and CLAUDE.md in PREVIEW MODE.
Process max 5 contacts — show me each draft, no Gmail calls, no tracker writes.

5. Review (30 sec)

The agent prints drafts to the console. Nothing was sent. Nothing was stored. That's the safety posture: review everything before promoting to a real run.

Ten Composable Skills

Skill What It Does
pipeline-analysis Analyzes the entire HubSpot pipeline — contacts, deals, segments, agent coverage — and recommends which action-skill to run next (forward-looking)
performance-review Closes the feedback loop. Joins tracker drafts with reply outcomes, computes per-segment conversion contrasts, proposes evidence-backed Section C rules for learnings.md (backward-looking)
follow-up-loop Autonomous bulk outreach to HubSpot contacts — drafts personalized follow-ups until stopped
inbox-classifier Reads incoming replies, classifies them into 8 categories, drafts responses to positive replies, and syncs HubSpot status
research-outreach Researches a lead's website/business using a configurable audit type, embeds top findings in a personalized email
lead-recovery Decision framework for stale/burned-out deals — recommends recovery levers or pipeline cleanup
compose-reply Deep-context single-lead composer — assembles full email history + HubSpot data + custom new context and drafts a careful reply for one specific lead
prospect-research Deep intelligence gathering — company profile, recent signals, decision-maker mapping, pain-point hypotheses. Outputs structured dossiers that cold-outreach consumes
cold-outreach First-touch cold emails for prospects with zero prior relationship. Value-first framing, signal-based hooks from prospect dossiers, different rules than follow-up-loop
crm-manager Full HubSpot CRM management from the terminal. Create contacts, move deals through stages, assign tasks, add notes, check pipeline. No more tab-switching to HubSpot UI

Each skill is self-contained. Invoke them independently or combine them in workflows. Monday-morning pair: run performance-review first (what worked last week), then pipeline-analysis (what to work on next). The rest of the week runs the action skills the analysis recommended.

Lead scoring (built-in utility)

Every contact gets a fit score (ICP match), engagement score (reply history), and priority tier (A/B/C/D). Scoring runs as a natural step — not a separate skill — when other skills need to prioritize. Configure your ICP definition in knowledge/scoring-config.md.

npx tsx src/scoring.ts score-tracker   # score all tracker contacts
npx tsx src/scoring.ts rank            # print contacts sorted by priority

Usage

Analyze your pipeline

Read skills/pipeline-analysis.md and CLAUDE.md.
Analyze the entire HubSpot pipeline and recommend which action-skill to run next.
Output: console summary + full report to output/analysis/pipeline-<date>.md.
Do NOT change any HubSpot data. Analysis only.

Run the follow-up loop autonomously

Read skills/follow-up-loop.md and CLAUDE.md, then start the autonomous loop.
NEVER STOP. Work through all HubSpot contacts until manually interrupted.

The agent fetches contacts from HubSpot, reads each contact's notes, generates a personalized email, creates a Gmail draft, logs to the tracker, and moves to the next contact.

Classify inbox replies

Read skills/inbox-classifier.md and CLAUDE.md.
Run with default filter: newer_than:7d in:inbox.
Classify all new replies, create reply drafts for positive ones, update HubSpot status.

Research-driven outreach for a curated list

Read skills/research-outreach.md, knowledge/research-config.md, and CLAUDE.md.
Run for these leads:
- [email protected], John Smith, Acme Inc, acme.com, ATTEMPTED_TO_CONTACT
- [email protected], Jane Doe, Beta Corp, beta.com, NEW

For each lead: audit the domain, extract top-3 findings, save the report,
create an HTML email draft with the findings embedded, log to the tracker
with notes_summary prefix "RES:".

Deep-context reply to a single high-value lead

Read skills/compose-reply.md and CLAUDE.md.
Compose a reply to [email protected].

New context:
- They just posted on LinkedIn about expanding to 3 new markets this quarter

Desired outcome:
- Warmly re-engage, use the LinkedIn post as a hook, offer a short call.

Assemble full context from HubSpot + Gmail history + tracker, generate a
brief, then draft the email. Ask me before creating the Gmail draft.

Manage HubSpot from the terminal

Read skills/crm-manager.md.
Create a contact for [email protected] — John Smith, CEO at Acme Inc.
Then create a deal "Acme Website Redesign" in the appointment scheduled stage,
linked to that contact, amount 12000, close date end of this month.

Research a prospect and send a cold email

Read skills/prospect-research.md and CLAUDE.md.
Research these companies and create dossiers:
- [email protected], John Smith, Acme Inc, acme.com
- [email protected], Jane Doe, Beta Corp, beta.io

Then read skills/cold-outreach.md and CLAUDE.md.
Use the dossiers to draft first-touch cold emails for each lead.

See prompts/invoke-skill.md for every skill invocation, every mode, and workflow examples.

Workflows

Workflow A — Weekly planning (recommended starting point)

Monday morning:
1. Run performance-review  → last week's numbers + proposed Section C rules
2. Human promotes any proposed rules to knowledge/learnings.md Section C
3. Run pipeline-analysis   → full report + recommended actions
4. Pick top 1-2 actions for the week
5. Run the recommended skills (follow-up-loop / research-outreach / lead-recovery)
6. Human reviews drafts and sends
7. Run inbox-classifier daily through the week

The performance-review → pipeline-analysis pair closes the loop: backward-looking (what worked) informs forward-looking (what to do next).

Workflow B — Send wave + follow up

Day 0:   Run follow-up-loop autonomously → 50-100 drafts in Gmail
Day 0:   Human reviews and sends
Day 1-2: Run inbox-classifier with "newer_than:2d"
Day 2:   Human reviews reply drafts and sends

Workflow C — Pipeline recovery

1. Run lead-recovery for stale deals → recommendation per deal
2. Build lead list from "value-first" recommendations
3. Run research-outreach with that list
4. Human reviews and sends
5. Run inbox-classifier 1-2 days later

Workflow D — Daily inbox maintenance

Morning: Run inbox-classifier with "newer_than:1d"
Human reviews reply drafts (5 min) and sends

Workflow E — Cold outreach pipeline (new leads)

1. Build lead list (manual curation, purchased list, or LinkedIn export)
2. Run prospect-research → dossiers with pain-point hypotheses
3. Run cold-outreach → signal-based cold emails using dossiers
4. Human reviews drafts and sends
5. Run inbox-classifier after 2-3 days
6. Positive replies → compose-reply for deep follow-up

Workflow F — Scored pipeline prioritization

1. Run scoring: npx tsx src/scoring.ts score-tracker
2. Run pipeline-analysis (now includes score distribution)
3. A-tier leads without outreach → prospect-research + cold-outreach
4. B-tier leads → follow-up-loop or research-outreach
5. D-tier leads → lead-recovery to decide if worth keeping

State files

Two state files live in the repo — both single sources of truth for their concern:

  1. tracker.db — per-contact tracker (SQLite, 16 columns). Every draft, skip, error, reply classification, plus lead scores (fit_score, engagement_score, priority_tier). Backed by SQLite as of v2.6 — binary-safe fields, WAL concurrency, indexed lookups. Dump to TSV or JSON on demand via npx tsx src/tracker.ts export. Full schema + CLI reference in docs/architecture.md.
  2. knowledge/learnings.md — living memory (3 sections). Section A cheat sheets (static, you edit), Section B running log (append-only, skills write), Section C distilled patterns (human-promoted from B). Every skill reads this at start, writes at end via src/learnings.ts. The feedback loop is closed weekly by performance-review, which proposes Section C rules with evidence that you copy-paste manually.

Both files are gitignored.

Dashboard UI (optional)

A local Next.js dashboard lives in ui/ — read-only over the tracker and learnings, with a skill trigger that copies the composed prompt to your clipboard or opens a new Terminal tab running claude.

npm run ui:install   # first time only
npm run ui:dev       # starts at http://127.0.0.1:3000

Four tabs: Pipeline, Performance, Skills, Learnings. Localhost-only, never deploy publicly. Full walkthrough in docs/dashboard.md.

Safety

  • Drafts only — the agent can never send emails, only create drafts
  • Human review required — every outgoing message waits in Gmail for manual approval
  • No duplicate drafts — tracker check prevents drafting the same contact twice
  • Configurable skip flags — contacts with certain notes are automatically excluded
  • No invented details — the agent is instructed to stay generic when notes are unclear
  • No destructive HubSpot operations — the agent only updates lead status and adds notes, never deletes

Known Limitations

  • Gmail rate limits — the Gmail API enforces quota limits; large batches may be throttled
  • Notes extraction — depends on consistent note formatting in your HubSpot CRM
  • Basic webfetch audit — the built-in webfetch.ts covers basic SEO signals. For richer audits (Lighthouse, full-page render, etc.), extend the tool or integrate an external service
  • OAuth setup — Gmail OAuth requires a one-time refresh token generation. See docs/setup.md
  • No email sending — by design (drafts only)
  • Dashboard UI is localhost-only — never deploy publicly. Terminal-run mode is macOS-only; other platforms fall back to clipboard copy

Deeper docs

Contributing

Contributions welcome. See CONTRIBUTING.md.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT — Marco Patzelt

Reviews (0)

No results found