Stop Reverse-Engineering Websites Manually: design-research Does It in 15 Minutes

You've been there. Staring at a stunning website, mentally dissecting every shadow, every hover state, every perfectly balanced whitespace ratio. Your designer brain screams "I need to build this" — but your practical brain knows what's coming: hours of DevTools archaeology, screenshot comparisons, color picker eyedrops, and the inevitable moment you realize you missed the subtle backdrop-filter that makes the whole thing work.

What if you could clone the entire design intelligence of any website in the time it takes to grab coffee?

Enter design-research — a Claude Code skill that deploys 10 specialized browser-automation agents to systematically dismantle, document, and deliver a complete design reference document. No guesswork. No missed details. No more squinting at computed styles until your eyes water.

This isn't just another design tool. It's a parallelized design intelligence operation running inside your actual Chrome browser, leveraging your real login sessions, capturing authentication-gated experiences that traditional scrapers can't touch. The kind of thing that makes you wonder how you ever worked without it.

Ready to see how deep this rabbit hole goes?

What is design-research?

design-research is an open-source Claude Code skill created by Hamel Husain (@hamelsmu) that automates comprehensive website design research through coordinated browser-automation agent teams. Released as a MIT-licensed project, it transforms what was traditionally a 4-8 hour manual process into a 10-15 minute automated pipeline.

The tool sits at the intersection of three exploding trends: AI agent orchestration, browser automation, and design system extraction. As frontend development increasingly prioritizes design consistency and component reuse, the ability to rapidly analyze and document existing implementations has become critical — yet maddeningly tedious when done by hand.

What makes design-research genuinely innovative is its agent team architecture. Rather than a single AI sequentially grinding through a checklist, it spawns 10 specialized research agents that work in coordinated passes, with dependencies managed between phases. Some agents run in parallel immediately; others wait for prerequisite intelligence before launching. This mirrors how senior design teams actually work — parallel specialists, not serial generalists.

The project leverages Claude Code's experimental agent teams feature, which requires tmux for split-pane visualization of parallel agent operations. Each agent operates its own Chrome tab through the Claude in Chrome extension, reading DOM structures, extracting computed styles, capturing screenshots, and interacting with pages as a human researcher would.

Critically, because agents use your actual Chrome browser, they inherit your authentication state. Researching a competitor's SaaS dashboard? Analyzing a paid course platform's UX patterns? The agents see exactly what you see, cookies and all. This eliminates the authentication nightmares that plague headless browser approaches.

Key Features That Make It Insane

True Parallel Agent Orchestration The 10-agent structure isn't marketing fluff — it's a carefully designed dependency graph. First-pass agents (site structure, colors/typography, visual personality, technical implementation, accessibility) launch simultaneously with zero dependencies. Second-pass agents (page layouts, component inventory, content templates, UX patterns) wait for site structure completion. The final responsive-behavior agent requires layout documentation first. This intelligent task scheduling maximizes throughput while ensuring analytical coherence.

Authenticated Browser Research Unlike Puppeteer, Playwright, or traditional scraping tools that struggle with login flows and 2FA, design-research operates through your lived-in Chrome profile. The Claude in Chrome extension creates a bridge where each agent opens fresh tabs in your existing session. This means gated content, personalized dashboards, and subscriber-only features are all within research scope — a capability that fundamentally expands what's auditable.

Structured Markdown Output The synthesized deliverable isn't a messy dump. It's a single, navigable markdown document with precise technical specifications: hex/RGB/Tailwind color values, complete typography scales with font stacks and weights, measured layout diagrams, component hierarchies, responsive breakpoint documentation, and accessibility assessments. Enough fidelity to faithfully recreate or systematically evolve any design.

Live Visual Monitoring With tmux split panes (or iTerm2 native integration via tmux -CC), you watch agents work in real-time. Each specialist occupies its own pane, scrolling, clicking, inspecting elements as you would. This transparency isn't just satisfying — it's debuggable. When something looks off, you see where the agent got confused.

