CLAUDE.md

Guidance for Claude Code working with this repository.

Quick Start

uv sync --all-extras         # Install dependencies
uv run pre-commit install    # Setup hooks
cp .env.example .env         # Add FRONTAPP_API_KEY

Essential Commands

NEVER CANCEL long-running commands - they may appear to hang but are processing.

API Facts Index — Read this first

For routine factual questions about the generated API surface, read docs/api-facts.yaml before grepping the api/ tree. It is generated by scripts/generate_api_facts.py and validated in CI by uv run poe facts-check, so it cannot drift from the generated code.

The file pre-computes the most common queries:

• "Does list_X return field_results, a raw array, or a single object?" → summary.list_endpoints_with_field_results / summary.list_endpoints_returning_raw_array
• "Which endpoints are mutations (need two-step confirm)?" → summary.mutations
• "Which generated module names have name quirks (_a_ infix, removes_ prefix)?" → summary.module_name_quirks
• "Is there already a helper / domain projection for resource X?" → tags.<resource>.helper.built / tags.<resource>.domain.built
• "What's the response model class name for list_X?" → tags.<resource>.endpoints[].response_type

When the answer isn't in the facts file (rare — check summary.* first), fall back to direct inspection of frontapp_public_api_client/api/<tag>/. Always prefer the facts file for context efficiency: one Read returns answers that would otherwise require dozens of file inspections.

CRITICAL: Zero Tolerance for Ignoring Errors

FIX ALL ISSUES. NO EXCEPTIONS.

• NO noqa, type: ignore, exclusions, or skips
• NO "pre-existing issues" or "unrelated to my changes" excuses
• NO --no-verify commits
• ASK for help if blocked - don't work around errors

Proper fixes:

• Too many parameters? → Create a dataclass
• Name shadows built-in? → Rename it
• Circular import? → Use TYPE_CHECKING block

Verify Your Work

Always run the appropriate validation tier before considering work complete. See the Essential Commands table above - use quick-check during development, agent-check before committing, and check before opening a PR. Don't trust that code works just because it looks right.

Continuous Improvement

This file is meant to evolve. Update it when you learn something that would help future sessions:

• Fix a tricky bug? Add the root cause to Known Pitfalls.
• Discover a new anti-pattern? Add it to Anti-Patterns to Avoid.
• Find a command or workflow that's missing? Add it to Essential Commands or Detailed Documentation.
• Hit a confusing API behavior? Document it so the next session doesn't waste time rediscovering it.

The same applies to all project documentation - if instructions are wrong, incomplete, or misleading, fix them as part of your current work rather than leaving them for later.

Known Pitfalls

This is a living document. When you discover a new recurring mistake, surprising API behavior, or gotcha during development, add it here so future sessions don't repeat it.

Common mistakes to avoid:

• Editing generated files — api/**/*.py, models/**/*.py, and client.py are generated. Run uv run poe regenerate-client instead of editing them directly.
• Editing the spec in-place — docs/frontapp-openapi.yaml is vendored and sanitized. To pull upstream changes run uv run python scripts/vendor_spec.py, not a direct edit. If upstream adds a quirk that breaks codegen, patch the sanitization rules in scripts/vendor_spec.py rather than hand-editing the YAML.
• UNSET vs None confusion — attrs model fields that are unset use a sentinel value, not None. Use unwrap_unset(field, default) from frontapp_public_api_client.domain.converters, not isinstance or hasattr checks.
• Manual status code checks — Don't write if response.status_code == 200. Use unwrap_as(), unwrap_data(), or is_success() from frontapp_public_api_client.utils.
• Pagination: cursor tokens — Front uses cursor-based pagination. List responses include _pagination.next as a full URL; pass the page_token query parameter back to the list endpoint to fetch the next page. limit caps page size (max 100, default 50). No total count is returned.
• Front search syntax (q= parameter) — Conversation list/search endpoints accept Front's query DSL: status:open tag:urgent assignee:me before:2024-12-31. Not every filter is a separate query param — they're all in the q= string.
• Generated list-response field names — openapi-python-client prefixes fields with field_ when they'd otherwise collide with Python (leading-underscore names). So _results becomes field_results, _pagination becomes field_pagination. Always use getattr(parsed, "field_results", None) or [] when unwrapping list responses. Which list endpoints use field_results vs return raw arrays is enumerated in docs/api-facts.yaml under summary.list_endpoints_with_field_results and summary.list_endpoints_returning_raw_array. Front's spec is currently all-field_results (the raw-array set is empty); the facts file is the authoritative source if that ever changes.
• Front error responses have no single schema — Front doesn't define a canonical ErrorResponse type; each endpoint models errors inline. utils.unwrap() dispatches on HTTP status code, not on parsed-type isinstance checks. Don't try to import an ErrorResponse model from models/; there isn't one.
• None-to-UNSET conversion — When building attrs API request models from optional fields, use to_unset(value) from frontapp_public_api_client.domain.converters instead of value if value is not None else UNSET.
• Help resource drift — frontapp_mcp_server/.../resources/help.py contains hardcoded tool documentation. When adding or modifying tool parameters, also update the help resource content to stay in sync.
• typecheck skips generated code deliberately — ty check only runs over hand-written paths (helpers/, domain/, frontapp_client.py, utils.py). The generated api/ and models/ have ~9 false positives from openapi-python-client's from_dict patterns that ty (pre-1.0) doesn't narrow correctly. When adding new hand-written modules, extend the typecheck task path list in pyproject.toml to include them. Revisit the exclusion when ty hits 1.0 — tracked in issue #8.
• git push -u origin <branch> can land on main — when a feature branch is created via git checkout -b <name> origin/main, its upstream is origin/main, so a bare git push -u origin <name> resolves to main and bypasses PR review. The scripts/pre-push-guard.sh pre-commit hook blocks this. The right form for first-time pushes is git push -u origin HEAD:refs/heads/<branch-name>. --no-verify is forbidden — fix the push command instead.
• uv.lock drift you didn't cause — when you start a branch off an older main and a sibling-package release (e.g. mcp-vX.Y.Z) lands on main while you work, your uv.lock will show modifications you didn't make once you sync or run uv sync. Stage and commit it (git add uv.lock) bundled with your other work — don't try to revert it. The lockfile is authoritative and CI re-resolves from pyproject.toml anyway, so a stale lockfile causes spurious CI diffs.
• Generator/script edits without committing the regen — when you edit scripts/vendor_spec.py, scripts/regenerate_client.py, or scripts/generate_api_facts.py, you must also run the corresponding regenerate task and commit the regenerated output. block-generated-edits.sh blocks direct edits to generated files but doesn't catch this case (the generator changes look unrelated). CI will fail on facts-check or generated-client diff if you forget.
• Live Front API data must not enter the repo — when testing against a real Front workspace, never commit raw response fixtures, names, emails, or conversation bodies from real customers. Sanitize to placeholders (cnv_TEST, customer@example.com, generic message bodies) before saving as a test fixture or example. Front workspaces contain customer PII and the published client is a public package.

