Build Your First Chrome Extension with Claude Code: A Step-by-Step Guide

Why Build a Chrome Extension?

Chrome extensions are powerful tools that can enhance your browsing experience. They can add features to websites, automate tasks, or provide helpful utilities. And with Claude Code, you can build one in an afternoon—even if you've never written a line of JavaScript.

In this guide, we're going to build ReadTime, a Chrome extension that estimates how long it takes to read any webpage. It will:

• Analyze the text content on any page
• Calculate reading time based on your reading speed
• Skip ads and navigation elements
• Display the estimate in a clean popup

By the end, you'll have a working extension you can use, share, or even publish to the Chrome Web Store.

---

What You'll Need

Before we start, make sure you have:

• Claude Code installed (if you haven't, check out our first app guide)
• Google Chrome browser
• A basic understanding of what you want the extension to do (we've got that covered!)

That's it. No Node.js, no build tools, no complex setup. Just Claude Code and Chrome.

---

Step 1: Start Your Project

Open Claude Code and create a new project folder. In your terminal, type:

mkdir readtime-extension
cd readtime-extension
claude

Once Claude Code is running, you'll see the welcome screen. This is where you'll communicate with Claude to build your extension.

Tell Claude what you want to build:

This is a new project. We're making a Google Chrome extension that estimates read time for a page and displays the time in the pinned extension. I want to be able to adjust my reading speed and let it skip ads and stuff I won't actually read, just the text of the article or webpage. Create a simple PRD as an md file to start this project.

Claude will create a Product Requirements Document (PRD) that outlines what we're building. This helps clarify the scope and features before we start coding.

Step 2: Create the Extension Structure

Chrome extensions have a specific structure. They need:

• A manifest.json file (tells Chrome what your extension does)
• HTML files for the popup UI
• JavaScript files for the logic
• CSS files for styling (optional, but makes it look good)

Ask Claude to create the basic structure:

Create the basic Chrome extension structure:
1. manifest.json with version 3
2. A popup.html file for the extension UI
3. A popup.js file for the main logic
4. A content.js file to analyze page content
5. Basic styling in popup.css

Make it a read time estimator that works on any webpage.

Claude will create all the necessary files. Let's look at what each one does:

manifest.json

This is the configuration file that tells Chrome about your extension:

{
  "manifest_version": 3,
  "name": "ReadTime",
  "version": "1.0.0",
  "description": "Estimate reading time for any webpage",
  "permissions": ["activeTab"],
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"]
  }]
}

popup.html

This is what users see when they click your extension icon. It should show the reading time and allow adjusting reading speed.

content.js

This script runs on every webpage and extracts the actual article text, filtering out ads, navigation, and other non-content elements.

popup.js

This handles the popup logic: calculating reading time, storing user preferences, and displaying results.

Step 3: Build the Content Analyzer

The hardest part of a read time extension is extracting just the article text from a page. Websites have navigation, ads, sidebars, footers—we need to ignore all of that.

Ask Claude to create a smart content extractor:

Create a content script that:
1. Finds the main article content on a page
2. Skips common non-content elements (nav, ads, footer, etc.)
3. Counts words in the actual article text
4. Sends the word count to the popup

Use semantic HTML5 elements like <article>, <main>, and common class names to identify content.

Here's what a basic content extractor looks like:

// content.js
function extractArticleText() {
  // Try to find the main article element
  const article = document.querySelector('article') || 
                  document.querySelector('[role="article"]') ||
                  document.querySelector('main');
  
  if (!article) {
    // Fallback: find the largest text container
    const paragraphs = document.querySelectorAll('p');
    let text = '';
    paragraphs.forEach(p => {
      text += p.textContent + ' ';
    });
    return text.trim();
  }
  
  // Remove unwanted elements
  const unwanted = article.querySelectorAll('nav, aside, footer, .ad, .advertisement, .sidebar');
  unwanted.forEach(el => el.remove());
  
  return article.textContent.trim();
}

// Count words
function countWords(text) {
  return text.split(/\s+/).filter(word => word.length > 0).length;
}

// Send to popup
const articleText = extractArticleText();
const wordCount = countWords(articleText);
chrome.runtime.sendMessage({ wordCount, text: articleText });

