Starting a Session

Running the local development server

Start the dev server in a separate terminal before working with Claude Code:

cd ~/Sites/<project-name>

# Theme projects
shopify theme dev --store your-store.myshopify.com

# Hydrogen projects
pnpm dev

Starting Claude Code

cd ~/Sites/<project-name>
claude

Activate the platform agent

The first thing to do in every session is activate the right agent:

activate_agent("theme-developer")      # Liquid themes
activate_agent("hydrogen-developer")   # Hydrogen storefronts

From there, issue commands as described in the command reference.

Tips

Say “Figma MCP” explicitly in your first prompt of a session. Claude Code sometimes attempts bash alternatives instead of the MCP tools if you are not specific.
Playwright CLI opens a visible Chrome window. The first time Claude Code navigates to your preview, you may need to authenticate manually. Once logged in, the session persists for the remainder of the workflow.
Activate QA Engineer alongside your platform agent when doing code reviews or audits — see QA Engineer.

Session initialisation sequence

Every session completes this sequence before any build work begins:

Session starts
  │
  ▼
CLAUDE.md auto-loaded by Claude Code
  │  → Project type, tech stack, file conventions
  │
  ▼
Activate platform agent (theme-developer or hydrogen-developer)
  │  → Component patterns, build rules, validation,
  │    platform-specific conventions (~300-500 lines)
  │
  ▼
get_conventions called from Dev MCP (remote)
  │  → Universal rules, MCP toolchain config,
  │    design tokens, communication style
  │
  ▼
CONVENTIONS.md read
  │  → This project's tokens, component library, APIs, icons, logos
  │
  ▼
get_project_context called
  │  → Command history, saved notes, agent preference
  │
  ▼
Engineer issues a command