Using the LSP tool

Both Python (pyright) and TypeScript (typescript-language-server) LSPs are wired through Claude Code plugins (pyright-lsp@claude-plugins-official and typescript-lsp@claude-plugins-official, enabled in .claude/settings.json → enabledPlugins). The plugins only register the language servers — the binaries themselves must be installed and on PATH:

uv tool install pyright                              # pyright + pyright-langserver → ~/.local/bin
npm install --prefix ~/.local typescript-language-server typescript
# then symlink both binaries into a directory already on PATH (e.g. ~/bin/)

If LSP <op> returns No LSP server available for file type: .py (or .ts), the plugin isn't enabled or the binary isn't reachable — verify which pyright-langserver / which typescript-language-server and restart Claude Code after enabling the plugin.

Prefer LSP operations over Read + Grep for type and call-graph questions — they are faster, more accurate, and cross-reference the real type system (including third-party libraries in .venv).

Project root must match workspace root. The pyright config lives at pyrightconfig.json (relative venvPath: "."). CLI pyright uses it automatically (npx pyright or uv run pyright); the langserver reads it on startup.

Reach for LSP first in these situations

It's easy to fall back on Grep reflexively — these are the situations where doing so is genuinely worse than the LSP:

• Before extracting a helper, renaming a symbol, or changing a function signature — LSP findReferences returns the precise call graph. Grepping the symbol name misses re-exports, dynamic dispatch, and string-only matches in unrelated docs; LSP doesn't.
• Before designing a class that mirrors an existing one — LSP documentSymbol on the canonical file (e.g. helpers/contacts.py) gives you the full method list in one hop; Read walks the whole file.
• When debugging a 'X' object has no attribute 'y' style error — LSP hover on the access tells you whether the type is Unset, None, a domain model, or a third-party class. Grepping for the field misses the type relationship.
• Refactors that touch >10 files — get the call graph from LSP findReferences, then mechanically rewrite. Lesson from PR #71 (confirm_or_preview rollout): a grep-driven refactor missed several formatting variants the regex didn't catch and needed a hand-edit pass to clean up.

If the question is "where is the string foo in this repo?" — Grep. If the question is "what calls / extends / overrides / shadows foo?" — LSP.

LSP known limitations

• workspaceSymbol returns nothing in this tooling — pyright only indexes open files, and the LSP tool doesn't expose the query parameter. Use Grep for project-wide symbol search instead (e.g., Grep "def format_md_table").
• goToImplementation is not implemented by pyright — use goToDefinition instead.
• goToDefinition on external-library imports returns "no definition found" — use hover instead, which gives you the class signature + docstring.
• If hover returns Unknown for a project-external import (e.g., pydantic, fastmcp), the langserver is stale — flag to the user that Claude Code needs a restart to re-read pyrightconfig.json. All project-internal imports should always resolve.

