How to Connect HubSpot to Claude Code

You want Claude Code to find a contact before a call, see which company they belong to, or draft a follow-up. That is a calm way to use HubSpot. The login does not need to sit in the chat.

The action to be careful with is a merge. HubSpot can combine two contacts into one. After that, you do not get a clean "put them back" button. Notes, emails, and deals have been folded together. If the assistant merged the wrong pair, you are reconstructing history by hand.

A link is different. HubSpot calls that link an association. A contact can be associated with a company, or a deal, without those records becoming the same record. If the link was wrong, you remove the link. The contact and the company are still there.

This article keeps lookup, linking, and merge apart. The next section defines Swytchcode. After that are five HubSpot agents you can start by pasting a prompt.

The same care with a different CRM is in this article: How to Connect Salesforce to Claude Code. HubSpot in the directory is here.

What Swytchcode is

Swytchcode is a production runtime for AI agents. Claude decides which API call to make. Swytchcode runs that call. It is not the model, not the agent framework, and not a catalog standing in for HubSpot.

On every call it does eight checks:

1. Allow list. Only an action you added with swy add method can run.
2. Schema check. Inputs are checked against that action before the request is sent.
3. Policy. Rules in policies.json can allow a call, deny it, or hold it for a person, and can read the arguments.
4. Credentials. The HubSpot token is added when the call runs. It is not put in the chat. You store it with swy auth connect. There is no project env file for it.
5. Execution. The request goes from your machine straight to HubSpot.
6. Retry. Swytchcode backs off when HubSpot says you are going too fast. A create or an update is retried only when an idempotency key is already set.
7. Response check. A success status whose body says the action failed is not treated as success.
8. Audit. The call and the policy decision are written to a local log.

Test or live mode is chosen once with swy init and stored in .swytchcode/tooling.json. On Business and Enterprise, a held call can go to Slack or Telegram. If nobody approves within 48 hours, it never runs.

HubSpot AI agents you can build

Paste one prompt into Claude Code, Cursor, or Codex. The assistant should follow the skills file, search with swy discover, and use the action name that search prints.

1. Contact lookup agent

Finds one person by email. It does not create or edit anyone.

Set up https://www.swytchcode.com/skills.md and build a HubSpot contact-lookup agent. When I give you an email, find that contact and show the company on the record. Do not create, edit, or merge contacts.

2. Association agent

Links a contact to a company. It does not merge the two records into one.

Set up https://www.swytchcode.com/skills.md and build a HubSpot association agent. When I name a contact and a company, link them and show me the link. Do not merge contacts. Do not delete either record.

3. Stalled deal agent

Lists deals that have not moved, for a person to review.

Set up https://www.swytchcode.com/skills.md and build a HubSpot stalled-deal agent. List open deals with no recent activity. Do not change stage, owner, or amount.

4. Follow-up draft agent

Writes a follow-up you can copy. It does not send email.

Set up https://www.swytchcode.com/skills.md and build a HubSpot follow-up agent. Draft a short follow-up for the deal I name and show it to me. Do not send email. Do not change the deal.

5. Duplicate contact agent

Shows two contacts that share an email. It stops before a merge.

Set up https://www.swytchcode.com/skills.md and build a HubSpot duplicate-contact agent. Find contacts that share an email and show both records. Do not merge them. Do not delete them.

HubSpot lookup, associations, and contact merge

A lookup answers "who is this person?" It does not change the database. That is the action to turn on first.

An association answers "this contact works at this company" or "this deal belongs with this contact." It is a change, but a small one. You can take the link off.

A merge answers "these two contacts are the same person, fold them into one." Use it when a person has decided that, and can see both records. Do not let an assistant merge because two email addresses looked similar. Similarity is how you find a candidate. It is not permission to combine them.

If your team does want the assistant to merge sometimes, add that action and have a person approve it. On Business and Enterprise, Swytchcode can hold the call for Slack or Telegram. If nobody approves within 48 hours, it never runs. Free and Pro can allow or deny. They do not include the hold. Writing the rule is in this article: Policy-as-Code for AI Agents.

Creating a contact twice is the other everyday bug. If the assistant creates a contact and never hears back, it may try again and create a second person. Swytchcode retries a create only when the call already carries a stable idempotency key, a note that says this is the same create. A brand-new note is a second contact. If you are not sure HubSpot stored that note for this action, look the contact up instead of creating it again. The plain version is Idempotency Explained.

Follow these steps to connect HubSpot

swy is the short name for the Swytchcode program. Do these in order, from the project folder.

1. Follow this step to install the CLI

If you use Node.js:

npm install -g swytchcode

On Windows PowerShell:

irm https://cli.swytchcode.com/install.ps1 | iex

On macOS or Linux:

curl -fsSL https://cli.swytchcode.com/install.sh | sh

Then run swy --version. A version number means it installed. Continue in the CLI quickstart.

2. Follow this step to sign in

swy login

This is your Swytchcode account, not the HubSpot token. The first two live calls can run before an account. See the authentication docs.

3. Follow this step to start Claude Code in test mode

swy init --editor=claude --mode=sandbox

--mode=sandbox is test mode, saved in .swytchcode/tooling.json. Claude cannot switch it later. Use cursor or codex if that is your editor. See Set up a project.

4. Follow this step to download HubSpot

swy get hubspot

This does not turn every HubSpot action on.

5. Follow this step to find a contact lookup

swy discover "find a contact" --project hubspot

Use the name it prints. --project hubspot keeps the search inside HubSpot. Do not copy a name from an old note, including this article.

6. Follow this step to read the fields

swy info <id from discover>

Replace <id from discover> with the name from step 5. This only works after step 4.

7. Follow this step to turn that lookup on

swy add method <id from discover>

Leave merge off. If you later add an association, add that action on its own, after you have seen a lookup work.

8. Follow this step to store the HubSpot token

swy auth connect hubspot

The token stays on your machine, outside the chat. There is no Swytchcode env file for it. Explore this article: credential brokering.

FAQ

How do I connect HubSpot to Claude Code?

Follow the eight steps in this article. Start with finding a contact. Do not paste the HubSpot token into Claude Code.

Should the assistant merge duplicate contacts?

Not as its default. Show a person the two records. Merging them is hard to undo. A link between records is the safer change.

What is an association?

A link between HubSpot objects, such as a contact and a company. Removing the link does not delete the contact or the company.

Will a retry create two contacts?

It can, if the second try is a new create. Look the email up before you create again.

Read next

• Explore this article if you use Salesforce as well: How to Connect Salesforce to Claude Code.
• How a repeat is treated is in the idempotency guide.

Find one contact, and stop there

Start at step 1 in this article if the CLI is not installed yet. Then ask Claude Code to find one contact by email. Do not ask it to merge anyone.

You can hand Claude Code skills.md and ask it to follow the same steps in test mode.

If two people got combined and you did not mean that, stop and tell us. Discord is the quick conversation. The contact form is better if the CRM records are private. Say what you asked Claude to do.