hubspot-claude: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A Claude Code plugin (/hubspot, package hubspot-agent, currently 0.2.14) for natural-language HubSpot CRM administration. Claude orchestrates ~44 specialist sub-agents that each call the hubspot CLI over Bash, with mandatory human-in-the-loop approval for every write. Implementation is complete and actively maintained — this is no longer a greenfield project.

Commands

pip install -e ".[dev]"                  # editable install with test deps
pytest -x                                # full suite (~960+ passed, 3 skipped)
pytest tests/test_cli_hitl.py -v         # one module
pytest tests/test_safety.py::test_name   # one test
claude plugin validate ./                # schema-check plugin.json + marketplace.json + hooks
bash scripts/check-artifact-allowlist.sh # shipping-artifact allowlist gate (run before release)
claude --plugin-dir ./                   # load the plugin locally for a session

Tests use pytest-asyncio, respx/pytest-httpx (no live HubSpot calls), and hypothesis (tests/property_based/). tests/conftest.py isolates Path.home() so tests never touch real ~/.claude/hubspot/ state.

Architecture

Claude is the orchestrator; the CLI is the source of truth. There is no custom orchestration framework — Claude Code's native Agent tool spawns stateless sub-agents whose prompts come from hubspot agent-prompt <name>. Sub-agents call ${CLAUDE_PLUGIN_ROOT}/bin/hubspot tool <name> --input '<json>' --portal <id> --working-dir <dir>. --portal/--working-dir are top-level flags and must precede --input.

Three call paths, one handler set. bin/hubspot (POSIX sh venv resolver) → router.py, which prefers the warm-client daemon (daemon.py, Unix-socket JSON-RPC reusing one HubSpotClient + schema cache), falls back to in-process execution, and cli.py also runs sync. All three share handlers.py, so the approve→execute safety contract (destructive-count gate, undo snapshot, created-id capture, audit entry, clear-pending) is identical everywhere. When changing write behavior, change handlers.py/safety.py — never one path.