Architecture Overview

Monorepo with 3 packages:

• frontapp_public_api_client/ — Python client with transport-layer resilience and hand-written domain helpers (client.conversations.… + more as verticals ship)
• frontapp_mcp_server/ — FastMCP server exposing Front operations as AI tools
• packages/frontapp-client/ — TypeScript client (hey-api generated + transport middleware for retries and pagination)

API scope: Front's Core API — 139 paths, 233 generated operations across conversations, messages, contacts, teammates, tags, inboxes, channels, rules, analytics, etc. Bearer auth on every endpoint.

Key patterns:

• Transport-layer resilience — retries, rate-limit awareness live in the httpx transport stack, not on individual methods. Every endpoint inherits them automatically via FrontappClient.
• Two-layer API surface — direct from frontapp_public_api_client.api.<tag> import <operation> access to every generated endpoint, plus hand-written client.<resource>.… facades that return Pydantic domain models for the most-used resources.
• Two-step confirm on MCP mutations — tools like update_conversation and create_draft_reply take a confirm: bool = False parameter; confirm=False returns a preview, confirm=True both executes and elicits explicit user approval via ctx.elicit. Outbound replies always go through the drafts vertical (create_draft_reply, create_draft_on_channel, etc.) — there is no direct-send tool. See ADR-0016 → "Drafts-first outbound".
• Spec sanitization at vendor time — Front's upstream OpenAPI spec has a few quirks that break openapi-python-client (example values on required path params, allOf-inherited defaults, binary */* attachment downloads). scripts/vendor_spec.py downloads and patches before writing docs/frontapp-openapi.yaml.

File Rules

The .claude/hooks/block-generated-edits.sh PreToolUse hook enforces the generated-file boundary; an attempted Edit/Write/MultiEdit on any file in the "DO NOT EDIT" row exits 2 with regen-flow guidance. The canonical glob list lives in .claude/hooks/_lib/generated-paths.sh and is shared with format-on-edit.sh — adding a new generated path means changing it once.

Commit Standards

feat(client): add feature    # Client MINOR release
fix(mcp): fix bug            # MCP PATCH release
docs: update README          # No release

Use ! for breaking changes: feat(client)!: breaking change

API Response Handling Best Practices

Use the helper utilities in frontapp_public_api_client/utils.py for consistent response handling:

Response Unwrapping

from frontapp_public_api_client.utils import unwrap, unwrap_as, unwrap_data, is_success
from frontapp_public_api_client.domain.converters import unwrap_unset
from frontapp_public_api_client.models.conversation_response import ConversationResponse

# Single-object responses (200 OK with parsed model)
conv = unwrap_as(response, ConversationResponse)  # Type-safe with validation

# Paginated list responses — Front wraps results in _results (→ field_results)
parsed = unwrap(response)
results = getattr(parsed, "field_results", None) or []

# For success-only responses (202 Accepted, 204 No Content)
if is_success(response):
    # Handle success case

# For attrs model fields that may be UNSET
tags = unwrap_unset(conv.tags, [])  # Returns [] if UNSET

When to Use Each Pattern

For the authoritative per-endpoint shape (which list returns field_results vs a raw array vs a single object), consult docs/api-facts.yaml — summary.list_endpoints_with_field_results, summary.list_endpoints_returning_raw_array, and tags.<resource>.endpoints[].list_shape are CI-validated and cannot drift.

Anti-Patterns to Avoid

# ❌ DON'T: Manual status code checks
if response.status_code == 200:
    result = response.parsed
# ✅ DO: Use helpers
result = unwrap_as(response, ExpectedType)

# ❌ DON'T: isinstance with UNSET
if not isinstance(value, type(UNSET)):
    use(value)
# ✅ DO: Use unwrap_unset
use(unwrap_unset(value, default))

# ❌ DON'T: hasattr for attrs-defined fields
if hasattr(conv, "status"):
    status = conv.status
# ✅ DO: Use unwrap_unset (attrs fields always exist, may be UNSET)
status = unwrap_unset(conv.status, None)

Exception Hierarchy

unwrap() and unwrap_as() raise typed exceptions:

• AuthenticationError - 401 Unauthorized
• ValidationError - 422 Unprocessable Entity
• RateLimitError - 429 Too Many Requests
• ServerError - 5xx server errors
• APIError - Other errors (400, 403, 404, etc.)

Claude Code Commands

Project slash commands in .claude/commands/ and skills in .claude/skills/:

Claude Code Agents

Sub-agents in .claude/agents/ that can be spawned for delegated work during complex tasks:

The vertical-planner and domain-advisor both consult docs/api-facts.yaml as their primary knowledge source. When you have a one-off factual question about the API surface mid-task, prefer domain-advisor over grep+ls.

Detailed Documentation

Discover on-demand - read these when working on specific areas:

Validation tiers, commit standards, and file rules are documented inline in this file — see "Essential Commands", "Commit Standards", and "File Rules" above.