Skill Integration for Repeat Use Install once, invoke forever. The skill system lets you trigger audits with simple commands like /design-research https://example.com, making it a persistent capability in your Claude Code workflow rather than a one-off script.

Use Cases Where It Absolutely Shines

Competitive Design Analysis Your competitor launched a gorgeous onboarding flow. You need to understand their progressive disclosure pattern, micro-interaction timing, and breakpoint behavior — not just static screenshots, but how it feels across states. design-research captures the full interactive surface, giving you actionable intelligence for your own UX evolution.

Design System Archaeology Inherited a codebase with scattered styling and no documentation? Point design-research at the production site and get instant archaeology — the living design system extracted from reality, not outdated Confluence pages. Colors actually used, not just specified. Components that exist, not just planned.

Mentorship & Learning Studying how the best teams build? Audit Vercel's dashboard, Linear's issue tracker, or Notion's editor. The output becomes a masterclass in implementation — exact values you can compare against your own choices, understanding why professionals made specific tradeoffs.

Cross-Platform Consistency Checks Running a product across web and mobile web? Use design-research to document your own production site as a regression baseline. Subsequent audits catch drift before users do. The structured output diffs cleanly for version comparison.

Agency & Consulting Work Client wants their site "like Airbnb but for X"? Instead of subjective mood boards, deliver objective design intelligence — exact specifications their team can implement. Transforms vague references into concrete requirements, reducing revision cycles dramatically.

Step-by-Step Installation & Setup Guide

Step 1: Install Claude Code

The foundation. Requires version 2.0.73 or later for agent team support:

npm install -g @anthropic-ai/claude-code

Verify with claude --version before proceeding.

Step 2: Install the Claude in Chrome Extension

Download from the Chrome Web Store. This extension is the critical bridge — it lets Claude drive your actual browser with all your existing sessions, cookies, and login states. No API tokens. No auth scripts. Your browser, your identity, automated.

Follow the setup guide for troubleshooting if the extension doesn't connect immediately.

Step 3: Install tmux

Agent teams require tmux for parallel pane management. Without it, agents collapse into a single invisible process — you lose monitoring and risk resource contention.

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

macOS iTerm2 users: Use tmux -CC for native tab/split integration. This renders tmux panes as native iTerm2 splits — dramatically better visual experience.

Step 4: Enable Experimental Agent Teams

Agent teams are disabled by default. Activate via settings file:

mkdir -p ~/.claude

Create or edit ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or export for the current session:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step 5: Launch Your Audit Session

Start tmux, then launch Claude with Chrome connectivity and permission bypass (essential for 10 agents to operate without constant approval prompts):

# Start tmux with iTerm2 integration (recommended for macOS)
tmux -CC

# Inside tmux session:
claude --chrome --dangerously-skip-permissions

Critical: Chrome must be running with the extension active before this step. The --dangerously-skip-permissions flag is required because 10 agents each requesting permission for every DOM read would create 50+ modal dialogs — functionally breaking the workflow. Understand this security tradeoff: agents have broad page access during the audit.

Step 6: Execute the Design Research

With Claude running, issue your research command. Use the remote skill file or local clone:

Read https://raw.githubusercontent.com/hamelsmu/design-research/main/skills/design-research/SKILL.md and follow those instructions for https://example.com. Write findings to notes/example-research.md

Or with local installation:

Read /path/to/design-research/skills/design-research/SKILL.md and follow those instructions for https://example.com. Write findings to notes/example-research.md

Step 7: Install as Persistent Skill (Optional)

For frequent use, add to Claude's skill directory:

mkdir -p ~/.claude/skills
cp -r skills/design-research ~/.claude/skills/

Now invoke with: /design-research https://example.com

REAL Code Examples from the Repository

Let's examine the actual implementation patterns from design-research's documentation and understand what makes this system tick.