Step 4: Create the Popup Interface

Now let's build the UI that users see. Ask Claude:

Create a clean popup interface with:
1. Display area for read time (e.g., "5 min read")
2. Word count display
3. Reading speed slider (Slow: 200 WPM, Average: 300 WPM, Fast: 400 WPM)
4. Save the reading speed preference
5. Make it look modern and clean with Tailwind-like styling

The popup should look something like this when it's working:

Step 5: Calculate Reading Time

The math is simple: divide word count by words per minute. Ask Claude to implement this:

In popup.js, create a function that:
1. Gets the word count from the content script
2. Gets the user's reading speed preference (default: 300 WPM)
3. Calculates: readingTime = wordCount / readingSpeed
4. Formats it nicely (e.g., "5 min read" or "1.5 min read")
5. Updates the display when the page changes or speed changes

Step 6: Load the Extension in Chrome

Now for the exciting part—seeing your extension work! Here's how to load it:

1. Open Chrome and go to chrome://extensions
2. Enable "Developer mode" (toggle in the top right)
3. Click "Load unpacked"
4. Select your readtime-extension folder

Your extension should now appear in the extensions list! Pin it to your toolbar by clicking the puzzle piece icon and then the pin icon next to ReadTime.

Step 7: Test It Out

Navigate to any article or blog post (like this one!). Click your ReadTime extension icon. You should see:

• The estimated reading time
• The word count
• A slider to adjust your reading speed

Try adjusting the reading speed slider—the time should update immediately. The extension remembers your preference for next time.

Step 8: Handle Edge Cases

Not every webpage will work perfectly. Some pages don't have clear article content, or the extension might not load. Ask Claude to add error handling:

Add error handling for:
1. Pages where we can't find article content (show a helpful message)
2. Pages that haven't loaded yet (wait for page load)
3. Invalid word counts (show "Unable to analyze")
4. Make the UI show loading states

Step 9: Polish and Improve

Now that the basic functionality works, let's make it better. Ask Claude to:

• Add an icon for the extension (create a simple SVG or PNG)
• Improve the content extraction to handle more website layouts
• Add keyboard shortcuts (optional)
• Style it to match your brand or make it more visually appealing

What You've Built

Congratulations! You've just built a real Chrome extension that:

• ✅ Works on any webpage
• ✅ Extracts article content intelligently
• ✅ Calculates reading time accurately
• ✅ Lets users customize their reading speed
• ✅ Saves user preferences
• ✅ Has a clean, functional UI

This isn't a toy project—it's a real extension you can use every day. And you built it in an afternoon using Claude Code.

Next Steps

Want to take it further? Here are some ideas:

• Publish to Chrome Web Store: Share your extension with others
• Add more features: Track reading progress, estimate time for multiple articles, export reading lists
• Improve accuracy: Better content detection, handle different languages, account for images
• Add analytics: See which sites you read most, track your reading habits

The Bigger Picture

What you just did would have taken weeks to learn traditionally. You'd need to:

• Learn JavaScript
• Understand Chrome Extension APIs
• Figure out DOM manipulation
• Learn about message passing between scripts
• Understand browser storage APIs

With Claude Code, you described what you wanted, reviewed the code Claude wrote, and iterated until it worked. You're still the product manager—you're just not writing every line of code yourself.

Common Questions

"What if Claude makes a mistake?"

Tell it! Say something like: "The extension isn't calculating reading time correctly on blog posts. Debug the content.js file and fix the word counting logic." Claude will find the issue and fix it.

"Can I customize it more?"

Absolutely. Ask Claude to add any feature you want. Want it to work differently? Describe the change and Claude will update the code.

"How do I share this with friends?"

You can zip the extension folder and send it to them. They can load it the same way you did. Or, publish it to the Chrome Web Store (there's a process, but Claude can help you with that too).

---

Ready to build your own extension?

Open Claude Code, create a new project, and describe what you want to build. Claude will guide you through the process, just like it did here.

Remember: You're not learning to code. You're learning to build. And that's a completely different skill.

---

Nate Pinches
Built ReadTime extension in 2 hours using Claude Code
Still can't write a for-loop from memory