Example 1: Core Skill Invocation Pattern

The fundamental interaction model — how you trigger a 10-agent audit with a single command:

# Remote skill invocation - no clone required
Read https://raw.githubusercontent.com/hamelsmu/design-research/main/skills/design-research/SKILL.md and follow those instructions for https://example.com. Write findings to notes/example-research.md

What's happening here? This leverages Claude Code's ability to fetch and execute skill definitions from URLs. The Read command loads the SKILL.md prompt file, which contains the complete agent orchestration logic — task definitions, dependencies, output formats. The URL parameter specifies the research target. The write destination ensures persistent output. This pattern means zero installation for one-off audits — bookmark this command template and deploy anywhere.

Example 2: Environment Configuration for Agent Teams

The experimental feature flag that unlocks parallel agent execution:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Deep dive: This JSON configuration in ~/.claude/settings.json persists the feature flag across Claude sessions. The "env" key injects environment variables into Claude's runtime context. Without this, the claude binary runs in single-agent mode — all 10 research tasks would serialize through one context window, destroying the parallelization that makes design-research time-efficient. The experimental status means this API may evolve; monitor Claude Code docs for changes.

Example 3: Chrome-Connected Launch with Permission Bypass

The precise launch incantation for authenticated, multi-agent browser automation:

# iTerm2 on macOS (recommended)
tmux -CC

# Then inside tmux:
claude --chrome --dangerously-skip-permissions

Critical security context: The --chrome flag establishes WebSocket communication with the Claude in Chrome extension, which must be installed and active. The --dangerously-skip-permissions flag is explicitly named to warn you — it suppresses the per-action approval prompts that would otherwise flood your session with 10 agents making DOM queries. This is safe for research on sites you trust, but understand that compromised agents could perform unwanted actions. The tmux wrapper provides process isolation and visual monitoring as partial mitigation.

Example 4: Skill Installation for Persistent Access

The filesystem pattern for making design-research a native Claude capability:

mkdir -p ~/.claude/skills
cp -r skills/design-research ~/.claude/skills/

Architecture insight: Claude Code's skill system scans ~/.claude/skills/ for directories containing SKILL.md files. By copying the skills/design-research directory (from the cloned repo) into this location, you register the skill globally. The directory name becomes the slash command trigger: /design-research. This follows Unix philosophy — filesystem-based configuration, no registry or package manager required. The -p flag on mkdir ensures parent directory creation without errors on repeat execution.

Example 5: Agent Team Dependency Orchestration

The three-pass execution model, as documented in the repository's "What happens" section:

1. Claude creates an agent team
2. **First pass** — 5 agents run in parallel (no dependencies):
   - Site Structure & Navigation
   - Design System (Colors & Typography)
   - Visual Design & Personality
   - Technical Implementation
   - Accessibility & Semantics
3. **Second pass** — 4 agents run in parallel (after site structure is mapped):
   - Page Layouts & Chrome
   - Interactive Components Inventory
   - Content Type Templates
   - UX Patterns & Micro-interactions
4. **Third pass** — 1 agent (after page layouts are documented):
   - Mobile & Responsive Behavior
5. The lead synthesizes all findings into a single structured markdown report

Orchestration analysis: This dependency graph is the core innovation. Pass 1 agents are embarrassingly parallel — they need no shared state. Pass 2 agents require site structure knowledge to navigate intelligently; attempting page layout analysis without knowing what pages exist would waste tokens on 404s. Pass 3's responsive behavior agent needs layout baselines to detect breakpoint changes. The lead agent's synthesis step implies reduction of 10 partial reports into one coherent document — a map-reduce pattern implemented with language model agents.

Advanced Usage & Best Practices

Token Budgeting A full 10-agent audit uses approximately 10x the tokens of a single Claude session. For complex sites, this can approach context window limits. Research simpler sites first to calibrate costs. The parallel architecture means you're trading token efficiency for time efficiency — appropriate for urgent research, wasteful for casual curiosity.

Authentication Hygiene Since agents inherit your browser identity, audit from a dedicated Chrome profile if researching competitor authenticated experiences. This isolates cookies, prevents accidental cross-contamination, and lets you maintain separate login states for research vs. personal use.

Output Templating The default markdown output is comprehensive but generic. Post-process with your own templates — extract color sections for design tokens, component tables for Storybook documentation, breakpoint data for CSS custom properties. The structured markdown parses cleanly with standard tools.

Selective Re-execution Don't rerun full audits for minor updates. The skill's modular agent structure means you could theoretically invoke individual research phases by modifying the SKILL.md prompt. Fork the repository and customize agent instructions for your specific research priorities.

Visual Regression Baselines Store audit outputs in version control. Diff between audits to catch unintended design drift in your own products. The exact color values and measurements make precise regression detection possible — not just "something looks different" but "the primary blue shifted from #3B82F6 to #2563EB".

Comparison with Alternatives

The verdict: design-research occupies a unique position — more intelligent than raw scraping, more automated than manual analysis, more capable with authentication than headless alternatives. The tradeoff is token cost and experimental feature dependency. For professional design research where time matters more than marginal API costs, it's unmatched.

FAQ

Is design-research free to use? The skill itself is MIT-licensed and free. However, Claude Code requires Anthropic API access, and 10-agent audits consume significant tokens. Budget approximately $2-5 per comprehensive audit depending on site complexity and Claude model used.

Can I use this without Claude Code? No. The agent team orchestration depends on Claude Code's experimental infrastructure. The SKILL.md prompt is specifically formatted for Claude's instruction-following architecture. Porting to other LLM platforms would require substantial reimplementation.

What sites work best with design-research? Sites with multiple distinct page types and rich interactive elements yield the most valuable outputs. Single-page landing pages are overkill. Complex SaaS applications, e-commerce flows, and content platforms are ideal research targets.

How does it handle JavaScript-heavy SPAs? Agents interact with rendered DOM through your actual Chrome instance, so client-side rendering is fully supported. They wait for elements, execute interactions, and observe state changes — just as a human researcher would.

Is my browsing data safe during audits? Agents operate within your Chrome profile, so they access whatever you can access. The tool doesn't exfiltrate data beyond your local Claude session and specified output file. However, the --dangerously-skip-permissions flag means agents aren't sandboxed — review the SKILL.md to understand what actions agents are instructed to perform.

Can I customize the research agents? Absolutely. The skill is open-source — fork the repository, modify skills/design-research/SKILL.md to adjust agent instructions, add research dimensions, or change output formatting. Submit pull requests for improvements the community would value.

What if Chrome disconnects mid-audit? Run /chrome inside Claude to reestablish the extension connection. The audit doesn't automatically resume — you'll need to restart. For long audits on unstable connections, consider researching smaller page subsets.

Conclusion

Manual design research is a tax on creativity — hours of mechanical inspection that steal time from actual building. design-research eliminates this tax with surgical precision: 10 specialized agents, your authenticated browser, and a structured deliverable that transforms any website from mystery to blueprint.

The implications extend beyond convenience. When design intelligence becomes this accessible, the gap between appreciation and implementation collapses. You see something beautiful, you understand exactly how it's built, you build something equally refined. The cycle of design evolution accelerates.

Yes, it's experimental. Yes, token costs require awareness. But the capability — authenticated, parallel, AI-interpreted design research — is a glimpse of how frontend professionals will work in the near future. The manual alternative feels increasingly like farming with hand tools when tractors exist.

Star the repository. Install the skill. Point it at a site you admire. Watch 10 agents dissect beauty into buildable truth. Then tell me you could have done it faster alone — I dare you.

Your next great design doesn't start with a blank canvas. It starts with intelligence.