When you finally sit down to fix things, the bug reports are scattered across three places. Half of them are missing details, and the ones that do make it into GitHub were copied there by hand, sometimes with the visitor's email address still pasted into a public issue.

I wanted something better for my own projects, so I built it. IssueRelay gives any React website a small support widget where visitors can ask a question, report a bug, or suggest a feature. Every report is saved to your own database first. Then an AI model called Jev classifies it, a set of plain rules in code decides where it goes, and you review it in a private dashboard.

When you confirm that a report really is a bug, IssueRelay creates one clean GitHub issue for it, with the visitor's private details removed. When you later close that issue on GitHub, the support ticket closes too.

In this tutorial, you'll learn how the whole system works, from the widget in the browser to the webhook that keeps GitHub and the dashboard in sync. You'll also see how to deploy your own copy in about 15 minutes.

IssueRelay is open source on GitHub at andrewbaisden/issuerelay, the widget is published on npm as @issuerelay/widget, and it's running in production on my portfolio website right now.

I won't paste the whole codebase into this article. The repository has every file, and the setup guide walks through installation step by step. Instead, I'll show you the small pieces of code that carry the important ideas, explain what each one does, and share what I learned while building, testing, and deploying it.

Table of Contents

• Table of Contents

• Prerequisites

• How an AI Support System Can Help Any Website

• What We'll Build

• What Is Jev?

• The Tech Stack

• How a Report Travels Through the System

• How to Deploy Your Own IssueRelay

• Running It on a Real Website

• Testing It End to End (and What I Learned)

• How It Was Built: Phases and AI Assisted Development

• Publishing the Widget to npm

• What Is Next

• Conclusion

Prerequisites

To follow along and deploy your own copy, you should have:

• Working knowledge of React, Next.js, and TypeScript: the platform uses the Next.js App Router, and the widget is a React component.

• Node.js 24 and pnpm: installed if you want to run the project locally or use the command that creates your GitHub App.

• A GitHub account: plus the repository for the website or app where you want to install the widget. Confirmed bugs become issues there.

• A Vercel account: The free Hobby plan is enough. You'll add a Neon PostgreSQL database through Vercel's marketplace, and Neon also has a free plan.

• A TypeSafe account: at typesafe.ai for Jev, the AI model that triages reports. You need an API key from the TypeSafe console before any report can become a GitHub issue.

• A React website: where you can add a component. A Next.js site is the easiest place to start.

• Optional: a Resend account: if you want account emails such as password resets.

You don't need to be an AI expert to follow along. Jev is used through a small, typed SDK, and most of the interesting work is ordinary web engineering: databases, validation, authentication, and webhooks.

How an AI Support System Can Help Any Website

A support system sounds like something only big companies need, but the problem it solves shows up on almost every website:

• Portfolio sites get messages from recruiters, questions about projects, and reports about pages that break on a particular browser.

• SaaS products get bug reports mixed with billing questions and feature requests, and each one needs a different person or process.

• Documentation sites get "this example doesn't work" reports that are really bugs in the product.

• Open source projects get users who won't open a GitHub issue themselves but will happily click a button on the website.

• Client sites you built for someone else get feedback that the client forwards to you days later with no details.

A good system gives you one place where every report arrives, keeps each report safe even when other services fail, and sorts reports so you spend your time on the ones that matter.

The AI part helps with the sorting, but it should never be in charge. A model can be confidently wrong, and a public GitHub issue isn't something you want to create on a guess. So IssueRelay follows one simple rule throughout: AI recommends, a human confirms, and code enforces the rules.

What We'll Build

Here's the journey of a single report through IssueRelay:

A visitor opens the widget on your site and picks a topic:

They describe the problem and can optionally leave a name and email so you can follow up:

The widget sends the report to your IssueRelay platform, which saves it and replies with a support reference the visitor can quote later:

From there, the report becomes a ticket in your dashboard. Jev classifies it, you review it, and if it is a real bug, one click creates a GitHub issue in your repository.

Here's the full feature list:

• An embeddable widget: Built as a React component inside a Shadow DOM, so it needs no CSS setup and never clashes with your site's styles. It works in the Next.js App Router and under a strict Content Security Policy.

• Durable intake: Every report is stored in PostgreSQL before anything else runs, with protection against duplicates, per project rate limits, and a list of allowed site addresses.

• Bounded AI triage: Jev recommends a type and severity from the message alone.

• A private dashboard: With filters, classification history, and human review decisions that are stored separately from the AI's output.

• Careful GitHub escalation: Issues are created by a GitHub App only after an owner confirms a preview, and contact details never leave IssueRelay.

• Two way sync: Closing or reopening the issue on GitHub updates the ticket through signed webhooks.

• Self hosting: A Deploy button, a first run setup page, and a settings page make it possible to run your own copy without touching the database.

What Is Jev?

Jev is a model from TypeSafe that's built for what TypeSafe calls "System One" tasks: quick, bounded judgments as opposed to long, open ended writing.

Instead of asking a model to write a paragraph and then trying to parse it, you give Jev some state and a set of questions, and each question has a fixed list of possible answers. Jev picks an answer for each question and returns the probability it assigned to every option.

That shape is exactly what support triage needs. A ticket is a bug, a question, a feature request, a billing problem, or spam. It's low, medium, high, or critical. There's no text for the model to invent, no prompt injection that can make it write an issue title, and no free text to clean up afterwards. The output is a label and a number, and your code can check both.

It's also cheap and fast. At the time of writing, TypeSafe lists Jev at $42 per billion input tokens, and a support message is a few dozen tokens. The IssueRelay integration sends Jev only the visitor's message and the topic they picked. It never sends names, email addresses, ticket IDs, or anything else that identifies a person.

The Tech Stack

IssueRelay is built with a modern TypeScript stack, and it's the same stack I use for my own projects. If you've read my other articles, a lot of it will look familiar:

• Next.js 16 (App Router) and React 19 for the platform and the dashboard

• Strict TypeScript everywhere, with Zod checking every input that crosses a trust boundary: public API requests, environment variables, AI output, and GitHub webhook payloads

• PostgreSQL with Drizzle ORM and reviewed SQL migrations

• Better Auth for dashboard accounts

• The official TypeSafe SDK for Jev, and Octokit for the GitHub App

• Vitest, React Testing Library, and Playwright for tests, and Biome for linting and formatting

• pnpm workspaces to hold everything in one monorepo

• Vercel, Neon, and Resend in production

The monorepo is split into small packages, each with a strict job:

The boundaries matter more than they might look like they do. React components never talk to GitHub, Jev, or the database directly. Browser code never contains a secret. The AI package can't import the database.

Keeping those lines strict made the system much easier to test and to reason about, and it's the reason the widget can be published to npm without dragging any server code along with it.

How a Report Travels Through the System

Let's follow one report from the visitor's browser all the way to a closed GitHub issue.

Step 1: The Widget

The widget is a normal React component that you install from npm:

npm install @issuerelay/widget

Then you render it once, for example from a client component in your root layout:

"use client";

import {
  HttpSupportSubmissionClient,
  SupportWidget,
} from "@issuerelay/widget";

const submissionClient = new HttpSupportSubmissionClient({
  apiBaseUrl: "https://your-issuerelay.vercel.app",
});

export function Support() {
  return (
    <SupportWidget
      projectKey="pk_your_project_key"
      submissionClient={submissionClient}
      theme="system"
      position="bottom-right"
    />
  );
}

HttpSupportSubmissionClient is the part that talks to your platform. It posts each report to your IssueRelay API without cookies or credentials, and it gives every report a submission ID so that a retry after a network error doesn't create a second ticket.

SupportWidget is the button and panel your visitors see. The projectKey tells the platform which project the report belongs to. It's public identification, not a password, so it's safe to put in your site's code. The real protection is on the server, which only accepts reports from the site addresses you list for that project.

The "use client" line is there because the submission client is created in the browser. In the Next.js App Router, you wrap the widget in your own small client component like this and render that component from your layout.

Under the hood, the widget renders inside a Shadow DOM with its own bundled styles, so your site doesn't need Tailwind or a CSS import, and your styles can't accidentally restyle it.

You don't have to write this code by hand, either. IssueRelay's project settings page shows this exact snippet with your platform address and project key already filled in.

Step 2: Save First, Think Later

When the report reaches the API, the first thing IssueRelay does is save it. Not classify it, not send it anywhere, just store it in PostgreSQL inside a transaction.

This is the most important design decision in the whole system. AI providers have outages. GitHub has outages. If the platform called Jev before saving the report and Jev timed out, the visitor's message would be lost, and they would never know.

So the rule is simple: a report is accepted only after it's safely stored, and a failure in any later step can never erase it. If Jev is down, the ticket waits in the dashboard until you run triage again.

Before saving, the API checks a few things:

• The request body matches the shared Zod contract, so bad input is rejected with a clear error.

• The project key exists, and the request's origin is one of the project's allowed site addresses.

• The project is under its rate limit.

• The submission ID hasn't been used before. A repeated submission returns the original ticket reference instead of creating a duplicate.

Step 3: Triage with Jev

Once a ticket is stored, the triage service asks Jev to classify it. Here's the heart of the Jev adapter, from packages/ai/src/jev-classifier.ts (trimmed a little for space):

const response = await this.client.systemOne({
  state: {
    message: input.message,
    category_hint: input.categoryHint ?? null,
  },
  questions: {
    ticket_type: choice(
      "What kind of support ticket is this? The visitor-selected category hint is a weak signal, not ground truth: judge from the message content.",
      {
        question: "The visitor asks how something works or what something is.",
        bug: "Something is broken, errors, or behaves incorrectly.",
        feature_request: "The visitor requests new functionality or an improvement.",
        spam: "Unsolicited advertising, scams, or irrelevant bulk content.",
        // ...account, billing, feedback, and other
      },
    ),
    severity: choice("How urgent is this ticket?", {
      low: "Minor inconvenience, cosmetic issue, or general question.",
      medium: "Broken functionality with a workaround, or a routine request.",
      high: "Major functionality unavailable, no workaround, time-sensitive.",
      critical: "Security breach, data loss, privacy exposure, or billing harm.",
    }),
  },
});

systemOne is the TypeSafe SDK call for bounded questions. The state object is everything Jev is allowed to see: the message and the topic the visitor picked.

Notice what's missing. There's no name, no email, and no ticket ID, because none of them help with classification and all of them would be private data leaving your platform.

Each choice defines one question and its possible answers. The descriptions next to each label tell Jev what the label means. The ticket type question also tells Jev to treat the visitor's chosen topic as a weak hint, because people often pick "Report a bug" for a question, or "Ask a question" for something that's clearly broken.

What comes back isn't trusted automatically. The adapter validates the response with a Zod schema, checks that both answers are labels from the allowed lists, and uses the probability Jev gave to the chosen type label as the confidence score.

If that probability is missing or outside the range 0 to 1, the result is rejected, and the ticket stays in review instead of getting a made up number.

Step 4: Code Makes the Decisions

Jev recommends a type and a severity. It doesn't decide where a ticket goes or whether it becomes a GitHub issue. That job belongs to plain functions in packages/ai/src/policy.ts:

export function routeForType(type: TicketType): TicketRoute {
  switch (type) {
    case "bug":
      return "engineering";
    case "feature_request":
      return "product";
    case "spam":
      return "ignore";
    default:
      return "support";
  }
}

export function evaluateGitHubEscalation(input: {
  type: TicketType;
  route: TicketRoute;
  confidence: number;
}): EscalationEvaluation {
  const reasons: string[] = [];
  if (input.type !== "bug") reasons.push(`type is ${input.type}, not bug`);
  if (input.route !== "engineering") reasons.push(`route is ${input.route}, not engineering`);
  if (!(input.confidence >= GITHUB_ESCALATION_CONFIDENCE_THRESHOLD)) {
    reasons.push(`confidence ${input.confidence} is below ${GITHUB_ESCALATION_CONFIDENCE_THRESHOLD}`);
  }
  return { eligible: reasons.length === 0, reasons };
}

routeForType maps each ticket type to a queue. Bugs go to engineering, feature requests go to product, spam is quarantined, and everything else goes to support. Because this is a normal switch statement, you can read it, test it, and change it without touching the AI.

evaluateGitHubEscalation decides whether a ticket is even allowed to become a GitHub issue. It must be a bug, it must be in the engineering queue, and its confidence must be at least 0.9. Instead of returning a bare true or false, it collects the reasons a ticket failed, which the dashboard shows so you always know why the Create GitHub issue button is missing.

The 0.9 threshold lives in one configuration file with a comment that says it's an uncalibrated starting point, not a measured accuracy. I wanted that to be honest in the code: a model score of 0.99 doesn't mean the model is right 99 percent of the time.

Step 5: Human Review in the Dashboard

Every ticket lands in a private dashboard. The projects page shows how many tickets are in each state:

Each project has a ticket list with filters for status, route, type, severity, and reference:

Opening a ticket shows the visitor's report, the current AI classification, the full classification history, and a timeline of everything that happened. You can run triage again, resolve the ticket, or record a review decision that changes the route, the status, or the GitHub recommendation.

One detail I care about: human decisions are stored in their own table, with the author and a required reason. The AI's history is never rewritten. If you override Jev, you can still see exactly what Jev said and when, which is important when you want to know how well the model is really doing.

The dashboard is protected by Better Auth, and every read and write is scoped to a workspace. Mutations require a same origin request, and only workspace owners can publish to GitHub.

Step 6: From Bug Report to GitHub Issue

When a ticket passes the policy, the dashboard shows a preview of the exact issue that will be created:

Look closely at that screenshot. The visitor left their name and email, and both are visible in the dashboard above, but neither appears anywhere in the issue preview.

That's not a coincidence. Before any issue is created, the report passes through a privacy gate in packages/github/src/privacy.ts that looks for email addresses, phone numbers, card numbers, private keys, API tokens, JSON web tokens, and password assignments. It also checks the report against the contact details the visitor submitted, so "Hi, Sam Visitor here" can't leak a name into a public issue. If anything is found, the preview is blocked and nothing is published.

When you click Create GitHub issue, a few more safeguards run:

• A GitHub App, not a personal token: The App is installed only on the repositories you choose, with permission to write issues and read metadata, and nothing else.

• Claim first, then create: The ticket is marked as creating in the database before GitHub is called, so two clicks can never create two issues.

• A hidden marker: Each issue body ends with an opaque HTML comment tied to the ticket. If a request times out and the result is unknown, IssueRelay searches the repository for that exact marker from its own App before it ever tries again. It never blindly retries an issue it might already have created.

Here's a real issue that IssueRelay created on my portfolio's public repository from a visitor report. It was created by the App's bot, labelled bug, and contains the report and the AI's classification, but no contact details:

Step 7: Keeping GitHub and the Dashboard in Sync

The last piece closes the loop. When you close the issue on GitHub, GitHub sends a webhook to IssueRelay, and the ticket moves to resolved. Reopen the issue and the ticket goes back into the queue.

A webhook endpoint is public by definition, so the first thing it does is prove the request really came from GitHub. This is the verification function from packages/github/src/webhook-auth.ts:

export function verifyWebhookSignature(input: {
  secret: string;
  rawBody: Uint8Array;
  signatureHeader: string | null;
}): boolean {
  const { secret, rawBody, signatureHeader } = input;
  if (!secret || !signatureHeader?.startsWith("sha256=")) {
    return false;
  }
  const hex = signatureHeader.slice("sha256=".length);
  if (!/^[0-9a-f]{64}$/.test(hex)) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const actual = Buffer.from(hex, "hex");
  if (expected.length !== actual.length) return false;
  return timingSafeEqual(expected, actual);
}

GitHub signs every delivery with a secret that only GitHub and your platform know, and sends the signature in the X-Hub-Signature-256 header. This function computes its own HMAC SHA256 signature over the raw request bytes and compares the two.

Two details are easy to get wrong. First, the signature has to be computed over the exact bytes GitHub sent, before any JSON parsing, because parsing and reformatting would change the bytes. Second, the comparison uses timingSafeEqual, which takes the same amount of time whether the first byte or the last byte differs, so an attacker can't guess the signature one character at a time by measuring response times. The function also returns false for every kind of failure without saying which one, so it leaks nothing.

After the signature check, IssueRelay stores each delivery ID, so a repeated delivery is ignored. It updates only an issue that belongs to the matching App installation and repository, and it applies events in the order they happened on GitHub, not the order they arrived.

How to Deploy Your Own IssueRelay

You can run your own IssueRelay on Vercel and Neon in about 15 minutes. The complete walkthrough, including troubleshooting, is in docs/SELF_HOSTING.md. Here's the short version.

Step 1: Deploy

The recommended path is the Deploy with Vercel button in the README. It copies the repository into your GitHub account, adds a Neon database, and asks for three random secrets.

The first build fails on purpose because Vercel's clone screen has no Root Directory setting, so you set Root Directory to apps/web in the project settings and redeploy. The production build then creates every database table for you.

The guide also describes a Fork and Import path that makes future updates a single click, but that path hasn't been tested end to end yet.

Step 2: Run the Setup Page

Open /setup on your new site. It only works while the database has no accounts and you enter the SETUP_TOKEN you created during the deploy, so nobody who finds your URL first can claim your platform. It creates your owner account and your first project, then shows your widget key and the ready to paste widget code.

The site address field starts with http://localhost:3000, which is where a Next.js app runs on your computer. Add your live address too, such as https://my-site.vercel.app or your own domain. If you forget, the widget will politely tell visitors "We couldn't send your message," so this is the first thing to check when a report doesn't arrive.

Step 3: Create the GitHub App

Setting up a GitHub App by hand has a few easy mistakes in it. The worst one is forgetting to subscribe to the Issues event, which I did myself during testing. So IssueRelay includes a command that creates the App for you from a manifest:

pnpm github:create-app --platform https://your-issuerelay.vercel.app

This opens GitHub in your browser with everything already filled in: a private App with permission to write issues and read metadata, subscribed to the Issues event, with its webhook pointing at your platform.

You click Create GitHub App, GitHub redirects back to a temporary local server started by the command, and the command writes the App ID, private key, and webhook secret to a file that git ignores. It never prints them in your terminal. The terminal then lists the next setup phase.

Step 4: Add Your Keys and Redeploy

Add the three GitHub App values and your TYPESAFE_API_KEY to your Vercel project's environment variables, then redeploy. Jev is required for GitHub issues: without it, reports still arrive in your dashboard, but none can become an issue.

Step 5: Connect Your Repository

Install the App on the repository of the website where the widget will live, then open your project's Settings page in the dashboard and connect it. The page asks GitHub which installation and repository ID belong to that name, so a typo can't link the wrong repository.

Step 6: Install the Widget

Install the widget on your site with the code from the settings page, and send your first report.

To keep your copy up to date later, pull changes from the main repository. The guide covers the one time step needed for copies made with the Deploy button, because those copies are not GitHub forks.

Running It on a Real Website

A demo is one thing, but I wanted to use IssueRelay for real, so the widget now runs on my portfolio at andrewbaisden.com:

The website design will likely change, so if you're reading this article in the future, previous builds can be found on my GitHub.

Installing it taught me a few things. My portfolio was still on React 18 for its tests, while the App Router was already rendering with React 19. So I upgraded it to React 19 first and made sure every existing test passed before adding the widget. The widget matches the site's light and dark themes, sits in the bottom right corner, and has its own unit test and browser test in the portfolio repository.

Then I tested it like a visitor would. I sent three real reports from the live site: a question, a bug, and a feature request. Jev classified all three the way I intended, with scores between 0.95 and 1.00, and the policy routed them to support, engineering, and product. The bug became issue #3 in my public portfolio repository, which is the issue shown in the screenshot earlier. I had included my name and email with that report, and neither appears in the public issue.

Testing It End to End (and What I Learned)

I didn't want a project that only worked on my machine, so testing was part of every phase instead of something saved for the end.

The test suite has several layers:

• Unit tests for the widget, the API contract, the AI policy, the privacy gate, the setup page, and more. There are 180 of them, and none need a database.

• Database integration tests that run against a separate PostgreSQL test database, including concurrency tests that prove two clicks can't create two GitHub issues.

• Browser tests with Playwright that start their own servers on separate ports, with a separate database that is recreated for every run, so a test can never touch real data. One of those servers runs against an empty database to test the first run setup page.

• A package check that builds the exact npm tarball and installs it into a Vite app with a strict Content Security Policy and into a Next.js app, both outside the monorepo, then submits a report in each.

• A live journey test with 20 checks against a real GitHub App and a throwaway repository: submit a report, triage it, preview it, create the issue, check that no private data was published, close the issue on GitHub and wait for the webhook, reopen it, and check the timeline.

I ran that live journey three times: first against my local machine through a tunnel, then against production, and finally against a completely fresh copy that I deployed by following only the setup guide. All three passed 20 out of 20.

More interesting than the passes, though, are the problems each stage uncovered:

• The Issues event is easy to forget: The first time I created a GitHub App by hand, it had no event subscriptions, so GitHub never told IssueRelay when issues closed. That mistake is why the create-app command exists.

• Visitors mention their own names: A report like "Sarah here, the page is broken" from a visitor named Sarah would have put her name in a public issue. The privacy gate now compares every report against the contact details that came with it.

• Zod and strict CSP don't mix in the browser: Zod 4 briefly tests whether it can use new Function, and sites with a strict Content Security Policy report that as a violation. I removed Zod from the widget and wrote small validation checks instead, with a test that proves they agree with the server's Zod schemas on 270 form combinations.

• Vercel's clone flow has no Root Directory option, and Vercel picks the framework only once: My fresh deploy failed twice: once because Vercel built the repository root, and once because the framework was still set to "Other." The repository now pins Next.js in vercel.json, and the guide warns about the first failure.

• Deploy button copies aren't forks: A plain git pull from the main repository refuses to merge, so the guide now has a one time command to connect a copy to the main repository.

• GitHub issues need Jev: I originally listed Jev as optional. A careful review of the guide showed that without it, no real report can reach the confidence threshold. The guide and the settings page now say so clearly.

• Log noise matters: Every database connection logged an SSL warning at error level, which made a healthy deployment look broken. The fix was to spell out the SSL mode the driver was already using, so the warning disappeared while the certificate checks stayed exactly the same.

The lesson that stuck with me most: deploying from your own documentation, word for word, finds bugs that no test will. Every one of the deployment problems above was invisible to the automated tests and obvious the moment a real person followed the guide.

How It Was Built: Phases and AI Assisted Development

IssueRelay was built in small phases, and each phase ended with a written handoff before the next one could start:

My Developer Setup

I did most of the work in the terminal. My setup is:

• Ghostty as my terminal, running Claude Code, Codex, and OpenCode

• Cursor as my editor

• The native desktop apps for ChatGPT, Claude, and OpenCode

My main model for building IssueRelay was Claude Opus 5.5 in Claude Code. For code reviews and for checking a phase before I signed it off, I used other models, including GPT-6 Sol and Grok, along with various other frontier and free models.

A second model reading the same code with fresh eyes caught real problems. For example, a Grok review of Phases 7 and 8 raised 15 findings. Seven were valid, including a race in claiming issue creation and issue markers that could be guessed, and all seven were fixed before I moved on. Three more were partly valid and five were deferred with written reasons.

Anthropic's newly released Sonnet 5.5 and OpenAI's GPT-6.1 Sol weren't used in this project.

How Better Prompts Improved the Codebase

The biggest improvement in quality didn't come from a smarter model. It came from giving the model better instructions and a better structure to work in. Here is what worked:

• One phase at a time: Each prompt asked for exactly one phase with a clear outcome, and the AI wasn't allowed to start the next phase until I approved it. Small, reviewable changes were much easier to check than one giant feature.

• A plan before any code: For bigger phases I asked for a plan first ("Create a plan and then go ahead with it once I approve it"). Reading a plan takes two minutes. Unpicking a wrong implementation takes an afternoon.

• Rules that live in the repository: An AGENTS.md file holds the project's rules, such as "persist an accepted ticket before external AI or GitHub calls," "never publish contact data to GitHub," and "do not blindly retry an ambiguous GitHub issue creation." Every AI session reads it, so the rules don't depend on me remembering to repeat them.

• Honest reporting: The instructions say never to report an unrun check as passing, and every handoff records the commands that were run and their real results, including failures.

• Clear conditions for committing: Prompts like "commit and push when tests pass and there are no other issues" meant the full test suite ran before anything reached the main branch.

• Asking for proof, not promises: Instead of asking "does self hosting work?", I asked the AI to verify it by following the guide on a fresh deployment. That single request uncovered seven documentation and configuration problems.

• Feeding back real use: When I deployed a test site myself and wrote down everything that confused me, those notes went straight back into the guide, the setup page, and the settings page.

Publishing the Widget to npm

The widget is the only part of IssueRelay that is published, as @issuerelay/widget. Everything else stays private inside the monorepo.

I didn't want to publish something that only worked inside my own workspace, so the release check builds the exact tarball that npm will receive and inspects it.

It must contain only five files. It must not reference private packages, Node built ins, environment variables, or anything that looks like a key. It must then install and work in two brand new apps outside the repository, one of them under a strict Content Security Policy, with zero policy violations.

Releases are published from GitHub Actions with npm trusted publishing and provenance, so there is no long lived npm token to leak.

The result is a package of about 10 KB compressed that needs no CSS setup and depends only on React and React Hook Form. The widget README documents every prop.

What Is Next

IssueRelay is complete for self hosting, and I'm using it every day on my portfolio. Some things I would like to explore next:

• A hosted version of IssueRelay, so you could sign up and add the widget without deploying anything yourself

• Testing the Fork and Import path end to end so it can become the recommended way to deploy

• Ideas from the roadmap, such as detecting duplicate reports, linking several reports to one issue, notifications, and syncing GitHub comments

Conclusion

In this tutorial, you saw how to build an AI support system that turns scattered website feedback into reviewed tickets and routes confirmed bugs to GitHub. Along the way, you learned how to:

• Build an embeddable React widget that works on any site without CSS setup or style clashes

• Save every report before calling any external service, so provider outages never lose data

• Use Jev for bounded, validated classification that returns labels and probabilities instead of free text

• Keep routing and publishing decisions in plain, testable code, with a human in the loop

• Create GitHub issues safely with a GitHub App, a privacy gate, and a marker that prevents duplicates

• Keep GitHub and your dashboard in sync with signed, verified webhooks

• Deploy your own copy on Vercel and Neon, and test it end to end, including against your own documentation

The best way to understand IssueRelay is to try it. You can explore the code on GitHub, deploy your own copy with the self hosting guide, and add the widget to your site with npm install @issuerelay/widget from npm. If it helps you, a star on the repository is always appreciated.

In the pre-LLM era, you might spend days writing a few lines of code. This meant your context on any project grew incrementally with your contribution. You only had to review and get acquainted with new code if you joined a new team or got into a new job.

But today, one prompt can generate thousands of lines of code across 100s of files in minutes. At that scale, the traditional format of reviewing code begins to collapse, and you spend more time reviewing code than actually writing it.

For instance, if you open a large TypeScript project and want to answer a seemingly simple question such as:

"What calls this function?"

you'll probably start by searching through files. You might use your editor's "Find References" feature. You might jump between definitions. You might search for imports, exports, and function names.

But there's another way to think about the problem. Instead of treating a codebase as a collection of files, we can model it as a graph.

Functions become nodes and calls become edges.

Once code is represented as a graph, questions such as "what calls this function?" or "what does this function eventually call?" become graph traversal problems.

In this tutorial, we'll build the core of a code graph using TypeScript and VS Code's built-in language APIs. We won't write our own TypeScript parser. Instead, we'll use the semantic information VS Code and the installed language extension already provide. The result will be a graph containing files, functions, methods, and call relationships that can be displayed in a VS Code Webview.

Table of Contents

• What We're Building

  • Prerequisites

• 1. Understanding the VS Code Language APIs

• 2. Setting Up the Extension

• 3. Designing the Graph Data Model

  • Stable Symbol IDs

• 4. Finding Functions and Methods

• 5. Finding the Symbol at a Position

• 6. Resolving the Call Hierarchy

• 7. Building a Symbol Registry

• 8. Traversing the Graph with BFS

• 9. Handling Cycles

• 10. Bounding the Graph

• 11. Filtering Files

• 12. Why Some Edges Silently Disappear

  • 1. It stores plain data, not live items.

  • 2. It tracks the age of each prepared item.

  • 3. It retries suspicious empty results.

• 13. Connecting the Graph to a Webview

• 14. Testing the Graph Builder

• 15. The Limitations of a Code Graph

• Conclusion

What We're Building

We’ll build a small code-graph engine that uses VS Code’s Call Hierarchy API to discover relationships between functions and methods, then traverses those relationships across multiple hops. Along the way, we’ll handle concurrency, stale language-tooling references, caching, and duplicate traversal so the graph remains reliable and efficient.

Prerequisites

Before following along, you should be comfortable with:

• TypeScript and basic asynchronous programming with async/await

• Any VS Code compartible code, VS Code extension APIs, and vscode.commands.executeCommand

• Basic graph concepts such as nodes, edges, and Breadth-First Search (BFS)

• Working with maps, arrays, and generic functions in TypeScript

Let's go!

Suppose we have the following code:

function checkout() {
  processPayment();
}

function processPayment() {
  chargeCard();
}

function chargeCard() {
  saveTransaction();
}

function saveTransaction() {
  // persist transaction
}

We want to transform the source code into a graph. For a real codebase, the graph may span multiple files:

The implementation has two main parts. The extension host uses VS Code's language APIs to discover the graph. The Webview displays the resulting graph. The interesting part of this architecture is the graph builder.

1. Understanding the VS Code Language APIs

VS Code already exposes several commands that extensions can use to query language intelligence. For this project, four are particularly useful:

These APIs sit above the language-specific implementation. For TypeScript and JavaScript, the TypeScript language service provides the underlying information. Other languages expose similar capabilities through their own language extensions and language servers, such as gopls for Go, rust-analyser for Rust, and Pyright or Pylance for Python.

This is particularly important because we don't need to build a separate parser and call graph engine for every language. If a language extension provides document symbols and call hierarchy support through VS Code, the same graph-building architecture can consume that information directly.

An AST can tell you that a function contains a call expression. It doesn't automatically tell you which function that call refers to across imports, files, modules, classes, aliases, and other language constructs.

The language server already performs much of that semantic work. So instead of building another parser and symbol resolver, we can ask VS Code for the information it already knows.

2. Setting Up the Extension

Our package.json declares a command:

{
  "main": "./out/extension.js",
  "engines": {
    "vscode": "^1.85.0"
  },
  "activationEvents": [],
  "contributes": {
    "commands": [
      {
        "command": "codeGraphView.open",
        "title": "Code Graph: Open Graph for Active File",
        "icon": "$(type-hierarchy)"
      }
    ],
    "menus": {
      "editor/title": [
        {
          "command": "codeGraphView.open",
          "group": "navigation",
          "when": "resourceLangId == typescript"
        }
      ]
    }
  },
  "dependencies": {
    "elkjs": "^0.9.3"
  }
}

The extension host and Webview run in different environments, so they're bundled separately. A simplified esbuild configuration would look like this:

const extensionConfig = {
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'out/extension.js',
  external: ['vscode'],
  format: 'cjs',
  platform: 'node',
};

const webviewConfig = {
  entryPoints: ['webview/main.ts'],
  bundle: true,
  outfile: 'out/webview/main.js',
  format: 'iife',
  platform: 'browser',
};

The extension code runs in Node, while the Webview code runs in a browser environment.

3. Designing the Graph Data Model

Before calling the language APIs, we need to decide what our graph looks like. A useful model is:

export interface SymbolRow {
  id: string;
  name: string;
  kind: 'function' | 'method';
  line: number;
  character: number;
}

export interface FileNode {
  id: string;
  label: string;
  file: string;
  symbols: SymbolRow[];
}

export interface CallEdge {
  id: string;
  source: string;
  target: string;
}

export interface GraphData {
  rootFileId: string;
  rootSymbolId?: string;
  roots: string[];
  files: FileNode[];
  edges: CallEdge[];
  truncated: boolean;
}

There are two important concepts.

1. A FileNode contains the functions or methods belonging to a file.

2. A CallEdge represents a relationship between two symbols.

We keep the edge direction consistent:

caller → callee

So if checkout() calls processPayment(), the graph always contains:

checkout → processPayment

even if we discovered that relationship while asking for incoming calls.

Stable Symbol IDs

Function names aren't unique. A project can easily contain:

// users.ts
function save() {}

and:

// payments.ts
function save() {}

We therefore need an identifier based on the symbol's location.

function idOf(
  uri: vscode.Uri,
  pos: vscode.Position
): string {
  return `${uri.toString()}#${pos.line}:${pos.character}`;
}

For call hierarchy items, we use their selectionRange:

function itemId(
  item: vscode.CallHierarchyItem
): string {
  return idOf(
    item.uri,
    item.selectionRange.start
  );
}

Using selectionRange is useful because it identifies the symbol's name rather than the entire body or declaration range. This stable ID becomes the foundation for deduplication. If the same function is discovered from several paths through the graph, we can recognise that all discoveries refer to the same node.

4. Finding Functions and Methods

The first step in building the graph is discovering the symbols in the active file. VS Code exposes document symbols through:

vscode.executeDocumentSymbolProvider

We can call it like this:

/*
 * Get all symbols in a document using VS Code's
 * built-in language service instead of parsing the code ourselves. This was we can get the methods, functions, variables within a document
 */
async function getDocumentSymbols(
  uri: vscode.Uri
): Promise<vscode.DocumentSymbol[]> {

  /*
   * `vscode.executeDocumentSymbolProvider` delegates the analysis
   * to the language provider registered for the document's language.
   */

  const result =
    await vscode.commands.executeCommand<
      vscode.DocumentSymbol[] | undefined
    >(
      'vscode.executeDocumentSymbolProvider',
      uri
    );

  // Return an empty list if no symbols are found.
  return result ?? [];
}

The returned symbols form a hierarchy. For example:

We need to walk that hierarchy and collect symbols that could represent callable code.

// Check whether a symbol can be treated as a callable node.
const isCallableKind = (
  kind: vscode.SymbolKind,
  includeConstructors: boolean
) =>
  kind === vscode.SymbolKind.Function ||
  kind === vscode.SymbolKind.Method ||
  (
    includeConstructors &&
    kind === vscode.SymbolKind.Constructor
  );

We can recursively inspect the symbol tree:

  // Recursively collect functions, methods, and variables from a symbol tree
function collectCandidates(
  symbols: vscode.DocumentSymbol[],
  isCallable: (
    kind: vscode.SymbolKind
  ) => boolean,
  out: vscode.DocumentSymbol[] = []
) {
  for (const symbol of symbols) {
    if (
      isCallable(symbol.kind) ||
      symbol.kind === vscode.SymbolKind.Variable
    ) {
      out.push(symbol);
    } else if (
      symbol.children.length
    ) {
      collectCandidates(
        symbol.children,
        isCallable,
        out
      );
    }
  }
  return out;
}

Variables are worth considering because functions assigned to variables can be reported differently by language tooling. For example:

const handler = () => {
  // ...
};

The symbol may be reported as a variable even though it participates in the call hierarchy.

5. Finding the Symbol at a Position

When the user opens the graph for a particular method, we need to determine which symbol contains the cursor position. Because document symbols are hierarchical, we can recursively find the deepest symbol containing the position.

// Find the most specific symbol containing a given position.
function symbolAt(
  symbols: vscode.DocumentSymbol[],
  position: vscode.Position
) {
  for (const symbol of symbols) {
    if (symbol.range.contains(position)) {
      return (
        symbolAt(
          symbol.children,
          position
        ) ?? symbol
      );
    }
  }
  return undefined;
}

This gives us the bridge between the editor and the graph. The user selects a location in the source file. We resolve that location to a symbol. Then we resolve that symbol into a call hierarchy item.

6. Resolving the Call Hierarchy

The call hierarchy API works in two stages. First:

position → CallHierarchyItem

Then:

CallHierarchyItem → incoming/outgoing calls

We can prepare the item like this:

async function prepare(
  uri: vscode.Uri,
  position: vscode.Position
) {
  // VS Code's language tooling already knows how to resolve
  // symbols in a source file.
  // So we can use it to prepare a call hierarchy for the symbol at this location.
  const items =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyItem[] | undefined
    >(
      'vscode.prepareCallHierarchy',
      uri,
      position
    );

  // The command returns an array of hierarchy items. In our case,
  // we are interested in the symbol directly under the cursor,
  // so we use the first result.
  // Optional chaining also handles the case where no symbol
  // could be resolved at the given position.
  return items?.[0];
}

Once we have the item, we can ask for callers:

async function callers(
  item: vscode.CallHierarchyItem
) {
  // Ask VS Code for all symbols that call this item.
  const calls =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyIncomingCall[] | undefined
    >(
      'vscode.provideIncomingCalls',
      item
    );

  // Return the calling symbols, defaulting to an empty list when none are found.
  return (
    calls ?? []
  ).map(call => call.from);
}

Or callees:

async function callees(
  item: vscode.CallHierarchyItem
) {
  // Ask VS Code for all symbols called by this item.
  const calls =
    await vscode.commands.executeCommand<
      vscode.CallHierarchyOutgoingCall[] | undefined
    >(
      'vscode.provideOutgoingCalls',
      item
    );

  // Return the called symbols, defaulting to an empty list when none are found.
  return (
    calls ?? []
  ).map(call => call.to);
}

If we have:

and we ask for incoming calls to processPayment, the language API gives us:

checkout
retryPayment

We then normalise those results into:

checkout → processPayment
retryPayment → processPayment

The same graph structure can therefore represent both incoming and outgoing traversal.

7. Building a Symbol Registry

As we crawl the graph, the same symbol can appear repeatedly. Consider:

We should create one node forC, not three. A registry provides that deduplication layer.

class Registry {
  // Keep files and their symbols separately so they can be reused across the graph.
  private readonly files =
    new Map<string, FileNode>();

  // Store symbols by ID for fast lookup and duplicate detection.
  private readonly rows =
    new Map<string, SymbolRow>();

  get size() {
    return this.rows.size;
  }

  has(id: string) {
    return this.rows.has(id);
  }

  register(
    uri: vscode.Uri,
    name: string,
    kind: vscode.SymbolKind,
    position: vscode.Position
  ): string {
    // Generate a stable ID from the file and symbol position.
    const id =
      idOf(uri, position);

    // Avoid registering the same symbol more than once.
    if (this.rows.has(id)) {
      return id;
    }

    const fileId =
      uri.toString();

    let file =
      this.files.get(fileId);

    // Create the file entry the first time we encounter it.
    if (!file) {
      file = {
        id: fileId,
        label:
          vscode.workspace
            .asRelativePath(uri),
        file: uri.fsPath,
        symbols: [],
      };

      this.files.set(
        fileId,
        file
      );
    }

    // Normalize VS Code's symbol kind into the graph's simpler representation.
    const row: SymbolRow = {
      id,
      name,
      kind:
        kind ===
        vscode.SymbolKind.Method
          ? 'method'
          : 'function',
      line: position.line,
      character:
        position.character,
    };

    // Store the symbol globally and under its containing file.
    this.rows.set(id, row);
    file.symbols.push(row);

    return id;
  }
}Now the graph builder can repeatedly register symbols without worrying about duplicates.

8. Traversing the Graph with BFS

A single call hierarchy lookup gives us one hop. A useful code graph needs multiple hops. A lookup from A() might tell us that it calls B(), but it tells us nothing about what B() calls next.

To build a useful graph, we repeatedly follow these relationships: A → B → C → D. Each lookup expands the graph by another level, which is why we need a traversal strategy such as BFS to explore multiple hops in an efficient way.

For example:

// Assuming a graph with 4 hops
A --> B --> C --> D --> E

If we start from A and request a depth of three (3 hops), we want:

Depth 0: A
Depth 1: B
Depth 2: C
Depth 3: D

Breadth-first search (BFS) is a natural fit because the graph is explicitly organised around hop depth. The traversal maintains a frontier:

current frontier
      ↓
discover neighbors
      ↓
next frontier
      ↓
discover neighbors

A basic implementation looks like this:

const walk = async (
  start: Handle,
  direction: 'incoming' | 'outgoing',
  limit: number
) => {
  // Traverse the call graph one level at a time, starting from the given symbol.
  let frontier: Handle[] = [start];

  for (
    let depth = 0;
    depth < limit &&
    frontier.length > 0;
    depth++
  ) {
    // Resolve the next level in parallel, limiting concurrency to six lookups.
    const results =
      await mapLimit(
        frontier,
        6,
        handle =>
          oneHop(
            handle,
            direction
          )
      );

    const next: Handle[] = [];

    frontier.forEach(
      (handle, index) => {
        for (
          const other
            of results[index]
        ) {
          // Register newly discovered symbols before adding their relationships.
          if (
            !registry.has(
              other.node.id
            )
          ) {
            registry.register(
              other.node.uri,
              other.node.name,
              other.node.kind,
              other.node.pos
            );
          }

          // Preserve the direction of the call relationship in the graph.
          if (
            direction === 'outgoing'
          ) {
            addEdge(
              handle.node.id,
              other.node.id
            );
          } else {
            addEdge(
              other.node.id,
              handle.node.id
            );
          }

          next.push(other);
        }
      }
    );

    // Continue the traversal from the symbols discovered at this depth.
    frontier = next;
  }
};

The mapLimit helper keeps the number of concurrent language-server requests under control:

async function mapLimit<T, R>(
  items: T[],
  limit: number,
  fn: (item: T) => Promise<R>
): Promise<R[]> {
  // Run at most `limit` async operations at the same time.
  const results =
    new Array<R>(items.length);

  let next = 0;

  // Create workers that share the next available item.
  const workers =
    Array.from(
      {
        length:
          Math.min(
            limit,
            items.length
          ),
      },
      async () => {
        while (
          next < items.length
        ) {
          const index = next++;

          results[index] =
            await fn(
              items[index]
            );
        }
      }
    );
  await Promise.all(workers);
  return results;
}

The key distinction is that BFS is just local computation, while resolving a symbol often requires asking VS Code's language tooling to do real work.

For each symbol we visit, Code Graph View may need to query the language service for its incoming or outgoing calls. Those lookups can involve parsing source files, resolving symbols, and communicating with the language server. As the graph grows, the number of these requests grows with it.

So even though the traversal itself is simple, doing those lookups sequentially can make the whole process much slower. mapLimit addresses this by allowing several independent language-tooling requests to run concurrently, while still putting a cap on concurrency so that we don't overwhelm the language service.

9. Handling Cycles

Real code isn't a tree. It's a graph. That means cycles are normal.

For example:

A naïve recursive traversal could continue indefinitely. We therefore need to track what we've already explored. But there's a subtle detail. A simple:

Set<string>

isn't always enough if the same node can be reached at different depths. Instead, we can store how much traversal depth remains when we explore a node.

const explored =
  new Map<string, number>();

Then:

// Track the deepest remaining traversal already performed for this node.
const key =
  `${direction}:${node.id}`;
if (
  (explored.get(key) ?? -1)
  < remainingDepth
) {
  // Revisit only when this traversal can explore deeper than before.
  explored.set(
    key,
    remainingDepth
  );
  next.push(node);
}

This means that if we previously reached a node with one hop remaining, but later discover it with three hops remaining, we're allowed to explore it again. That's more precise than treating the node as "visited".

10. Bounding the Graph

A graph can grow extremely quickly. A highly connected function might have dozens of callers. Those callers may each have dozens of callers of their own. For that reason, the graph builder should have explicit limits.

For example:

const MAX_SYMBOLS = 400;
const MAX_CALLS_PER_SYMBOL = 50;
const HOP_CONCURRENCY = 6;

If the graph reaches a limit, we don't want to pretend that the graph is complete. Instead:

let truncated = false;

and:

if (
  registry.size >=
  MAX_SYMBOLS
) {
  truncated = true;
  continue;
}

The resulting GraphData can then tell the UI:

This graph was truncated.

This is better than allowing an unexpectedly large codebase to make the extension appear frozen.

11. Filtering Files

The language server may return relationships into files that aren't part of the application we're exploring. These could be build files or outputs that are created by dependency installations or language-specific build/runtime actions. For example, a TypeScript project can lead into:

node_modules

A Python project might lead into:

site-packages

We can filter those paths before adding them to the graph.

const DEPENDENCY_DIRS =
  /\/(node_modules|vendor|target|\.venv|venv|site-packages|__pycache__|build|obj|\.dart_tool)\//;

function isWorkspaceFile(
  uri: vscode.Uri
): boolean {
  if (
    uri.scheme !== 'file' ||
    DEPENDENCY_DIRS.test(uri.path)
  ) {
    return false;
  }
  return !!vscode.workspace
    .getWorkspaceFolder(uri);
}

This keeps the graph focused on the user's workspace. It also demonstrates an important distinction between language intelligence and application behaviour. The language server tells us what it can resolve. Our graph builder decides what should become part of the graph.

12. Why Some Edges Silently Disappear

On a large graph, some functions that clearly call each other can end up with no connection, and nothing reports an error. The problem is that a CallHierarchyItem is tied to language-service state. If that state becomes stale, asking for its callers or callees can return an empty array. From the graph builder's perspective, that looks exactly like a function with no callers.

In the VS Code implementation, call hierarchy sessions are kept for a limited number of recent requests. Our crawler can also have several lookups in flight at once, so older items can become unusable while the graph is being traversed. The graph builder deals with this in three ways.

1. It stores plain data, not live items.

Each function is represented by a NodeRef containing its ID, URI, name, kind, and position. One-hop results are also cached as NodeRefs. This gives us enough information to recreate a call hierarchy item when necessary.

interface NodeRef {
  id: string;
  uri: vscode.Uri;
  name: string;
  kind: vscode.SymbolKind;
  pos: vscode.Position;
}

2. It tracks the age of each prepared item.

A global epoch counter increases whenever a new call hierarchy item is prepared. Each handle records the epoch at which its item was created. If an item becomes sufficiently old, the crawler prepares a fresh one from the stored NodeRef.

3. It retries suspicious empty results.

A trimmed version of oneHop looks like this:

const SESSION_WINDOW = 7;

// Refresh stale language-tooling references and retry once if necessary.
for (let attempt = 0; attempt < 2; attempt++) {
  const stale =
    !current.item ||
    epoch - current.epoch > SESSION_WINDOW;

  if (stale) {
    // Re-resolve the symbol before using an expired CallHierarchyItem.
    const fresh = await prepareFresh(
      current.node.uri,
      current.node.pos
    );

    if (!fresh) {
      return [];
    }

    current = fresh;
  }

  const items =
    await lookup(
      current.item!,
      direction
    );

  // A stale reference may return nothing, so invalidate it and retry once.
  if (
    items.length === 0 &&
    attempt === 0 &&
    epoch - current.epoch > SESSION_WINDOW
  ) {
    current = {
      node: current.node,
      epoch: -1,
    };

    continue;
  }

  // Cache the resolved relationships to avoid repeating the language-tooling lookup.
  hopCache.set(key, {
    nodes: items.map(refOf),
    at: Date.now(),
  });

  return items.map(child => ({
    node: refOf(child),
    item: child,
    epoch: current.epoch,
  }));
}

Here, lookup is shorthand for the vscode.provideIncomingCalls or vscode.provideOutgoingCalls command discussed earlier. The exact session limit is an implementation detail of VS Code rather than something the extension should depend on. The crawler therefore doesn't assume that a particular limit will always exist. The SESSION_WINDOW simply gives us a conservative threshold for refreshing old handles.

This reduces lost edges, but it can't guarantee a complete graph. Language tooling can still return incomplete information or fail to resolve certain relationships.

The broader lesson applies to language-service APIs beyond call hierarchy: store what you need to recreate an object from a language service, not the object itself. Treat an empty result from stale state as potentially unknown, not automatically as none.

13. Connecting the Graph to a Webview

Once the graph has been constructed, the extension needs somewhere to display it. VS Code Webviews are a natural fit.

The extension host creates the panel:

const panel =
  vscode.window.createWebviewPanel(
    'codeGraphView',
    'Code Graph',
    vscode.ViewColumn.Beside,
    {
      enableScripts: true,
      retainContextWhenHidden: true,
    }
  );

The graph is sent to the Webview as serializable data:

panel.webview.postMessage({
  command: 'graphData',
  data: graphData,
});

The Webview can then receive it:

window.addEventListener(
  'message',
  event => {
    const message =
      event.data;

    if (
      message.command !==
      'graphData'
    ) {
      return;
    }

    renderGraph(
      message.data
    );
  }
);

At this point, the language-server side of the problem is complete.

We have transformed:

source code

into:

symbols + relationships

and then into:

GraphData

The visualisation layer can now use that data to render the graph.

A library such as ELK can be used to calculate positions for the graph without affecting the graph-building logic.

14. Testing the Graph Builder

Testing this kind of extension can be difficult if every test requires a running VS Code instance and a real language server. A better approach is to isolate the graph-building logic from VS Code itself. The crawler only really needs a few operations:

prepareCallHierarchy
provideIncomingCalls
provideOutgoingCalls

We can create a fake implementation of those commands. For example:

const sessions = new Map();

let sessionCounter = 0;

async function executeCommand(
  command,
  ...args
) {
  // Simulate VS Code creating a session when resolving a symbol.
  if (
    command ===
    'vscode.prepareCallHierarchy'
  ) {
    const id =
      'session-' +
      ++sessionCounter;

    sessions.set(id, true);

    return [
      createFakeItem(
        args,
        id
      ),
    ];
  }

  // Simulate call lookups that depend on a still-valid session.
  if (
    command ===
      'vscode.provideIncomingCalls' ||
    command ===
      'vscode.provideOutgoingCalls'
  ) {
    const item = args[0];

    // Return nothing when the CallHierarchyItem belongs to an expired session.
    if (
      !sessions.has(
        item.sessionId
      )
    ) {
      return [];
    }

    return getFakeCalls(
      item
    );
  }
}

The mock can model edge cases such as expired call hierarchy state. Importantly, if the fake uses a particular session limit, that should be understood as a test model, not automatically as an official VS Code API guarantee.

We can then generate a deterministic graph and compare the crawler's output against a simple reference BFS.

For example:

flowchart LR
    A[A] --> B[B]
    A --> C[C]
    B --> D[D]
    C --> D
    D --> E[E]

The reference implementation knows the expected edges. The production crawler runs against the fake language service. If the two results differ, the test fails. This approach lets us test the difficult graph logic without depending entirely on the editor runtime.

15. The Limitations of a Code Graph

A language-server-based call graph is useful, but it's not a complete representation of program execution. Some relationships can be difficult or impossible for static call hierarchy analysis to resolve.

Examples include:

• dynamic dispatch

• reflection

• dependency injection

• event emitters

• callbacks

• runtime-generated code

• framework-specific behavior

Consider:

eventEmitter.on(
  'payment.completed',
  handlePayment
);

A developer may understand that this creates a runtime relationship between the event and handlePayment. A static call graph may not represent that relationship as a normal function call. The quality of the graph therefore depends partly on the language server and the kinds of relationships it can resolve.

This is why the graph should be understood as a semantic approximation, not as a perfect runtime model. There's also a language-specific dimension.

The graph builder itself can remain largely language-agnostic, but different language extensions may provide different levels of support for document symbols and call hierarchy.

Conclusion

Building a code graph doesn't require writing a compiler or implementing a parser from scratch. VS Code already exposes a significant amount of semantic information through its language APIs.

The core process is:

Document -> Document Symbols -> Call Hierarchy -> Graph Nodes + Edges -> BFS Traversal -> GraphData -> Visualization

The most important engineering decisions aren't about drawing the graph. They're about choosing a useful graph model, creating stable symbol identities, correctly interpreting incoming and outgoing calls, controlling traversal depth and concurrency, handling cycles, and treating language-server state as something that can change.

Once those pieces are in place, the visualisation becomes a separate problem. That separation is what makes the architecture useful beyond a single VS Code extension.

The same graph model can eventually power dependency exploration, change-impact analysis, architecture views, AI context selection, and other ways of navigating increasingly complex codebases.

I built a working version based on this, accessible at: https://github.com/otobongfp/code-graph-view.

I'll be looking forward to seeing all the cool things you can make out of graphs to contribute to the software engineering process.

They search your name, read your posts, and look at your profiles. All of this happens before the first call.

A strong online presence doesn't mean joining every social network. It means that the places people find you tell one clear, credible story about what you do.

Here are the seven parts that matter most:

• 1. A Strong Professional Profile

• 2. A Personal Website

• 3. A Portfolio of Real Work

• 4. A Content Trail

• 5. One Identity Across Platforms

• 6. An Obvious Way to Reach You

• 7. Upkeep and Reputation Checks

• Making It Actually Work

1. A Strong Professional Profile

After finding your name, most people check your profile next. For many, that means LinkedIn.

Treat it as more than a résumé. Your headline should explain your focus, not just your job title. Your summary should say what problems you solve and what work you want more of.

Your experience section should show outcomes. Don't write that you "managed a team." Write what the team achieved. Don't write that you "worked on a product." Write the problem you solved and what changed because of it.

Keep it consistent: your name, title, history, and photo should match your website. A recruiter should never wonder if they found the right person.

Here are a few LinkedIn profiles that will show you how to build a profile that stands out from the rest.

2. A Personal Website

Your website is the base of everything else. It's the one place you fully control.

Social profiles are useful, but they belong to platforms. Designs, algorithms, and rules change. Your own site does not.

More importantly, your website and your LinkedIn profile aren't just the same thing in a different wrapper.

LinkedIn is structured around employment history. It lists your roles in chronological order, inside a template you share with hundreds of millions of people.

Your website is structured around you. It can lead with the specific problem you solve, put your best work front and center, and give visitors a feel for how you think, none of which a profile page can do well.

A consultant, for example, might open their site with a one-line summary of the outcome they deliver ("I help fintech startups reduce churn in their first year"), followed by two or three case studies, and a short essay about their approach. That combination would be invisible on LinkedIn and is exactly what a website is for.

It doesn't need to be complex. One page is often enough. Include your name, your role, a short intro, your experience, a few work samples, and how to reach you.

Clarity beats polish. A visitor should know in five seconds who you are and why it matters.

If you don't want to code, Onepage is an AI-powered website and landing page builder that lets you turn a simple prompt into a professional website within minutes. The AI can generate the initial layout, content, images, and individual sections, while everything remains fully editable through OnePage's visual no-code editor.

You can refine the design and content, add forms and other elements, connect your own domain, and publish the finished site with built-in hosting, without needing a developer or managing a complicated technical setup.

Prefer open source? GitHub Pages hosts a site, blog, or résumé for free. Jekyll works with it out of the box. Hugo is faster and gives you more control, and both have large theme libraries so you can skip the design work.

The goal isn't the most impressive site. It's a reliable home that represents you well.

3. A Portfolio of Real Work

Credentials say what you did, while a portfolio shows it.

This matters most for designers, developers, writers, marketers, consultants, and researchers. If your work can be shown, show it.

A long project list isn't a portfolio. Each piece needs context. Explain the problem, your role, what you did, and the result.

An engineer can walk through the technical problem, the architecture choices, and the outcome. A marketer can cover the strategy, audience, and numbers. A designer can show how research shaped the final screens.

The most useful projects to include are ones where you can clearly explain the problem, your specific contribution, and a measurable result.

A developer might show a tool they built to automate something tedious, explaining the technical tradeoffs and the time it saved. A product manager might walk through a prioritization call , why they chose one feature over three others, what data drove it, and what shipped as a result.

A UX researcher might document a usability study: the questions, the findings, and how the design changed because of them. These are more convincing than a list of company names because they let someone evaluate how you think, not just where you've been.

Is your work confidential? You can still prove skill. Use anonymized case studies, technical articles, talks, or written lessons.

For developers, open source work is one of the strongest portfolio signals available. A public repository shows real code, real decisions, and (if it has contributors or stars) real adoption.

If you've contributed to an existing project, link to specific pull requests and explain the problem you solved. If you've built your own tool or library, make sure the README reads like a case study, what does it do, why did you build it, and who is it for?

If you're looking for inspiration on how to present your portfolio site itself, the portfolio-website topic on GitHub is a useful starting point: developers have tagged thousands of live portfolio sites there, covering a wide range of tech stacks and layouts, and you can browse them to find patterns that work or fork one as a foundation.

The rule is simple: show evidence, not claims.

4. A Content Trail

Your presence gets much stronger when you publish useful ideas.

You don't need to post daily. A few solid articles a year beat a hundred empty ones.

Write about what you know. Explain a hard concept. Share a project lesson. Break down a trend. Document something you built. Describe a mistake and what it taught you.

Over time this becomes a searchable record of your expertise.

It also does something a résumé can't. A résumé lists what you did, while your writing shows how you think.

You can publish anywhere. A hosted platform like Substack needs zero setup. A blog on your own domain gives you full ownership. Developers can also write in their repo docs or on a community site.

Stay focused. You want your name tied to two or three areas, not twenty.

5. One Identity Across Platforms

Your presence has many pieces. They should feel like one person.

Use the same name everywhere. Keep your photo roughly consistent. Link your site from your profiles, and your profiles from your site.

Picture someone finding your website, then LinkedIn, then GitHub. Each stop should add something. None should confuse.

This doesn't mean posting the same thing everywhere. Each platform has a job. Your site is the hub, LinkedIn carries your history, GitHub shows your code, and a social account or blog shows your thinking.

Think of them as different windows into the same room.

6. An Obvious Way to Reach You

A lot of professional sites make contact hard. That's a costly mistake.

If someone wants to hire you, work with you, or invite you to speak, they shouldn't have to hunt. Give them one clear next step.

That could be an email address. It could be a contact form, a LinkedIn link, or a booking page like Cal.com.

You don't need to share personal details. A separate work email keeps things clean.

What matters is that the method is visible, current, and actually checked.

7. Upkeep and Reputation Checks

An online presence isn't a one-time build.

A stale site can hurt as much as no site. Old titles, dead links, dropped projects, and expired domains all signal neglect.

Every few months, set aside an hour. Check that your site loads. Update your current role and recent wins. Cut what's out of date. Then search your own name and see what shows up.

That last step is the most useful one. Search engines surface old profiles, forum comments, conference pages, and accounts you forgot. Google Alerts can flag new mentions for you, and Google's results about you tool lets you request removal of sensitive listings.

You can't control everything online, but you should know what's there.

Making It Actually Work

A good online presence isn't a pile of profiles or a fancy website. It's a clear digital identity that makes your skills easy to grasp and your work easy to check.

Start small: build a simple personal website. Sharpen one professional profile. Add two or three real work examples. Publish a few useful pieces. Then make your contact details obvious.

Use a no-code tool if you want speed. Use GitHub Pages with Jekyll or Hugo if you want control. Either path works.

The best presence isn't the one with the most features. It's the one that answers three questions fast. Who are you? What can you do? And why should anyone trust you?

Answer those clearly and your presence stops being a digital résumé. It becomes an asset that brings you opportunities, even when you aren't looking.

Hope you enjoyed this article. You can connect with me on LinkedIn.

Among these metrics, histograms are particularly useful. They show how often values fall into different ranges, like HTTP request durations, database query times, or queue processing latencies.

Unlike simple averages, histograms show the full picture: you can see how many requests are fast, how many are slow, and where the occasional outliers occur that might be silently degrading the user experience.

In payment systems, for instance, a sudden spike in transactions can expose hidden bottlenecks. Most of the requests might complete quickly, but a small percentage of slow transactions can ripple through the system, impacting retries, failures, and overall throughput. Histograms help identify these issues early by showing how values are distributed and highlighting outliers that averages obscure.

But not all backends understand Prometheus metrics natively. Many modern observability platforms prefer OTLP (OpenTelemetry Protocol). Forwarding Prometheus metrics without converting them can lead to incomplete or misinterpreted data. That’s why we need a pipline to scrape, transform, and export histograms into OTLP so that your observability pipeline remains consistent and actionable.

In this article, we'll use the OpenTelemetry Collector to scrape Prometheus histograms from application /metrics endpoints, map them to the OpenTelemetry Histogram data model, and export them to our observability backend using OTLP. The Collector acts as a bridge that preserves data fidelity while ensuring compatibility with your monitoring platform.

To make this concrete, we'll use a small FastAPI application that simulates payment transactions. It exposes two Prometheus metrics: payment_transaction_duration_seconds (a histogram tracking how long each transaction takes) and payment_transactions_total (a counter of completed transactions). You can follow along with your own instrumented application, as anything exposing Prometheus metrics at /metrics will work the same way. This is the metric we'll follow from the application all the way to the observability backend.

What We'll Cover:

• Prerequisites

• 1. How to Scrape Metrics with Prometheus Receiver

• 2. Transforming Prometheus Histograms

• 3. Exporting Metrics via OTLP

• 4. Putting the Pipeline Together

• 5. Running the OpenTelemetry Collector

  • 5.1 Set Up SigNoz Cloud

  • 5.2 Start the FastAPI Application

  • 5.3 Start the Collector

  • 5.4 Generate Test Transactions

  • 5.5 Confirm Backend Receipt

  • 5.6 Troubleshooting

• Conclusion

Prerequisites

Before you begin, make sure you have:

• Docker installed

• An application exposing Prometheus metrics through a /metrics endpoint

• An OTLP-compatible observability backend

• Basic knowledge of Prometheus metrics

• Basic knowledge of YAML

• Basic familiarity with Docker and OpenTelemetry

You don't need advanced OpenTelemetry knowledge to follow this tutorial. I'll walk through the Prometheus histogram and show what happens to it as it moves through the OpenTelemetry Collector.

1. How to Scrape Metrics with Prometheus Receiver

First, we'll collect metrics from the application. The demo application exposes its Prometheus metrics at the /metrics endpoint, and the Prometheus receiver periodically scrapes this endpoint and ingests the metrics into the observability pipeline. You can also inspect /metrics directly to see the data before the Collector reads it.

Configuration setup example:

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: payment-demo
          scrape_interval: 15s
          static_configs:
            - targets: ["payment-api:8080"]

What's happening behind the scenes here:

scrape_interval controls how often the Collector scrapes the target. Here, we're using 15 seconds; adjust it based on how frequently you need metric updates and the load your application can handle.

In high-throughput systems like payment platforms or real-time processing services, the scrape interval becomes particularly important. Setting it too long may cause you to miss short-lived performance issues or transient errors, while setting it too short risks overwhelming the service with scraping requests or generating excessive network traffic.

targets lists the specific endpoints that expose Prometheus metrics. You can add multiple targets when you need to scrape more than one service.

Finally, job_name is an identifier that helps group metrics logically, making them easier to manage and analyze once they reach your backend.

2. Transforming Prometheus Histograms

Once the metrics are scraped, the next step is transformation. Prometheus exposes histograms as multiple time series:

• _bucket shows how many requests fall below a certain duration.

• _sum is the total of all observed durations.

• _count is the number of observations.

The payment_transaction_duration_seconds histogram records how long each payment transaction takes. Prometheus exposes it as _bucket, _count, and _sum series. When the Prometheus receiver collects these metrics, it converts them into the OpenTelemetry Histogram data model, which can then be exported through OTLP while preserving the information needed to analyze transaction latency and calculate percentiles.

Without histograms, averages obscure latency distributions. If most requests complete in 50ms but 5% take 2+ seconds, the average of 150ms masks that serious performance issue. Histograms capture the complete picture by recording how many observations fall into each latency bucket.

Keeping the distribution allows you to identify changes in latency and investigate issues such as slow database queries, overloaded services, or delays from downstream dependencies.

Actual Prometheus Histogram

This is how your actual /metrics output would look, for example:

And here's the actual OpenTelemetry Histogram representation:

The output above shows the same transaction-duration data represented as an OpenTelemetry Histogram. Instead of three separate Prometheus series, the Collector now has one histogram containing the count, sum, explicit bucket boundaries, and bucket counts.

3. Exporting Metrics via OTLP

Once the metrics have been scraped and processed, the Collector sends them to your observability backend using OTLP. The OTLP exporter sends the processed metrics, including histograms, counters, and gauges, to the backend.

exporters:
  otlp:
    endpoint: "otlp.backend.example.com:4317"
    tls:
      insecure: false

endpoint specifies the backend address for receiving OTLP metrics. This typically points to a central observability platform that aggregates metrics from multiple services across your infrastructure.

tls ensures secure data transmission between the collector and your backend. Set insecure: true only when intentionally connecting to an endpoint that does not use TLS, such as some local development setups

4. Putting the Pipeline Together

We've looked at each part of the pipeline individually. Now let's connect them and follow a metric from the application all the way to the backend.

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      exporters: [otlp]

This is the complete path our payment_transaction_duration_seconds metric follows, from the FastAPI application to the observability backend. The diagram above shows this flow. The next section walks through actually running it and connecting to SigNoz

Pipeline flow:

The above architecture diagram shows a FastAPI application exposing metrics through /metrics, the OpenTelemetry Collector scraping them with the Prometheus receiver, processing the metrics, and exporting them through OTLP to an observability backend.

5. Running the OpenTelemetry Collector

We'll run the complete pipeline and verify that the transaction metrics make it from the application to SigNoz. Follow these steps (which I'll walk you through in detail below):

1. Set up SigNoz Cloud: Configure the endpoint and ingestion key that the Collector will use.

2. Start the FastAPI application: The application exposes the Prometheus metrics at /metrics.

3. Start the OpenTelemetry Collector: The Collector begins scraping the application's /metrics endpoint using the Prometheus receiver.

4. Generate test transactions: Send requests to the application to create transaction-duration measurements.

5. Verify the Collector and backend: Check the Collector logs to confirm that the pipeline is running, then open SigNoz and verify that the payment_transaction_duration_seconds metric has arrived.

6. Troubleshooting

5.1 Set Up SigNoz Cloud

SigNoz provides the observability backend that will receive the metrics exported by the OpenTelemetry Collector. For this demo, we'll use SigNoz Cloud as the observability backend, so there's nothing to install locally.

First, sign up for a free account at signoz.io. In the SigNoz Cloud dashboard, go to Settings → Ingestion Keys. The page shows your Ingestion URL, Region, and Ingestion Key.

Add these to a .env file in your project directory:

SIGNOZ_INGESTION_KEY=your-real-key
SIGNOZ_OTLP_ENDPOINT=ingest.<your-region>.signoz.cloud:443

Treat the ingestion key like a password and never commit it or share it publicly.

Reference those variables in your Collector configuration:

exporters:
  otlp:
    endpoint: "${SIGNOZ_OTLP_ENDPOINT}"
    tls:
      insecure: false
    headers:
      signoz-ingestion-key: "${SIGNOZ_INGESTION_KEY}"

Then add .env to your .gitignore so the key never gets committed:

echo ".env" >> .gitignore

5.2 Start the FastAPI Application.

Start the application on port 8080:

uvicorn app.main:app --reload --port 8080

Verify that the application is running:

curl http://localhost:8080/

Now inspect the Prometheus metrics:

curl -Ls http://localhost:8080/metrics

The /metrics endpoint exposes the application's Prometheus metrics, including the payment_transaction_duration_seconds histogram that the Collector will scrape.

5.3 Start the Collector

With the application running and the Collector configuration in place, start the Collector:

docker compose up --build

Check the Collector logs to confirm that the pipeline is running and that metrics are being processed.

This builds the payment-api image, starts both containers on the shared telemetry network, and the Collector immediately begins scraping /metrics from the application using the Prometheus receiver, reading your SigNoz ingestion key and endpoint from .env automatically.

5.4 Generate Test Transactions

Generate transactions with different processing times:

curl -X POST "http://localhost:8080/transactions?delay_ms=50"

curl -X POST "http://localhost:8080/transactions?delay_ms=250"

curl -X POST "http://localhost:8080/transactions?delay_ms=2500"

Generate additional requests if you want more observations in the histogram.

These requests create transaction-duration observations that are recorded by the payment_transaction_duration_seconds histogram. The Collector picks up the updated metric during its next scrape.

5.5 Confirm Backend Receipt

Open SigNoz Cloud and search for:

payment_transaction_duration_seconds

The metric should be represented as a histogram, with its bucket distribution _bucket, _sum, and _count available to the backend rather than appearing as unrelated Prometheus series.

5.6 Troubleshooting

If metrics aren't flowing correctly, start by checking the log:

docker logs <collector-container>

Look for connection errors, authentication failures, failed scrape attempts, or configuration errors.

Also verify that:

• The FastAPI application is running.

• /metrics is accessible.

• The Collector can reach the application.

• The SigNoz endpoint and ingestion key are correct.

• The .env variables are available to the Collector.

• The receiver and exporter names match the pipeline configuration.

Use the --dry-run flag if available to validate before deployment.

Conclusion

Prometheus histograms provide a useful view of transaction latency by showing how observations are distributed across different buckets rather than reducing them to a single average.

In this tutorial, we followed payment_transaction_duration_seconds from a FastAPI application's /metrics endpoint through the OpenTelemetry Collector and into SigNoz.

The Prometheus receiver mapped the _bucket, _count, and _sum series into the OpenTelemetry Histogram data model, preserving the distribution of transaction durations for analysis in the backend.

This allows the same metric to move from a Prometheus-instrumented application into an OTLP-based observability platform without manually reconstructing the histogram.

You can deploy it in different hosting environments, which gives you the flexibility to choose a deployment model that fits your needs.

Choosing the right hosting option is an important part of any Odoo deployment. It affects factors such as performance, security, maintenance, scalability, and long-term operational costs.

Your team can either self-host Odoo on your own infrastructure or use a managed hosting provider to handle server management. Each approach offers different levels of control, flexibility, and operational responsibility.

In this article, you'll learn about the different ways to host Odoo, including how to set up a basic self-hosted deployment. You'll also compare self-hosted and managed hosting and explore the advantages and limitations of each approach.

By the end, you'll have a better understanding of which hosting model best fits your business and technical requirements.

What We'll Cover:

• What Are Your Odoo Hosting Options?

• Self-Hosted Odoo

• Managed Odoo Hosting

• Self-Hosted vs Managed Hosting

• How to Choose the Right Option

• Key Factors to Consider Before Choosing

• Conclusion

What Are Your Odoo Hosting Options?

Odoo can be hosted in different ways depending on your organization's needs. The main difference between these options is who manages the infrastructure and day-to-day maintenance. In most cases, businesses choose between two hosting models:

1. Self-Hosted Odoo: With a self-hosted deployment, you install and manage Odoo on infrastructure that you control, such as a virtual private server (VPS), dedicated server, cloud virtual machine, or on-premises server. This approach gives you greater control over the environment, but your team is also responsible for maintaining and securing it.

2. Managed Odoo Hosting: With managed hosting, a hosting provider manages the infrastructure and handles routine maintenance tasks. This allows your team to focus on using Odoo for business operations instead of managing servers.

The following sections examine both hosting models in more detail, including their benefits, limitations, and ideal use cases. You'll also learn how to set up a basic self-hosted Odoo deployment and what to consider before choosing a hosting option.

Self-Hosted Odoo

Self-hosting Odoo means deploying and managing the application on infrastructure that you control, such as a virtual private server (VPS), dedicated server, cloud virtual machine, or an on-premises server.

With this approach, your organization is responsible for installing, configuring, maintaining, and securing both Odoo and the infrastructure.

Benefits of Self-Hosting

Self-hosting gives you greater control and flexibility over your deployment. Some of the key benefits include:

• Complete control over the hosting environment.

• Freedom to choose your operating system, database configuration, and hosting provider.

• Support for custom modules, integrations, and server configurations.

• Flexibility to optimize performance based on your workload.

• Greater control over scaling and infrastructure resources.

Challenges of Self-Hosting

Along with greater control comes additional responsibility. When you self-host Odoo, you are responsible for:

• Installing software updates and security patches.

• Managing backups and disaster recovery.

• Monitoring server performance and application availability.

• Troubleshooting infrastructure and application issues.

• Securing the server against potential threats.

Organizations should ensure they have the necessary technical expertise before choosing this deployment model.

Who Should Choose Self-Hosted Odoo?

Self-hosted Odoo is a good choice for:

• Developers and DevOps teams.

• Organizations with in-house IT administrators.

• Businesses that require extensive customization.

• Teams that need complete control over their infrastructure.

• Organizations with specific security or compliance requirements.

How to Self Host Odoo

The following steps show how to deploy Odoo using Docker Compose, PostgreSQL, and Traefik. Traefik acts as the reverse proxy and handles HTTPS certificates for your domain.

Prerequisites

• Linux server with 2 vCPU and 4 GB RAM.

• Docker and Docker Compose installed.

• Domain name with an A record pointing to the server.

• Inbound TCP traffic allowed on ports 80 and 443.

Prepare the Project Directory

Create a directory for the Odoo deployment:

mkdir ~/odoo

Navigate to the project directory:

cd ~/odoo

Create directories for persistent Odoo data, PostgreSQL data, custom addons, and Let's Encrypt certificates:

mkdir -p odoo-data postgres-data addons letsencrypt

Set the ownership of the Odoo data and addons directories to the user used by the Odoo container:

sudo chown -R 100:101 ~/odoo/odoo-data ~/odoo/addons

Create the environment file:

nano .env

Add the following configuration. Replace the domain, email address, and passwords with your own values.

DOMAIN=odoo.example.com 
LETSENCRYPT_EMAIL=admin@example.com 

POSTGRES_DB=postgres 
POSTGRES_USER=odoo 
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD 

ODOO_DB_HOST=db 
ODOO_DB_PORT=5432 
ODOO_DB_USER=odoo 
ODOO_DB_PASSWORD=STRONG_DATABASE_PASSWORD

ODOO_ADMIN_PASSWORD=STRONG_ADMIN_PASSWORD

Save and close the file.

Create the Docker Compose Configuration

Create the Docker Compose file like this:

nano docker-compose.yml

Add the following configuration:

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    restart: unless-stopped

  db:
    image: postgres:15
    container_name: odoo-db
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  odoo:
    image: odoo:19.0
    container_name: odoo
    depends_on:
      - db
    environment:
      HOST: ${ODOO_DB_HOST}
      PORT: ${ODOO_DB_PORT}
      USER: ${ODOO_DB_USER}
      PASSWORD: ${ODOO_DB_PASSWORD}
    command:
      - "--admin-passwd=${ODOO_ADMIN_PASSWORD}"
    volumes:
      - ./odoo-data:/var/lib/odoo
      - ./addons:/mnt/extra-addons
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.odoo.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.odoo.entrypoints=websecure"
      - "traefik.http.routers.odoo.tls=true"
      - "traefik.http.routers.odoo.tls.certresolver=letsencrypt"
      - "traefik.http.services.odoo.loadbalancer.server.port=8069"
    restart: unless-stopped

Start the services in detached mode:

docker compose up -d

Verify that all services are running:

docker compose ps

Check the Odoo logs:

docker compose logs odoo --tail=50

Configure PostgreSQL

Check the privileges of the odoo PostgreSQL role:

docker exec -it odoo-db psql -U odoo -d postgres -c "\du"

Confirm that the odoo role has the Create DB attribute.

If the attribute is missing, grant it using the PostgreSQL administrator account.

docker exec -it odoo-db psql -U postgres -d postgres -c "ALTER ROLE odoo CREATEDB;"

Verify the privilege again:

docker exec -it odoo-db psql -U odoo -d postgres -c "\du"

Access and Configure Odoo

Open https://odoo.example.com in your browser, replacing the domain with your own.

Then click Create Database.

Enter the master password from ODOO_ADMIN_PASSWORD in your .env file. Enter a database name, such as odoo. And enter the administrator email and password.

Select your language and country and click Create Database. Odoo creates the database and opens the dashboard. Log in with your administrator credentials.

Managed Odoo Hosting

Managed Odoo hosting is a deployment model where a hosting provider manages the underlying infrastructure and routine maintenance tasks. Instead of provisioning and maintaining servers yourself, you rely on the provider to manage the hosting environment, allowing your team to focus on using Odoo for day-to-day business operations.

Managed Odoo hosting is available through Odoo itself using Odoo.sh, as well as through third-party providers such as CloudPepper and RoseHosting. The level of server access, customization, maintenance, and infrastructure management varies between providers, so it's important to review what each provider includes before choosing a service.

Benefits of Managed Hosting

Managed hosting simplifies Odoo deployment by reducing the effort required to maintain the underlying infrastructure. Depending on the provider and plan, common benefits may include:

• Faster deployment without extensive server setup.

• Assistance with software updates and security maintenance.

• Automated backups and disaster recovery options.

• Infrastructure monitoring and performance management.

• Technical support for infrastructure-related issues.

• Easier scaling as business requirements grow.

Limitations of Managed Hosting

While managed hosting offers convenience, it also comes with certain trade-offs. Organizations should consider the following:

• Limited control over the underlying server environment.

• Fewer customization options compared to self-hosting, depending on the provider.

• Provider-specific restrictions on server access or configurations.

• Recurring hosting or subscription costs.

• Dependence on the provider for certain maintenance and infrastructure tasks.

Who Should Choose Managed Odoo Hosting?

Managed Odoo hosting can be a good choice for:

• Small and medium-sized businesses.

• Organizations without dedicated IT or DevOps teams.

• Teams that want to reduce the effort of managing infrastructure.

• Businesses looking for a faster and simpler deployment.

• Organizations that prefer a low-maintenance hosting solution.

Self-Hosted vs Managed Hosting

Both self-hosted and managed hosting allow you to deploy and run Odoo. The right choice depends on your organization's technical expertise, operational requirements, customization needs, and budget. The following table compares the key differences between the two hosting models.

Self-hosting is a good choice for organizations that need greater control and customization, while managed hosting is better suited for teams that want to reduce the effort of managing infrastructure and focus on business operations. The right option depends on your technical expertise, operational requirements, customization needs, and long-term business goals.

How to Choose the Right Option

Choosing between self-hosted and managed Odoo hosting depends on your organization's technical expertise, business requirements, budget, and how much time your team can dedicate to managing infrastructure.

Choose Self-Hosted Odoo If

Self-hosting may be a better fit if you:

• Have an in-house IT or DevOps team with Linux and cloud administration experience.

• Need full control over the server environment.

• Require extensive customization or third-party integrations.

• Have specific security, compliance, or performance requirements.

• Are prepared to manage updates, backups, monitoring, and troubleshooting.

Choose Managed Odoo Hosting If

Managed hosting may be a better fit if you:

• Want to deploy Odoo without managing the underlying infrastructure.

• Don't have dedicated IT or DevOps resources.

• Prefer a provider to handle routine maintenance and infrastructure management.

• Want to reduce the operational work involved in maintaining servers.

• Prefer a low-maintenance solution that allows your team to focus on business operations.

The right hosting model depends on how much control your organization needs and how much infrastructure management it is prepared to handle. Consider your technical skills, customization requirements, budget, and long-term business needs before making a decision.

Key Factors to Consider Before Choosing

Choosing the right hosting option involves more than comparing features or costs. Consider the following factors before deciding how to host Odoo.

• Budget: Consider both the initial and ongoing costs. Self-hosting requires infrastructure and maintenance, while managed hosting usually involves recurring hosting fees in exchange for less infrastructure work.

• Technical Expertise: Consider whether your team has the skills to install, maintain, secure, and troubleshoot Odoo. If you don't have dedicated IT or DevOps resources, managed hosting may be easier to maintain.

• Customization: If you need custom modules, third-party integrations, or specific server configurations, check whether your hosting option supports them. Self-hosting generally provides more control over customization.

• Security and Compliance: Consider your security policies, data protection requirements, and any industry regulations that apply to your organization. Also determine which security responsibilities belong to your team and which are handled by the hosting provider.

• Scalability: Consider how your Odoo deployment may grow over time. Your hosting environment should be able to support increases in users, data, and workloads.

• Maintenance and Support: Decide whether your team is prepared to manage updates, backups, monitoring, and troubleshooting or whether you would prefer a provider to handle these responsibilities.

Consider these factors together rather than focusing on a single one. The right hosting solution should match your organization's technical skills, business requirements, budget, and long-term plans.

Conclusion

Choosing the right hosting model is an important part of planning a successful Odoo deployment. Self-hosting offers greater control, flexibility, and customization, while managed hosting reduces the effort required to maintain the infrastructure.

Each approach has its own advantages, and the best choice depends on your organization's technical expertise, business requirements, and long-term goals.

Before making a decision, evaluate factors such as your budget, customization needs, security requirements, scalability, and the resources available to manage the deployment. By selecting the hosting model that aligns with your priorities, you can build a reliable and maintainable foundation for running Odoo.

If you'd like to read more hands-on deployment tutorials and technical documentation, visit my portfolio at docs.abdultalha.dev. You can also connect with me on LinkedIn to follow my latest articles and open-source work.

That tiny game, hidden behind the "No Internet" error since 2014, is played roughly 270 million times every month. Its internal codename at Google was "Project Bolan," a nod to Marc Bolan, frontman of the rock band T. Rex.

And because Chrome is built on the open-source Chromium project, the entire game – every constant, design decision, and hack – is sitting in public for anyone to read.

So I read it. All of it. And it turns out this "simple" game is a small masterclass in game design: it quietly onboards you, refuses to kill you unfairly, animates a moon through seven phases, and has been shipping a typo to billions of devices for a decade.

In this article, we'll walk through the real source code and unpack how the dino game actually works. If you want the game open in a tab while you read, you don't need to kill your Wi-Fi. You can play the Dinosaur Game online, and freeCodeCamp also has a guide to launching it on and offline.

And the code itself lives in the Chromium tree, browsable at source.chromium.org. This is historically a single file of roughly 3,000 lines of dependency-free vanilla JavaScript, drawing on a plain <canvas>. No engine. No framework. Not even jQuery.

By the way, here's the entire game's artwork. It's one small PNG, with every sprite the code refers to by coordinates:

Table of Contents

• The Clock: Why the Game Runs the Same Speed Everywhere

• The T-Rex: Four Constants and a Typo

• The Fairness Engine: How the Game Refuses to Cheat You

• Collision Detection: The Dino Is Six Rectangles

• Night Mode and the Seven-Phase Moon

• The Small Delights Hiding in Plain Sight

• What You Can Steal for Your Own Projects

The Clock: Why the Game Runs the Same Speed Everywhere

The first problem every game has to solve: browsers don't repaint at a fixed rate. A 144 Hz gaming monitor fires requestAnimationFrame 144 times a second. But a struggling laptop might manage 40. If you move things a fixed number of pixels per frame, your game literally runs 3× faster on better hardware.

The dino's solution is the standard one, executed cleanly. The game defines its speeds in pixels per frame at an assumed 60 FPS, then scales every movement by how much time actually passed:

this.msPerFrame = 1000 / FPS;
// ...in each update:
this.xPos -= Math.floor((currentSpeed * FPS / 1000) * deltaTime);

Every moving thing in the game from the dino's jump to the cacti, clouds, and even the moon, is multiplied by deltaTime. That's why your high score is comparable to your friend's, whatever machines you're both on.

If you take one engineering habit away from this article, take this one: never move anything by "per frame" amounts. Always scale by elapsed time.

The T-Rex: Four Constants and a Typo

The dino's entire physical existence is defined by a handful of numbers in Trex.config and Runner.config:

GRAVITY: 0.6,
INIITAL_JUMP_VELOCITY: -10,
SPEED: 6,
ACCELERATION: 0.001,
MAX_SPEED: 13,

Yes, you read that right: INIITAL_JUMP_VELOCITY, with three I's. That misspelling shipped in Chrome, on billions of devices, and has survived for roughly a decade, because renaming it was never worth the risk. Let it comfort you the next time you find a typo in your own production code.

The units are pixels per frame at 60 FPS. Convert them and the physics becomes intuitive: gravity is 0.6 px/frame², jump velocity −10 px/frame. Run the math and the jump arc peaks at about 83 pixels roughly 0.28 seconds after takeoff. On a 150-pixel-tall playfield, that's more than half the screen.

The world starts scrolling at 6 px/frame (360 px/s) and gains 0.001 px/frame every frame until it hits the cap of 13, a little over twice the starting speed. That cap matters: it's the promise that the game gets hard, but never impossible.

But here's the detail most clones miss: the jump height is variable. Watch the code that runs when you release the spacebar:

endJump: function () {
    if (this.reachedMinHeight &&
        this.jumpVelocity < this.config.DROP_VELOCITY) {
        this.jumpVelocity = this.config.DROP_VELOCITY;
    }
},

Tap the spacebar and the dino does a short hop, but hold it and the dino rides the full arc. Releasing the key early clamps the upward velocity, cutting the jump short (as long as a minimum height was reached, so you can't glitch yourself into a cactus). And if you press the Down arrow mid-air, setSpeedDrop multiplies the fall speed by 3, slamming the dino back to the ground for a fast recovery.

Two tiny mechanics, and suddenly the single-button game has an expressive skill ceiling: short hop, full jump, fast slam. That's why the top players' runs look nothing like yours.

The Fairness Engine: How the Game Refuses to Cheat You

This is my favorite part of the codebase, because none of it is visible. You can only feel it. Every obstacle in the game is declared with a small config, and the configs encode a set of fairness rules. Here's the small cactus:

{
    type: 'CACTUS_SMALL',
    width: 17,
    height: 35,
    multipleSpeed: 4,
    minGap: 120,
    minSpeed: 0,
    // ...
}

Let's unpack the rules hiding in there and elsewhere in the spawning code:

Rule 1: The first three seconds are empty. CLEAR_TIME: 3000 guarantees no obstacle spawns for the first three seconds of a run. That's silent onboarding: you get a moment to feel the controls before the game asks anything of you.

Rule 2: Clusters are gated by speed. A cactus can spawn as a group of up to MAX_OBSTACLE_LENGTH: 3, but only when the current speed exceeds its multipleSpeed (4 for small cacti, 7 for large). Why? Because your jump distance grows with the world speed. The arc lasts a fixed time, so the faster the ground moves, the more ground you clear per jump.

Wide obstacles only appear once your jump is physically long enough to clear them. The game never generates a wall it knows you can't cross.

Rule 3: Gaps scale with speed too. The gap after each obstacle is computed as roughly obstacleWidth × speed + minGap × 0.6, plus randomness. So the faster the game, the more room you're given to react. Difficulty comes from the speed itself, never from unfair spacing.

Rule 4: No obstacle appears three times in a row. There's a function whose entire job is variety:

duplicateObstacleCheck: function (nextObstacleType) {
    var duplicateCount = 0;
    for (var i = 0; i < this.obstacleHistory.length; i++) {
        duplicateCount = this.obstacleHistory[i] == nextObstacleType ?
            duplicateCount + 1 : 0;
    }
    return duplicateCount >= Runner.config.MAX_OBSTACLE_DUPLICATION;
},

With MAX_OBSTACLE_DUPLICATION: 2, the spawner keeps a history and re-rolls if the same obstacle type would appear a third consecutive time. You've never noticed this rule, which is exactly the point. You'd have noticed its absence.

Rule 5: The pterodactyl is a late-game boss. Its config says minSpeed: 8.5, meaning it can't appear at all until you're two-thirds of the way to max speed. It flies at one of three heights (so sometimes you jump it, sometimes you duck, and sometimes at 50 pixels you must decide), it never spawns in groups (multipleSpeed: 999), and it has its own speedOffset: 0.8, meaning each pterodactyl flies slightly faster or slower than the world scrolls. That last detail breaks your rhythm-based muscle memory precisely when you've gotten comfortable.

Together these rules are the answer to a question every game designer faces: how do you make a game harder without making it unfair? Players can feel the difference between "I lost because I was slow" and "I lost because the game cheated". And the dino, in ten years and trillions of runs, has never cheated anyone.

Collision Detection: The Dino Is Six Rectangles

Naïve collision detection would wrap the dino in one bounding box and check overlap. But look at the dino: he has a snout sticking out, a tail, a gap under his chin. With a single box, a cactus grazing the empty air under his jaw would kill you, and it would feel terrible.

So the real dino is six boxes:

Trex.collisionBoxes = {
    RUNNING: [
        new CollisionBox(22, 0, 17, 16),   // head
        new CollisionBox(1, 18, 30, 9),    // torso
        new CollisionBox(10, 35, 14, 8),   // legs
        new CollisionBox(1, 24, 29, 5),
        new CollisionBox(5, 30, 21, 4),
        new CollisionBox(9, 34, 15, 4)
    ],
    DUCKING: [
        new CollisionBox(1, 18, 55, 25)    // one long low box
    ]
};

Six small rectangles that trace the dino's actual silhouette: head, torso, and a staircase of boxes down the belly and legs. When the dino ducks, the whole set is swapped for one long, low box.

The obstacles get the same treatment: a small cactus is three boxes tracing its trunk and arms, and the pterodactyl is five, following its wings and beak.

Here's what those boxes actually look like, drawn over the real sprites:

The algorithm is a classic two-phase check: first a cheap outer-box test (do the overall rectangles even touch?), and only if that passes, the detailed loop comparing every dino box against every obstacle box. Fast in the common case, precise in the moment that matters. If a cactus needle visually passes through the notch under the dino's chin, you live, and the code agrees with your eyes.

This is the cheapest possible version of a technique that scales all the way up to fighting-game hitboxes and hurtboxes. The lesson generalizes: collision should match what the player sees, not what's convenient for the math.

Night Mode and the Seven-Phase Moon

Reach 700 points (INVERT_DISTANCE: 700) and the world inverts: dark sky, pale ground, stars. Twelve seconds later (INVERT_FADE_DURATION: 12000), day returns. Numerically it's just a class toggle plus a CSS-style inversion of the palette. But the charming part is what happens in the sky.

The moon isn't a static sprite. The sprite sheet contains it in seven versions, and the code cycles through them:

NightMode.phases = [140, 120, 100, 60, 40, 20, 0];

Those are x-offsets into the sprite sheet, from a thin crescent through the half moons to a full disc:

Every time night falls, the moon advances one phase. Stars drift at their own speed (STAR_SPEED: 0.3), slower than the ground, giving the night a whisper of parallax depth. Nobody needed a lunar calendar in a browser error page. Somebody built one anyway, and that somebody understood that details like this are the difference between a feature and a beloved thing.

The Small Delights Hiding in Plain Sight

A few more finds from the source that reward the attentive:

The dino blinks. While the game waits for you to start, the idle dino blinks at randomized intervals. And there's a constant, MAX_BLINK_COUNT: 3, limiting how many times he'll do it. The blink delay itself is Math.ceil(Math.random() * Trex.BLINK_TIMING). Someone at Google tuned the randomness of a dinosaur's eyelid.

Your score isn't pixels. The distance meter multiplies actual pixels traveled by COEFFICIENT: 0.025. So a score of 100 means you've run 4,000 pixels. Every 100 points (ACHIEVEMENT_DISTANCE: 100), the score flashes at four beats per second – a tiny dopamine metronome that makes round numbers feel like events.

The counter is theatrical about overflow. The display shows MAX_DISTANCE_UNITS: 5 digits. Roll past 99,999 and the score visually resets. The internal counter keeps going, but the odometer effect stays, a deliberate homage to arcade cabinets.

Mobile players get a handicap. MOBILE_SPEED_COEFFICIENT: 1.2: the game runs faster... wait, no: it adjusts for the smaller screens and touch latency so the experience feels equivalent. The point is that someone measured the difference between a thumb on glass and a finger on a spacebar, and encoded the answer in a constant.

Restart is protected. After a crash there's a GAMEOVER_CLEAR_TIME: 750. For three-quarters of a second, your jump key won't restart the game. That's there because you will be hammering the spacebar when you die, and instantly restarting would rob you of the chance to see your score. A 750-millisecond act of mercy.

What You Can Steal for Your Own Projects

The dino game is a masterclass precisely because its constraints were brutal: it had to be tiny, load instantly, run on everything from gaming rigs to $50 phones, and be understood by anyone in one second.

The techniques it uses under those constraints transfer to any project:

• Scale by time, not frames. Delta-time movement is why the game is fair across hardware.

• Gate difficulty behind capability. Wide clusters appear only when the jump can clear them. Ask what the player can do, then spawn accordingly.

• Give the player an empty runway. Three quiet seconds teach the controls better than a tutorial screen.

• Enforce variety. A three-line history check prevents monotony the player would notice only as vague boredom.

• Make hitboxes honest. Six rectangles that match the silhouette beat one rectangle that betrays the player's eyes.

• Spend effort on invisible details. Blinking, moon phases, the restart grace period: none are necessary, but all are felt. Ten years on, the Chrome dino is proof that a great game doesn't need photorealistic graphics or a 100-gigabyte install. It just needs tight controls, fair rules, one button, and a moon that keeps its phases. Now you know exactly why it feels so good: because someone, line by line, made sure it would.

Go read the source. It's one of the best free game design lessons on the internet, and it's been hiding behind your worst Wi-Fi days all along.

So I built and open-sourced a complete SaaS landing page template called ChatDeck. It runs on Next.js 16, React 19, shadcn/ui with the new base-nova style, Tailwind CSS v4, and TypeScript. The full source is on GitHub under the MIT license. I built and open-sourced this template, and everything here comes from decisions made during that process.

Building it forced me to make real decisions on a stack that moved significantly in the past 12 months. This article is about those decisions: what worked, what didn't, and what I'd do differently if I started today.

Prerequisites: This article assumes you're comfortable with React and TypeScript. Some familiarity with the Next.js App Router is helpful but not required. Each lesson is explained from first principles.

Table of Contents

• The Stack Choices and Why They Matter

• Getting Started

• Project Structure

• Lesson 1: shadcn/ui's Newbase-novaStyle Changes What "Accessible" Means

• Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

• Lesson 3: OKLCH Colors Make Dark Mode Predictable

• Lesson 4: Page Architecture — Flat Beats Clever

• Lesson 5: Staggered Animations Without Managing Individual Delays

• Lesson 6: CSS-Only Infinite Scroll — No Library Needed

• Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

• Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

• What I'd Do Differently

• Summary

The Stack Choices and Why They Matter

Before getting into the code, here's what the template runs on. Each choice was deliberate — none of these are defaults you get from create-next-app.

The most interesting decisions in this list are the ones that reflect how the ecosystem changed in the past year: Base UI replacing Radix inside shadcn/ui, and Tailwind v4's shift to CSS-first configuration. The lessons below walk through each of these in detail, starting with the choices that had the biggest impact on how the code is actually written.

Getting Started

Before diving into the lessons, here's how to get the project running locally. Having it open alongside this article makes the code examples easier to follow.

git clone https://github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template.git
cd chatdeck-shadcn-saas-landing-page-template
pnpm install
pnpm dev

Open http://localhost:3000 and you'll see the full landing page running locally.

All section content lives as plain TypeScript arrays inside each Block component. To change the features, edit the features array in FeatureSection.tsx. To change pricing tiers, edit the plans array in PricingSection.tsx. No CMS, no config files — just TypeScript objects.

To customize colors, update the OKLCH values in app/globals.css under the :root block. Change --primary and every button, link, and accent color updates across the entire template.

Deploy to Vercel with a single vercel command or by pushing to GitHub and connecting the repo. Next.js is detected automatically.

Project Structure

Here's the full directory layout before we go through each part of it:

chatdeck/
├── app/
│   ├── globals.css         # Theme tokens + custom animations (Tailwind v4 @theme)
│   ├── layout.tsx          # Root layout — Navbar, Footer, fonts
│   └── page.tsx            # Section imports — 16 lines
├── components/
│   ├── Blocks/             # Page sections (Hero, Features, Pricing, etc.)
│   ├── ui/                 # shadcn/ui components — base-nova style
│   └── navbar.tsx          # Scroll-aware sticky navbar
└── lib/
    └── utils.ts            # cn() helper (clsx + tailwind-merge)

The key separation is Blocks/ vs ui/. The ui/ folder holds primitive components — Button, Badge, Accordion — that come from shadcn/ui and rarely change. The Blocks/ folder holds page-level sections that are specific to this template and change often. When you're customising, you mostly work in Blocks/. When you upgrade shadcn/ui components, you touch ui/.

The lessons below go through specific files in this structure piece by piece: components.json and ui/accordion.tsx in Lesson 1, app/globals.css in Lessons 2 and 3, app/page.tsx in Lesson 4, and the individual Block components in Lessons 5 through 8.

Lesson 1: shadcn/ui's New base-nova Style Changes What "Accessible" Means

If you've used shadcn/ui before, you know the default setup uses Radix UI primitives, headless components that handle focus management, keyboard navigation, and ARIA attributes. Radix has been the default for years.

But shadcn/ui introduced a new style in 2025 called base-nova, which replaces Radix with Base UI, the headless primitive library from MUI.

Based on shadcn's public direction and the components released through 2025, base-nova appears to be the intended default going forward (though shadcn hasn't yet deprecated the Radix style).

In the project's components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

The "style": "base-nova" line means every component the shadcn/ui CLI installs wraps Base UI primitives instead of Radix. To understand what this changes in practice, here's what the same Accordion trigger component looks like in the older Radix-based default style:

// Radix-based default style (the old way)
import * as AccordionPrimitive from "@radix-ui/react-accordion"

const AccordionTrigger = React.forwardRef<
  React.ElementRef<typeof AccordionPrimitive.Trigger>,
  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
>(({ className, children, ...props }, ref) => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        ref={ref}
        className={cn("flex flex-1 items-center justify-between ...", className)}
        onClick={() => setIsOpen(!isOpen)}
        {...props}
      >
        {children}
        <ChevronDownIcon
          className={cn(
            "h-4 w-4 shrink-0 transition-transform duration-200",
            isOpen ? "hidden" : "block"
          )}
        />
        <ChevronUpIcon
          className={cn(
            "h-4 w-4 shrink-0 transition-transform duration-200",
            isOpen ? "block" : "hidden"
          )}
        />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
})

Notice the useState(false) tracking whether the accordion is open, and the onClick handler that toggles it. This means the component has to manually keep its own isOpen state in sync with what Radix internally knows about the open/closed state.

Now here's the same component using the base-nova style with Base UI:

// components/ui/accordion.tsx — base-nova style (the new way)
import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"

function AccordionTrigger({ className, children, ...props }: AccordionPrimitive.Trigger.Props) {
  return (
    <AccordionPrimitive.Header className="flex">
      <AccordionPrimitive.Trigger
        data-slot="accordion-trigger"
        className={cn(
          "group/accordion-trigger relative flex flex-1 items-start ...",
          className
        )}
        {...props}
      >
        {children}
        <ChevronDownIcon
          className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden"
        />
        <ChevronUpIcon
          className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline"
        />
      </AccordionPrimitive.Trigger>
    </AccordionPrimitive.Header>
  )
}

No useState. No onClick. No isOpen variable. The chevron visibility is controlled entirely by group-aria-expanded/accordion-trigger:hidden — a Tailwind class that reads the aria-expanded attribute Base UI sets automatically on the trigger element.

The lesson here: in the Radix version, you have two parallel systems: the component's own isOpen state, and the ARIA attributes that the library manages separately for screen readers. These can drift out of sync — for example, if the accordion closes via keyboard navigation, the ARIA state updates correctly but your isOpen state doesn't unless you wire up the right callbacks. In the Base UI version, there is only one system. ARIA state IS the state. Tailwind reads it directly. There's nothing to keep in sync and nothing that can drift.

Lesson: use the primitive library's ARIA attributes as your source of truth for visual state. If your headless component library already sets aria-expanded, aria-selected, or aria-checked, Tailwind can respond to those directly with aria-* variant classes — no parallel JavaScript state needed.

So when you install shadcn/ui today, choose base-nova over the default Radix style. You get tighter Base UI integration, a smaller peer dependency footprint, and components that are more aligned with where the ecosystem is moving.

Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

Tailwind CSS v4 moves primary theme configuration out of the JavaScript config file and into CSS. This sounds small. In practice, it changes how you think about the entire theming system.

In Tailwind v3, you'd extend the theme in tailwind.config.js:

// OLD — tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      animation: {
        marquee: "marquee 40s linear infinite",
      },
      keyframes: {
        marquee: {
          from: { transform: "translateX(0)" },
          to: { transform: "translateX(calc(-100% - var(--gap)))" },
        },
      },
    },
  },
}

In Tailwind v4, that same configuration lives in your CSS file instead:

/* app/globals.css — Tailwind v4 */
@import "tailwindcss";

@theme inline {
  --animate-marquee: marquee var(--duration) infinite linear;
  --animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;

  @keyframes marquee {
    from { transform: translateX(0); }
    to   { transform: translateX(calc(-100% - var(--gap))); }
  }

  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

The @theme inline block extends Tailwind's design token system. Define --animate-marquee here and you can use className="animate-marquee" anywhere in your components. Tailwind generates the utility class automatically from the CSS variable.

Custom animations, radius scales, and color tokens all live in CSS now. The benefit is that CSS is where styles belong. The config file was always an indirection layer between "what I want my design system to look like" and "where that actually lives." Tailwind v4 removes the indirection.

The friction: if you start a Tailwind v4 project with a v3 mental model, you'll spend time looking for theme config in the wrong place. Read the v4 migration guide before you start, not after you're confused.

Lesson: move your mental model of "theme config" from JavaScript to CSS. In Tailwind v4, if you want a custom animation, a new radius scale, or a color token, define it in @theme inline inside globals.css. That's where it belongs, and that's where every developer on your team will find it.

Lesson 3: OKLCH Colors Make Dark Mode Predictable

The template uses OKLCH color values throughout, not hex or HSL:

:root {
  --background: oklch(1 0 0);        /* white */
  --foreground: oklch(0.145 0 0);    /* near-black */
  --primary: oklch(0.205 0 0);
  --border: oklch(0.922 0 0);
}

.dark {
  --background: oklch(0.145 0 0);    /* near-black */
  --foreground: oklch(0.985 0 0);    /* near-white */
  --primary: oklch(0.922 0 0);
  --border: oklch(1 0 0 / 10%);      /* white at 10% opacity */
}

OKLCH is a perceptually uniform color space. When you increase the lightness value in OKLCH, the color actually looks lighter to human eyes, consistently. Hex and HSL don't guarantee this. You can increase the L in HSL and get a color that looks the same or even darker depending on the hue.

For dark mode specifically, this matters because you're inverting a whole color system. With HSL, you'll often end up manually tweaking individual color values until contrast ratios look right. With OKLCH, increasing or decreasing the lightness value gives you predictable results across all your tokens.

The dark mode switch itself is zero JavaScript. Adding class="dark" to the <html> element swaps every CSS variable. Tailwind reads the updated variables and re-renders every component. There's no context provider and no useTheme hook needed for the CSS layer — just a class toggle on the root element.

Lesson: swap your color tokens to OKLCH. When defining dark mode values, adjust the first OKLCH parameter (lightness) and the result will look predictably lighter or darker. With hex or HSL you're often guessing; with OKLCH you're reasoning.

Lesson 4: Page Architecture — Flat Beats Clever

The main page file is 16 lines:

// app/page.tsx
import Hero from "@/components/Blocks/Hero";
import { LogoCarousel } from "@/components/Blocks/LogoCarousel";
import { FeatureSection } from "@/components/Blocks/FeatureSection";
import { TeamSection } from "@/components/Blocks/TeamSection";
import { TestimonialSection } from "@/components/Blocks/TestimonialSection";
import { PricingSection } from "@/components/Blocks/PricingSection";
import { FaqSection } from "@/components/Blocks/FaqSection";

export default function Home() {
  return (
    <main className="min-h-screen bg-white dark:bg-black">
      <div className="mx-auto max-w-7xl px-6 pt-40">
        <Hero />
        <LogoCarousel />
        <FeatureSection />
        <TeamSection />
        <TestimonialSection />
        <PricingSection />
        <FaqSection />
      </div>
    </main>
  );
}

No dynamic imports, no lazy-loading config, no context providers wrapping everything. Each section is a completely self-contained component in components/Blocks/. None of them import from each other.

This decision came from watching how developers actually use shadcn templates. The first thing anyone does after cloning is delete the sections they don't need and reorder the ones they keep. With flat imports, removing the Team section is one deleted line. Reordering sections is moving one line. Adding a new section is creating a file and adding one import.

The alternative (a sections array, a renderer loop, a config file that controls order) sounds sophisticated. In practice, it adds indirection that makes the template harder to understand and slower to customize. Templates should be obvious, not impressive.

Lesson: in a template context, the simplest architecture is the correct architecture. The developer cloning your template isn't impressed by abstraction. They want to understand the code fast and change it faster.

Lesson 5: Staggered Animations Without Managing Individual Delays

The Hero section uses entrance animations where each element fades up sequentially: badge first, then heading, then subheading, then CTA. The naïve approach sets a different delay prop on each element manually. The correct approach uses staggerChildren:

// components/Blocks/Hero.tsx
"use client"
import { motion, type Variants } from "motion/react"

const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.15,  // each child animates 150ms after the previous
      delayChildren: 0.1,
    },
  },
}

const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { duration: 0.5, ease: "easeOut" },
  },
}

const Hero = () => (
  <motion.div variants={containerVariants} initial="hidden" animate="visible">
    <motion.div variants={fadeUpVariants}>
      {/* Badge */}
    </motion.div>
    <motion.h1 variants={fadeUpVariants}>
      AI Chatbot for Customer Support.
    </motion.h1>
    <motion.p variants={fadeUpVariants}>
      {/* Subheading */}
    </motion.p>
    <motion.div variants={fadeUpVariants}>
      {/* CTA */}
    </motion.div>
  </motion.div>
)

The parent defines staggerChildren: 0.15. Every child with variants={fadeUpVariants} automatically inherits a 150ms offset from the previous child. Want to add a new element? Give it variants={fadeUpVariants} and the stagger chain extends automatically. No manually updated delay values.

The Features section uses scroll-triggered animations with a different easing:

// components/Blocks/FeatureSection.tsx
<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, amount: 0.3 }}
  transition={{
    duration: 0.5,
    delay: index * 0.15,
    ease: [0.22, 1, 0.36, 1],
  }}
>

viewport={{ once: true }} fires the animation once when the element enters the viewport, not on every scroll pass. amount: 0.3 starts the animation when 30% of the element is visible, not when the full element is on screen. The cubic bezier [0.22, 1, 0.36, 1] is a fast-out-slow-in curve that feels physical rather than mechanical.

Quick note on the import: most of the core API is compatible, but motion/react isn't a straight drop-in rename of framer-motion. If you're upgrading an existing project, check the official migration guide before swapping the import. Layout animations, AnimatePresence behaviour, and some hooks changed.

Lesson: define animation variants at the parent level and use staggerChildren to orchestrate the sequence. Never set delay manually on individual elements — that creates a brittle list of numbers you have to update every time you add or remove an element. Let the parent handle timing; let children just declare what they animate to.

Lesson 6: CSS-Only Infinite Scroll — No Library Needed

The testimonials use a dual-row auto-scrolling marquee. The second row scrolls in reverse. There's no third-party marquee package. It's a small component built entirely on CSS animations defined in Tailwind v4's @theme block.

// components/ui/marquee.tsx
export function Marquee({
  reverse = false,
  pauseOnHover = false,
  vertical = false,
  children,
  repeat = 4,
  ...props
}) {
  return (
    <div className="group flex gap-(--gap) overflow-hidden [--duration:40s] [--gap:2rem]">
      {Array(repeat).fill(0).map((_, i) => (
        <div
          key={i}
          className={cn("flex shrink-0 justify-around gap-(--gap)", {
            "animate-marquee flex-row": !vertical,
            "group-hover:paused": pauseOnHover,
            "[animation-direction:reverse]": reverse,
          })}
        >
          {children}
        </div>
      ))}
    </div>
  )
}

The repeat={4} prop renders the children 4 times side by side. As the CSS animation scrolls the container left, the repetitions create a seamless loop. By the time the first set has scrolled off screen, the second set is already in position.

group-hover:paused is Tailwind applying animation-play-state: paused when the parent has group class and is hovered. No onMouseEnter/onMouseLeave handlers or state, just pure CSS.

To customize the scroll speed without touching the component source, you override the CSS variable inline:

<Marquee pauseOnHover className="[--duration:20s]">
  {items.map(item => <Card key={item.id} {...item} />)}
</Marquee>

[--duration:20s] is a Tailwind arbitrary property. It sets --duration directly on the element, which the animation reads via var(--duration). Speed customization without a prop, without touching the component.

Lesson: before reaching for a third-party animation package, check whether a CSS keyframe animation and a couple of Tailwind utilities can do the same job. A marquee, a fade loop, a pulsing skeleton — all of these are achievable with native CSS. Fewer dependencies means fewer breaking changes when the ecosystem moves.

Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

The pricing section has three cards: Free, Pro, and Business. Each card has four rows: plan name, price, CTA button, and features list. The features list height varies between plans. Without CSS subgrid, the rows don't align across cards.

The common workaround is min-height on each row, or JavaScript that measures each card and sets explicit heights. Both approaches are fragile. Subgrid solves it in CSS:

// components/Blocks/PricingSection.tsx
<div className="grid lg:grid-cols-3">
  {plans.map((plan) => (
    <div className="p-8 grid grid-rows-subgrid row-span-4 gap-6">
      <div>{/* Plan name + description */}</div>
      <div>{/* Price */}</div>
      <div>{/* CTA button */}</div>
      <div>{/* Features list */}</div>
    </div>
  ))}
</div>

grid-rows-subgrid tells each card to participate in the parent grid's row tracks rather than creating its own. Each card spans 4 rows (row-span-4). The plan name row, price row, CTA row, and features row align across all three cards (regardless of content height) because they're all on the same row tracks.

Each card's row-span-4 reserves four rows in the parent's implicit grid. Because every card spans the same four shared row tracks, their internal rows align automatically even though the parent never declares explicit row heights.

CSS subgrid has been in all modern browsers since late 2023. There's no reason to reach for a JavaScript layout solution when the platform handles it.

Lesson: when you have a grid of cards where each card has multiple internal rows that need to align across columns, reach for grid-rows-subgrid before reaching for min-height or JavaScript. Define the number of rows each card spans with row-span-N, and the browser handles the rest.

Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

The logo carousel renders 12 brand logos: Shopify, Stripe, GitHub, Google, and others. The first instinct is to use a package like react-icons or simple-icons. I went a different direction: inline SVG paths stored as a plain TypeScript object.

// components/Blocks/LogoCarousel.tsx
const iconMap = {
  stripe: "M13.976 9.15c-2.172-.806...",
  github: "M12 .297c-6.63 0-12...",
  google: "M12.48 10.92v3.28h7.84...",
  // ...
} as const

const SimpleIcon = ({ iconSlug, size = 24 }: { iconSlug: string; size?: number }) => {
  const iconPath = iconMap[iconSlug as keyof typeof iconMap]
  return (
    <svg role="img" viewBox="0 0 24 24" className="fill-black dark:fill-white">
      <path d={iconPath} />
    </svg>
  )
}

The fill-black dark:fill-white class means every logo automatically inverts in dark mode: no separate dark mode logo assets, and no conditional rendering based on theme.

The carousel itself duplicates the logo array to create a seamless loop:

{/* First pass */}
{techCompanies.map((company, i) => <LogoCard key={`first-${i}`} {...company} />)}
{/* Second pass — identical, creates the seamless loop */}
{techCompanies.map((company, i) => <LogoCard key={`second-${i}`} {...company} />)}

The CSS animation (animate-logo-scroll) scrolls the container left. When the first pass disappears off the left edge, the second pass is already in position. The loop is seamless.

The trade-off: maintaining SVG paths manually is fine for a fixed set of logos. If you need a large dynamic icon set, reach for simple-icons or a proper icon library. For 12 brand logos that rarely change, this approach ships zero extra dependencies.

Lesson: match your tooling to your actual requirements. A logo carousel with a fixed set of brand logos doesn't need an icon library — it needs a TypeScript object and two Tailwind classes. Installing a package to solve a problem you could solve with 10 lines of code adds maintenance surface for no gain.

What I'd Do Differently

These are the three decisions I'd change if starting the template today.

1. Extract Animation Variants to a Shared File

containerVariants and fadeUpVariants are currently defined locally in both Hero.tsx and FeatureSection.tsx. If you want to change the global animation timing (say, reduce duration from 0.5s to 0.3s) you update two files. A shared lib/animations.ts exporting the standard variants would make global timing changes a one-line edit.

// lib/animations.ts
export const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.5, ease: "easeOut" } },
}

export const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1, transition: { staggerChildren: 0.15, delayChildren: 0.1 } },
}

2. Use Subgrid in the Features Section Too

The Features grid uses a border-based visual separation pattern — borders between cells create the grid appearance. It works, but the hover states have an inconsistency: the gradient hover overlay height varies slightly between cells in the same row because content heights differ. Subgrid would lock those row heights across cards the same way it does in the Pricing section.

3. Use next/font More Consistently

The layout loads both Geist and Inter font families. Inter is used via --font-sans. Geist is loaded but the geistSans.variable and geistMono.variable are applied to <body> as className strings while Inter drives the actual font rendering through the CSS variable. The result is that Geist is loaded but not actually displayed. Cleaning this up could shave tens of kilobytes from the font payload — worth verifying in Lighthouse or the Network tab before deploying.

Summary

These are the five things from this build worth taking into your next project:

1. shadcn/ui's base-nova style runs on Base UI primitives. ARIA state drives visual state — no parallel JavaScript state needed.

2. Tailwind v4 moves theme config to CSS. All theme tokens, custom animations, and radius scales live in CSS via @theme inline. This is the right place for them.

3. OKLCH gives predictable dark mode contrast. Adjusting lightness in OKLCH actually changes perceived brightness. Hex and HSL don't guarantee this.

4. staggerChildren in motion/react eliminates manually managed animation delays. The parent orchestrates while the children just declare their animation variant.

5. CSS subgrid (grid-rows-subgrid) aligns card rows across columns natively. No JavaScript measurement, no fixed heights.

The full template is MIT-licensed and available at github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template. If it's useful, a star helps others find it.

But these skills have a hidden limitation: they're static. If you download a skill someone else wrote and you want it to behave a little differently, you'll have to copy the whole thing and edit it by hand. And as you may have noticed lately, there are many "skills" forks floating around that are difficult to maintain.

In this tutorial, I'll show you I built a small convention that fixes this. It lets any Agent Skill read a per-project config file, so you can adopt any skill and customize how it behaves by editing a few lines of YAML (without ever touching the skill itself).

You'll build it step by step, test it, and see how to share it so other people can plug into it.

Table of Contents

• What You Will Build

• Prerequisites

• What Are Antigravity Agent Skills?

• Why Static Skills Are a Problem

• The Configurable Skills Solution

• How to Build the Config Loader

• How to Make a Skill Configurable

• How to Add Project Overrides

• How to Test Your Configurable Skill

• Two More Example Skills

• How to Share Your Agent Skills With Others

• Wrapping Up

What You Will Build

You will build a tiny, reusable layer called Configurable Agent Skills. It has three parts:

1. A small Python script, resolve_config.py, that merges a skill's default settings with your project settings and prints the result.

2. A convention: each skill ships 2 files, a config.default.yaml file with its "knobs" and a SKILL.md file. They both guide the agent's behavior.

3. A per-project file, .agent/skills.config.yaml, where anyone using your skill sets their own values.

By the end, you'll have a working git-commit-formatter skill that one team can run in Conventional Commits mode and another team can switch to gitmoji mode, all using the exact same skill files with no forking.

Prerequisites

To follow along, you'll need:

• Google Antigravity installed (the IDE, CLI, or SDK. Any of them work, since skills are just files.).

• Python 3 installed, with PyYAML. You can install PyYAML with python -m pip install pyyaml.

• Basic comfort with the terminal and YAML. You don't need to be an expert in either.

If you've never written an Agent Skill before, the next two sections will bring you up to speed.

What Are Antigravity Agent Skills?

A Skill in Antigravity is a folder that contains a SKILL.md file and, optionally, some scripts, templates, or examples. The SKILL.md file has a short block of YAML "frontmatter" at the top (a name and a description), followed by a set of instructions written in plain Markdown.

Here's the important part: skills are loaded on demand. The agent reads only the short description of each skill at first. When your request matches that description, the agent pulls in the full instructions and follows them. This keeps the agent's context small and focused.

A minimal skill that enforces Conventional Commits looks like this:

---
name: git-commit-formatter
description: Formats git commit messages using the Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---

# Git Commit Formatter

When writing a commit message, follow the Conventional Commits format:
`type(scope): description`

Allowed types: feat, fix, docs, style, refactor, perf, test, chore.

Drop that in your skills folder, ask the agent to "commit these changes," and it will write a properly formatted message. Simple and useful, right?

Why Static Skills Are a Problem

Now look closely at that skill. The allowed types (feat, fix, docs, and so on) are baked directly into the instructions.

That's fine until someone wants something slightly different. Maybe your team also uses a ci type. Maybe you prefer gitmoji, where each commit starts with an emoji. Maybe you want to require a scope on every commit.

With a static skill, there's only one way to get any of that: copy the whole skill and edit the Markdown. When you do this across a team, everyone ends up with their own private fork. When the original author ships an improvement, none of the forks get it. The skill stops being something you share and becomes something everyone rewrites.

The core issue is that there's no clean line between the skill's logic (which everyone should share) and its settings (which each project wants to control). How do we solve this?

The Configurable Skills Solution

The idea is simple. Instead of hard-coding settings in the instructions, the skill will:

1. Ship its settings and their defaults in a separate config.default.yaml file.

2. Read a merged config (defaults plus any project-level overrides) before it acts.

The project-level overrides live in a file called .agent/skills.config.yaml, which sits at the root of the user's project:

# .agent/skills.config.yaml 
# (edit this file in your project instead of the skill globally)
git-commit-formatter:
  style: gitmoji
  extra_types: [ci, build]
  scope_required: true

That's the easy flow. Drop the skill in, set a few keys, and you're done. The skill's own files never change.

To make this work, you need a script that reads both files, merges them, and hands the result to the agent. Let's build it.

How to Build the Config Loader

Create a file called resolve_config.py. Its job is to take a skill's name, load that skill's config.default.yaml, find the user's .agent/skills.config.yaml, and merge the two so that user values win.

Start with a deep-merge helper. This is the heart of the loader:

def deep_merge(base, override):
    """Recursively merge override onto base.

    Dicts merge key by key. Anything else (scalars, lists) is replaced
    wholesale by the override value.
    """
    if isinstance(base, dict) and isinstance(override, dict):
        merged = dict(base)
        for key, value in override.items():
            merged[key] = deep_merge(merged[key], value) if key in merged else value
        return merged
    return override

Notice the deliberate choice here: dictionaries merge key by key, but lists are replaced, not appended. That keeps the behavior predictable. If you want to handle "defaults plus extras", use the explicit extra_types key in the skill as you'll see in the example below.

Next, you need to find your "per-project" config. The loader walks up from the current directory looking for an .agent/skills.config.yaml file:

from pathlib import Path

def find_project_config(start: Path):
    """Walk upward from start looking for .agent/skills.config.yaml."""
    start = start.resolve()
    for folder in [start, *start.parents]:
        candidate = folder / ".agent" / "skills.config.yaml"
        if candidate.is_file():
            return candidate
    return None

Now put it together. The loader locates the skill's defaults (which sit next to the script), loads your overrides for that skill's name, merges them, and prints the result:

import sys, yaml
from pathlib import Path

def resolve(skill_name, skill_dir, project_root):
    defaults = yaml.safe_load((Path(skill_dir) / "config.default.yaml").read_text()) or {}

    user_path = find_project_config(Path(project_root))
    user_all = yaml.safe_load(user_path.read_text()) if user_path else {}
    user_cfg = (user_all or {}).get(skill_name, {}) or {}

    return deep_merge(defaults, user_cfg)

That completes the whole idea. The full version in the sample repo adds a command-line interface, JSON output, and clear error messages, but the logic above is all you really need.

How to Make a Skill Configurable

Now you'll convert the static commit skill into a configurable one. This takes two files.

First, create config.default.yaml next to the skill. It lists every setting and a safe default, so the skill works even when the user has no config at all:

# Default configuration for the git-commit-formatter skill.
style: conventional          # conventional | gitmoji
types:                       # base set of allowed commit types
  - feat
  - fix
  - docs
  - style
  - refactor
  - perf
  - test
  - chore
extra_types: []              # additional types, merged on top of `types`
scope_required: false        # if true, require a scope: type(scope): ...
max_subject_length: 72       # hard cap on the subject line

Second, update SKILL.md so that its very first instruction is to resolve the config and apply it. This is the key move: you're telling the agent to read the settings before it does anything else:

---
name: git-commit-formatter
description: Formats git commit messages to a team's chosen convention (Conventional Commits or gitmoji). Use this when the user asks to commit changes or write a commit message. Reads per-project settings so teams customize commit style without editing this skill.
---

# Git Commit Formatter (Configurable)

## Step 1 - Resolve configuration (always do this first)

Run the loader and read its output:

`python scripts/resolve_config.py git-commit-formatter --project-root .`

Apply exactly those settings:

- `style`: `conventional` or `gitmoji`.
- `types` + `extra_types`: the full set of allowed commit types.
- `scope_required`: if true, a scope is mandatory.
- `max_subject_length`: hard cap on the subject line.

## Step 2 - Compose the message

Pick the primary type from `types` + `extra_types`, build the subject in the
chosen `style`, and enforce `scope_required` and `max_subject_length`.

This pattern ("make the agent run a script and obey its output") is the same one Antigravity's own validation skills use. It keeps the behavior deterministic instead of leaving it to the model's memory.

Notice how extra_types solves the additive-list question. The default list stays put, and the user's extras are simply added on top by the skill. No fork is required to add a ci type.

How to Add Project Overrides

Let's say you want gitmoji commits with two extra types. Create a single file in your project:

# .agent/skills.config.yaml
git-commit-formatter:
  style: gitmoji
  extra_types: [ci, build]
  scope_required: true

You just changed three lines of config and didn't open the skill or fork any code. The next time the agent commits, it will use this project settings.

And a different project, with no config file at all, keeps getting the sensible Conventional Commits defaults. You have one skill with many behaviors.

How to Test Your Configurable Skill

You don't need the agent to check that the merge works. Run the loader directly and read the output.

With no overrides, you get the defaults:

$ python scripts/resolve_config.py git-commit-formatter --project-root .
style: conventional
scope_required: false
...

Now add the .agent/skills.config.yaml override from the last section and run it again:

$ python scripts/resolve_config.py git-commit-formatter --project-root . --print-sources
style: gitmoji
scope_required: true
extra_types:
- ci
- build
types:
- feat
- fix
- docs
...

The style flipped to gitmoji, scope_required became true, and your extra types appeared (while the base types list stayed intact). That confirms the merge does exactly what you want.

It's worth writing a small automated test too, so a future change to the loader can't silently break the merge. A test can create a fake skill and a fake project config in a temp folder, run the loader, and assert that user values override defaults while untouched defaults survive.

Two More Example Skills

The same pattern works for any skill. Here are two more to show the range.

A Changelog Generator

Its config.default.yaml exposes the output format (like Keep a Changelog), which commit types to include, and whether to link commit hashes to a repo URL. One project can generate a formal changelog grouped by type, while another can generate a simple bulleted list. It's the same skill with a different config.

# changelog-generator config.default.yaml (excerpt)
format: keepachangelog       # keepachangelog | conventional | simple
include_types: [feat, fix, perf]
include_authors: false
repo_url: ""                 # if set, hashes link to commits

A License-Header Adder

Its config exposes the license (Apache-2.0, MIT, or custom), the holder, and a map of file extensions to comment styles. A company sets the holder once in their project config, and every new file gets the right header in the right comment style, without editing the skill.

# license-header-adder config.default.yaml (excerpt)
license: apache-2.0          # apache-2.0 | mit | custom
holder: "Your Name or Org"
year: auto                   # auto = current year

The lesson is that almost any skill has a few decisions baked into it. When you pull those decisions into a config.default.yaml, you convert a one-off skill into a tool that anyone can reuse and tune.

How to Share Your Agent Skills With Others

Once your agent skills follow the convention, they compose into something bigger. To make your agent skills easy for others to adopt, you have to:

• Keep each skill self-contained: Vendor a copy of resolve_config.py inside each skill's scripts/ folder, so someone can copy a single skill folder anywhere and it just works.

• Document every config key in the SKILL.md, so users know exactly what they can tune.

• Publish a small index: A simple index.json that lists each skill's name, path, and config keys makes it easy for others to discover what you've built and contribute their own.

Because the convention is just "read a config file first," anyone can publish a compatible skill. Each new configurable skill makes the whole ecosystem more useful. In addition to shipping a skill, you're shipping a small standard that other people can build on.

Wrapping Up

You started with a static skill whose behavior was frozen in Markdown, and you turned it into a configurable one that anyone can tune from a single project file.

The entire setup is relatively small. It has the merge function, one convention, and a config.default.yaml per skill.

It also changes how skills are shared. Instead of forking a skill to change one setting, you can keep the shared logic and adjust your own config. Improvements to the skill flow to everyone, and everyone still gets the behavior they want.

If you want to try it, build the git-commit-formatter skill from this tutorial, drop it into your Antigravity skills folder, and add an .agent/skills.config.yaml to a project. Then flip style from conventional to gitmoji and watch the same skill behave differently.

From there, make one of your own skills configurable. Find the settings you baked into the instructions, move them into a config.default.yaml, and let your users take it from there.

The full sample code (the loader, its tests, and all three example skills) is on GitHub at github.com/keepdeploying/configurable-agent-skills.

Thanks for reading. If you build a configurable skill of your own, share it. Let's keep the ecosystem growing.

const response = await llm.chat("Explain Kubernetes");

For a little while it feels like the whole flow is: the user asks something, and the model returns an answer. That early success often creates a false impression that building AI is just about sending prompts and getting responses.

That simplicity is seductive, but it doesn't hold up. Over time, users want the assistant to find answers in their documents and knowledge bases, call APIs, fetch live data, or trigger services or schedule meetings.

Users also expect the agent to access internal systems and interact with ERPs, CRMs, or other tools holding critical business data. They'll want agents to combine multiple steps, as workflows often require chaining queries, computations, and side effects into reliable processes.

This is where concepts like MCP (the Model Context Protocol) and tools like LangChain come in. Initially, they may seem like buzzwords, but they address different aspects of LLM production.

After experimenting with AI tools, I found that these concepts help solve different problems related to interfaces, orchestration, and system integration.

This article is a practical guide to understanding how LLMs connect with tools, orchestrate workflows, and power real AI applications.

Here’s what we’ll cover:

1. What Is an LLM?

2. Why LLMs Need Tools

3. Where MCP Comes In

4. So What Does LangChain Actually Do?

5. Putting It Together

6. What I Built While Learning This

Throughout the article we'll discuss what LLMs are and how they work, what tool-calling looks like in practice, what MCP is and how it works, how LangChain fits into the whole process, and how to put all these tools together.

To follow along, you'll need a basic understanding of Node.js, API operations, and basic JavaScript concepts.

What Is an LLM?

LLM stands for Large Language Model. It's a class of deep neural networks trained on massive amounts of text to model and generate human-like language. Popular examples you might have heard of include GPT, Claude, Gemini, and Llama.

How to Call an LLM From a Node.js Application

Before writing code, let’s understand what it means to call an LLM from a Node.js application.

Calling an LLM means sending input from your application to an AI provider’s API and receiving generated output in return. It's similar to calling any other external service.

In most real-world applications, the model isn't hosted or trained by your application. Instead, providers such as OpenAI and Groq host and maintain the models, while your application communicates with them over HTTP APIs.

In this example, we’ll build a minimal API using Node.js and Express. We’ll create a simple POST /chat endpoint that accepts a user message, sends it to the OpenAI API, receives the generated response, and returns it to the client.

Here, our Node.js server acts as the bridge between the user and the LLM provider.

For this example, create an API key from the Groq console. Since it offers a free tier, it’s a simple way to experiment and understand the concepts.

First, install the dependencies:

npm install express

import express from "express";

const app = express();
app.use(express.json());

app.post("/chat", async (req, res) => {
  const { message } = req.body;
  const response = await fetch("https://api.groq.com/openai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: GROQ_API_KEY,
    },
    body: JSON.stringify({
      model: "llama-3.3-70b-versatile",
      messages: [{ role: "user", content: message }],
    }),
  });

  const data = await response.json();

  if (!response.ok) {
    return res.status(response.status).json({ error: data });
  }

  const reply = data.choices[0].message.content;

  res.json({ reply });
});

const PORT = process.env.PORT || 8888;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Start the server and make a request. Use Postman and do a POST request to /chat using the below body:

POST /chat

{
  "message": "Explain Kubernetes"
}

Example response:

{
  "reply": "Kubernetes is a container orchestration platform..."
}

The backend receives the message, forwards it to the model provider, receives generated text, and returns it to the client.

LLMs are excellent at language-centric tasks: they understand phrasing and intent, generate coherent text, extract structured information from unstructured input, and perform basic reasoning over provided context. These capabilities make them powerful for things like summarization, drafting, and conversational QA.

But there’s an important limitation: LLMs don't automatically know about and can't access your private or live data. They don’t have implicit access to your company database, internal APIs, or the current state of your systems unless you provide that information at runtime.

Because of that limitation, you need secure mechanisms to connect models to live systems and data — which brings us to the idea of tools.

Why LLMs Need Tools

Imagine asking:

Check my order and raise support if delivery is delayed.

The model alone can't inspect your order database or create a support ticket in your system. To do that, it must call external functions — for example, a getOrderStatus(orderId) API and a createSupportTicket(orderId, issue) action.

Those callable functions are what we call tools: programmatic interfaces the AI can use to interact with systems and take concrete actions on behalf of users.

A tool is simply a function that an AI model can call to interact with external systems or perform actions.

For example, imagine we have a getOrderStatus(id) function that returns an order’s delivery status.

To expose this to the LLM, we define a tools array. Each tool includes:

• type – currently "function"

• function name – the function identifier

• function description – helps the LLM decide when to call the tool

• function parameters – a JSON Schema describing the arguments the tool expects

Here's an example:

function getOrderStatus(id) {
  const statuses = ["pending", "success", "cancelled"];
  const status = statuses[Math.floor(Math.random() * statuses.length)];
  return `Your order status is ${status}.`;
}

const tools = [
  {
    type: "function",
    function: {
      name: "getOrderStatus",
      description: "Get the status of an order by its ID",
      parameters: {
        type: "object",
        properties: {
          id: { type: "string", description: "The order ID" },
        },
        required: ["id"],
      },
    },
  },
];

The above tool format is for Grok. Different LLM providers may use different formats for defining tools, but the overall idea remains the same.

When making the API call, we pass both the user messages and the list of available tools.

body: JSON.stringify({
    model: "llama-3.3-70b-versatile",
    messages: [{ role: "user", content: message }],
    tools,
}),

After the API call, the LLM decides whether a tool is needed. If a tool call is requested, our application executes the corresponding function and sends the result back to the model.

For this example, we'll only handle the getOrderStatus tool. We can check whether the model requested a tool call like this:

const toolCall = data.choices[0].message.tool_calls[0];
const { id } = JSON.parse(toolCall.function.arguments);
const toolResult = getOrderStatus(id)

and later we can pass the message context with tool result

body: JSON.stringify({
    model: "llama-3.3-70b-versatile",
    messages: [
        { role: "user", content: message },
        assistantMessage,
        { role: "tool", tool_call_id: toolCall.id, content: toolResult },
    ],
    tools,
}),

Finally, return the response:

return res.json({ reply: followUpData.choices[0].message.content });

Here's a diagram of the flow:

The LLM decides whether a tool is needed and generates the required inputs, while your application executes the function.

Where MCP Comes In

Tools are simple. You define functions and tell the AI what it can use.

For example, getOrderStatus() works well when all tools are built inside your application. But as applications grow, tools may come from many places, like Slack, GitHub, databases, internal systems, or third-party services. Each one may expose tools differently.

This is where MCP (Model Context Protocol) helps. Think of MCP as a common language that lets AI systems connect to external tools in a consistent way.

Tools define what the AI can do. MCP standardizes how the AI connects to and uses those tools.

Now let’s extend the previous /chat API example so the LLM can use tools exposed through MCP. There are multiple ways to do this:

• build and host your own MCP server and expose your application functions

• connect to existing third-party MCP servers such as Slack

For this tutorial, we'll keep things simple and use a remote MCP server approach because it's easier to understand.

npm install express @modelcontextprotocol/sdk zod

Now let’s create our own MCP server and expose the same getOrderStatus function as an MCP tool:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

function getOrderStatus(id) {
  const statuses = ["pending", "success", "cancelled"];
  const status = statuses[Math.floor(Math.random() * statuses.length)];
  return `Your order status is ${status}.`;
}

function createOrderServer() {
  const server = new McpServer({ name: "order-server", version: "1.0.0" });

  server.registerTool(
    "getOrderStatus",
    {
      description: "Get the status of an order by its ID",
      inputSchema: { id: z.string() },
    },
    async ({ id }) => ({
      content: [{ type: "text", text: getOrderStatus(id) }],
    })
  );

  return server;
}

const app = createMcpExpressApp({ host: "0.0.0.0" });

app.post("/mcp", async (req, res) => {
  const server = createOrderServer();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  res.on("close", () => {
    transport.close();
    server.close();
  });

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const PORT = process.env.PORT || 3001;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Order MCP server running on http://0.0.0.0:${PORT}/mcp`);
});

This is useful when you want to expose your own application functions through MCP. Typically, the MCP server runs separately and is accessed by MCP clients. Now any MCP client can connect to this server and discover the available tools automatically.

The same idea applies to third-party MCP servers.

For example, if a Slack MCP server is available, we can connect to it instead of writing Slack integration code ourselves.

In that case, our application isn't directly calling Slack APIs. It connects to the Slack MCP server, which exposes Slack-related tools using the MCP standard.

So the difference is:

• For our own features, we can build our own MCP server

• For external systems, we can use existing MCP servers when available

Now we can pass MCP servers to the LLM request:

body: JSON.stringify({
  model: "llama-3.3-70b-versatile",
  messages: [{ role: "user", content: message }],
  tools: [
    {
      type: "mcp",
      server_label: "OrderServer",
      server_url: `http://0.0.0.0:${PORT}/mcp`,
      server_description: "Get the status of an order by its ID",
    },
    {
      type: "mcp",
      server_label: "Slack",
      server_url: "https://mcp.slack.com/mcp",
      server_description: "Send and read Slack messages",
      headers: {
        Authorization: `Bearer ${process.env.SLACK_BOT_TOKEN}`,
      },
    },
  ],
})

We can also use local MCP servers instead of remote URLs by connecting through transports such as StdioClientTransport. In that case, we connect locally, discover the available tools, and expose them to the LLM.

Now if the user sends:

{
  "message": "What is status of order 123"
}

The LLM decides whether a tool is needed, MCP exposes and executes the tool, and the final response is returned to the user.

The flow becomes:

This standardization makes integrations far more reusable: instead of rewriting glue logic for each new connector, teams can register MCP-compliant tools and let the orchestrator and model handle discovery and invocation.

So What Does LangChain Actually Do?

I initially thought LangChain was simply another wrapper around LLM APIs, but it is better understood as an orchestration framework for AI workflows. Tools let an LLM perform actions. MCP standardizes how tools are exposed. LangChain helps coordinate models, tools, and application logic to build multi-step workflows.

For example:

User: Find flights, compare prices, book hotel, send confirmation.

Now the system may need to:

• Check order status

• Decide whether support is needed

• Create a support ticket

• Generate the final response

Without orchestration, you would manually control each step. LangChain helps manage this flow.

To use LangChain, Install the required packages:

npm install express langchain @langchain/groq

We'll reuse the same tool functions from earlier:

import express from "express";
import { createAgent } from "langchain";
import { ChatGroq } from "@langchain/groq";

const app = express();
app.use(express.json());

const agent = createAgent({
  model: new ChatGroq({
    model: "llama-3.3-70b-versatile",
    apiKey: GROQ_API_KEY,
  }),
  tools: [
    {
      name: "getOrderStatus",
      description:
        "Get order status",
      execute: ({ id }) =>
        getOrderStatus(id), // we have this function above
    },
    {
      name: "createSupportTicket",
      description:
        "Create support ticket",
      execute: ({ id }) =>
        createSupportTicket(id), //imagine a function that creates a support ticket
    },
  ],
});

app.post(
  "/chat",
  async (req, res) => {
    const { message } = req.body;

    const response =
      await agent.invoke({
        messages: [
          {
            role: "user",
            content: message,
          },
        ],
      });

    res.json({
      reply:
        response.messages
          ?.at(-1)
          ?.text,
    });
  }
);

app.listen(3000);

Now the flow becomes:

LangChain doesn't replace tools or MCP. It sits above them and coordinates how everything works together.

Putting It Together

A modern AI application usually has multiple layers working together. The LLM handles reasoning and language generation. Tools perform real operations such as reading data, calling APIs, or executing actions. MCP helps standardize how those tools are exposed and accessed. LangChain helps orchestrate the interaction between models, tools, and workflows.

By separating these responsibilities, applications become easier to extend, maintain, and scale.

The goal is more than just generating text. You want to be able to build systems that can reason, retrieve information, take actions, and reliably solve real user problems.

What I Built While Learning This

After understanding the concepts above, I wanted to reduce some of this setup for my own projects. As I experimented, I noticed most applications recreate the same plumbing over and over: connecting an LLM, wiring up tools, managing execution, and exposing orchestration patterns.

So I built a small open-source toolkit to reduce that setup. The goal was simple: you should be able to focus on business logic instead of wiring AI infrastructure.

Current capabilities:

• LLM integration

• Tool registration

• Tool execution

• Chat orchestration

• LangChain support

• Extensible architecture

Packages:

AI Chat Widget: https://www.npmjs.com/package/ai-chat-toolkit-widget

AI Chat Server: https://www.npmjs.com/package/ai-chat-toolkit-server

GitHub Repository: https://github.com/sudheeshshetty/ai-chat-toolkit

To build a server using the toolkit:

npm install express ai-chat-toolkit-server

Create the chat server:

const aiChat = new AiChatServer({
  path: "/my-chat",
  provider: "groq",
  apiKey: process.env.API_KEY,
  model: process.env.MODEL || "llama-3.3-70b-versatile",
  cors: {
    origin: "http://localhost:5174",
  },
  orchestration: "langchain",
  maxToolRounds: 6,
  systemPrompt:
    "You are a helpful operations assistant for a demo store. Keep answers concise.",
});

Add your tools:

aiChat.addTools([
  {
    name: "...",
    description: "...",
    inputSchema: { ... },
    handler: async (input) => { /* runs in Node */ },
  },
]);

Attach it to your Express app:

aiChat.attach(app);

Now /my-chat is exposed in your Express server and can be used directly.

You can also use ai-chat-toolkit-widget if you want to skip building the chat UI.

Examples are available in the repository, so you can try it out quickly.

A quick glance of one of the examples:

If you find it useful, I’d appreciate a star, feedback, or contributions on GitHub as I continue improving the developer experience and exploring new ideas.
Thanks for reading — I hope this helped make LLMs, tools, MCP, and LangChain feel a little less magical and a lot more practical.

A decade ago, most STEM students depended on textbooks, calculators, and expensive licensed software. Today, open source tools have made advanced learning resources available to anyone with an internet connection.

Many of these tools are powerful enough for professional researchers and software engineers, yet simple enough for students who are just getting started. They help with coding, data analysis, mathematics, technical writing, visualization, collaboration, and project management.

In this article, we'll look at seven open source tools that can help STEM students study more effectively, build projects faster, and develop industry-ready technical skills.

What We'll Cover:

• Why Open Source Tools Matter for STEM Students

• Jupyter Notebook for Interactive Learning

• VS Code for Programming and Technical Projects

• GeoGebra for Mathematics Visualization

• Git and GitHub for Collaboration

• Blender for Scientific and Engineering Visualization

• OBS Studio for Recording and Presentations

• How Open Source Tools Build Career Skills

• The Future of STEM Education

• Final Thoughts

Why Open Source Tools Matter for STEM Students

Open source software is more than just free software. It gives students access to the underlying code, community support, and the freedom to experiment without restrictions.

This matters because STEM education is becoming increasingly hands-on. Employers expect students to understand practical workflows, not just theory. Learning how to use modern tools early can make the transition into internships and engineering roles much easier.

Open source ecosystems also evolve quickly. Students can explore real-world technologies used in research labs, startups, and large engineering organizations. Many of these environments also rely on open-source automation tools to simplify development workflows and improve collaboration across technical teams.

Jupyter Notebook for Interactive Learning

One of the most important tools for STEM students is Jupyter Notebook.

Jupyter Notebook allows users to combine code, mathematical equations, visualizations, and notes inside a single interactive document. This makes it extremely useful for subjects like data science, physics, statistics, and machine learning.

A student can write Python code, run calculations, and immediately visualize the output using graphs or tables. Instead of switching between multiple applications, everything exists in one place.

For example, a physics student can simulate motion equations, while a statistics student can analyze datasets directly inside the notebook.

Jupyter is widely used in universities and research institutions because it supports experimentation and iterative learning.

VS Code for Programming and Technical Projects

Visual Studio Code has become one of the most popular development environments in the world. Although it is developed by Microsoft, it's built on open source technologies and supports a massive extension ecosystem.

For STEM students, VS Code is valuable because it supports nearly every major programming language. Whether you're learning Python, JavaScript, C++, or Rust, the editor provides debugging, syntax highlighting, terminal integration, and Git support in one interface.

Engineering students often work across multiple disciplines. A robotics student might write Python scripts, configure embedded systems, and document experiments all in the same environment.

VS Code also integrates well with Jupyter Notebook, making it an excellent all-in-one workspace for technical learning.

GeoGebra for Mathematics Visualization

Mathematics becomes easier when students can visualize concepts instead of memorizing formulas.

GeoGebra is an open source mathematics platform that helps students explore algebra, geometry, calculus, and statistics through interactive graphs and simulations.

Students can manipulate equations dynamically and observe how graphs change in real time. This creates a much deeper understanding of mathematical relationships.

Interactive visualisation tools are especially useful for students preparing for advanced mathematics courses. Popular teaching platforms like Brighterly who are known as a great precalculus tutor, use graphing platforms like GeoGebra to better understand trigonometric functions, transformations, and polynomial behaviour. The platform is also useful for individual teachers who want to create interactive lessons instead of relying entirely on static diagrams.

Git and GitHub for Collaboration

Version control is one of the most important technical skills students can learn.

Git is an open source version control system that helps developers track changes in code and collaborate efficiently. It is widely used across software engineering, data science, and research projects.

Students often lose work because they overwrite files or create confusing project versions. Git solves this problem by maintaining a complete history of changes.

When paired with GitHub, students can collaborate on projects, contribute to open source repositories, and build a public portfolio of technical work.

This is especially valuable for computer science students applying for internships or engineering roles. Recruiters frequently review GitHub profiles to evaluate coding ability and project experience.

Even students outside traditional software engineering fields benefit from Git. Researchers use it for reproducible experiments, while engineering teams use it to manage technical documentation and simulation code.

Blender for Scientific and Engineering Visualization

Most people associate Blender with animation and game design, but it's also a powerful tool for STEM applications.

Blender is an open source 3D modeling and rendering platform used in industries ranging from architecture to scientific visualization.

Engineering students can use Blender to create product prototypes, mechanical visualizations, and simulation renders. Biology students can build anatomical models, while physics students can visualize complex systems in three dimensions.

Visualization plays a major role in technical understanding. A well-designed 3D model can explain concepts that are difficult to communicate through text alone.

Blender also teaches valuable spatial reasoning and design skills that are increasingly useful in fields like robotics, manufacturing, and augmented reality.

OBS Studio for Recording and Presentations

Modern STEM learning is becoming more collaborative and content-driven.

Students now create tutorials, record presentations, explain coding projects, and participate in online learning communities. OBS Studio is an open source tool that allows users to record screens, stream presentations, and create technical demonstrations.

This is particularly useful for students building portfolios or preparing project walkthroughs.

For example, a software engineering student can record a demo of a web application, while a mathematics student can create video explanations of problem-solving methods.

OBS Studio is lightweight, flexible, and widely used by educators, developers, and technical creators.

How Open Source Tools Build Career Skills

One of the biggest advantages of open source tools is that they mirror real industry workflows.

Students aren't just learning academic concepts. They're learning systems used in professional engineering environments.

A student who understands Git, VS Code, Jupyter, and collaborative development practices already has exposure to modern software engineering workflows. Similarly, students using Blender or GeoGebra are developing visualization and analytical skills that transfer into technical careers.

Open source communities also encourage experimentation. Students can inspect source code, contribute fixes, participate in discussions, and learn directly from experienced developers around the world.

This creates a more active learning process than simply consuming tutorials.

The Future of STEM Education

STEM education is shifting toward project-based and interdisciplinary learning.

Students are expected to solve problems, communicate ideas clearly, and adapt to rapidly evolving technologies. Open source tools make this possible by lowering financial barriers and giving students access to professional-grade software.

The rise of artificial intelligence, data science, and remote collaboration has also increased the importance of technical self-learning. Students who can independently explore tools and build projects will have a significant advantage in both academics and industry.

The good news is that modern open source ecosystems make this easier than ever before. A student with a laptop and internet connection can now access tools that were once available only to large universities or research organizations.

Final Thoughts

The best STEM students aren't always the ones with the most expensive hardware or software. Often, they're the ones who learn how to use accessible tools creatively and consistently.

Platforms like Jupyter Notebook, VS Code, GeoGebra, LibreOffice, Git, Blender, and OBS Studio provide a strong foundation for technical learning across many disciplines.

More importantly, these tools encourage curiosity, experimentation, and practical problem-solving. Those skills matter far beyond the classroom.

As STEM education continues to evolve, students who embrace open source technology will be better prepared for research, engineering, software development, and the increasingly interdisciplinary future of technical work.

The usual fix is to hand the agent a headless browser — Puppeteer or Playwright driving a fresh Chromium instance. That works, sort of. But a headless Chromium starts every session as a stranger: no logins, no cookies, no sessions. It spins up a second browser engine that pushes your CPU and spins up your fan. And a growing number of sites simply block it on sight.

There's another option, and on a Mac it's a good one: let the agent drive the Safari you already use — the one that's already logged into GitHub, your analytics, your staging environment. That's what Safari MCP does. It's an open-source MCP server that exposes Safari to any MCP-capable agent through around 80 tools, with no Chromium, no WebDriver, and no separate browser to babysit.

In this tutorial you'll connect Safari MCP to an AI agent, run your first automation, and then build something a headless browser fundamentally cannot do: an automation that works inside a page you're logged into. By the end you'll understand not just how to wire this up, but when native browser automation is the right call — and when it isn't.

Here's what you'll need:

• A Mac (Safari MCP is macOS-only — more on that trade-off later)

• Node.js 18 or newer

• An MCP-capable AI agent — this tutorial uses Claude Code and Cursor, but any MCP client works

Table of Contents

• What is MCP, and Why Does Browser Automation Need It?

• Why Safari Instead of Chrome or Playwright?

• Installing Safari MCP

• Your First Automation: Reading a Page

• The Payoff: Automating a Logged-in Workflow

• Handling the Tricky Parts

• Limitations: When Not to Use This

• Wrapping Up

What is MCP, and Why Does Browser Automation Need It?

Before wiring anything up, it helps to know what the "MCP" in Safari MCP stands for.

MCP is the Model Context Protocol — an open standard for connecting AI agents to external tools and data. Think of it the way you'd think of a USB port. Before USB, every device needed its own connector. MCP is the equivalent of agreeing on one connector: an agent that speaks MCP can use any tool that speaks MCP, with no custom integration code on either side.

An MCP server exposes a set of tools. An MCP client — your AI agent — discovers those tools and calls them. The server describes each tool (its name, what it does, what arguments it takes) and the agent decides when to call it. When Claude Code decides it needs to read a web page, it doesn't run browser code itself. It calls a tool that some MCP server provides.

Browser automation is a natural fit for this model. The agent's job is reasoning — "I need to see what's on the staging site, then check the console for errors." The actual mechanics — open a tab, wait for load, read the DOM, capture console output — are well-defined operations that belong behind a stable interface. That interface is exactly what an MCP server provides.

Safari MCP is one such server. It runs as a local process, exposes around 80 browser tools (navigate, click, fill, read, screenshot, extract, and more), and any MCP client can drive it. The agent never touches AppleScript or WebKit internals. It just calls safari_navigate and gets a result.

The "USB port" framing matters for a practical reason: nothing in this tutorial is Claude-specific. Wire Safari MCP into Cursor, Cline, Windsurf, or your own MCP client and the tools are identical.

Why Safari Instead of Chrome or Playwright?

If you've automated a browser before, you've almost certainly used Chrome through Puppeteer, Playwright, or Selenium. So why reach for Safari?

It comes down to three differences that matter once an AI agent, not a test script, is the thing driving the browser.

1. It's your real browser, with your real sessions. A headless Chromium launched by Playwright is a clean room. It has never logged into anything. If you want your agent to read your analytics dashboard, you first have to solve authentication — store credentials somewhere, script the login, handle two-factor prompts, refresh tokens. Safari MCP skips all of that. It drives the Safari instance you use every day, which is already logged into your dashboards, your GitHub, your email. The agent inherits those sessions for free.

2. It doesn't melt your laptop. A headless Chromium is a second, full browser engine running alongside the browser you already have open. On a laptop that's real CPU, real memory, and a fan you can hear. Safari MCP uses the WebKit engine that's already running on every Mac — there's no second engine to start. The project measures this at roughly 60% less CPU for the browsing work, and the automation runs with Safari in the background, so it doesn't steal your screen.

3. Sites don't treat it as a bot. Headless browsers leak. They expose navigator.webdriver, they ship with telltale automation fingerprints, and bot-detection services — Cloudflare's challenge pages, reCAPTCHA, the WAFs in front of a lot of B2B sites — have gotten very good at spotting them. Your real Safari, driven through the operating system, looks like exactly what it is: a person's browser. (To be clear: this is for automating your own accounts and sites — not for evading access controls you don't own.)

The cost of all this is the obvious one: Safari MCP is macOS-only. It's built on WebKit and AppleScript, so there's no Windows or Linux story. If your agent runs on a Linux CI box, this isn't your tool. If it runs on your Mac — which, for a coding agent, it very often does — the trade is a good one. We'll come back to limitations honestly at the end.

Installing Safari MCP

Installation is genuinely one command, but there are two Safari settings to flip first. Let's do it in order.

Step 1 — Enable Safari's developer features

Safari MCP reads and controls pages by running JavaScript inside Safari. Two settings have to be on:

1. Open Safari → Settings → Advanced and check "Show features for web developers." This reveals the Develop menu.

2. Open the new Develop menu and check "Allow JavaScript from Apple Events."

That second one is the important one. It's what lets an outside process — the MCP server — ask Safari to run JavaScript on a page. Without it, every tool call fails.

Step 2 — Run the server

npx safari-mcp

That's the whole install. npx fetches the package and runs it; there's nothing to build. The first time an agent calls a tool, macOS will pop up a permission prompt — something like "Terminal wants to control Safari." Click OK. That's the standard Automation permission, and you can review it later under System Settings → Privacy & Security → Automation.

If you'd rather have it installed permanently:

npm install -g safari-mcp

Step 3 — Tell your agent about it

Your AI agent needs to know the server exists. For Claude Code, one command does it:

claude mcp add safari -- npx safari-mcp

For Cursor, create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["safari-mcp"]
    }
  }
}

The process is the same for every client — Claude Desktop, Cline, Windsurf, Continue, VS Code. You're telling the agent: "there's an MCP server named safari; start it by running npx safari-mcp."

Restart your agent (or reload its MCP servers) and it will connect. In Claude Code you can confirm with the /mcp command, which lists connected servers and their tools. You should see safari with around 80 tools available.

That's it. Your agent now has a browser.

Your First Automation: Reading a Page

Let's prove the wiring works with the simplest possible task: have the agent read a web page.

In your agent, just ask in plain language:

"Use the safari tools to open example.com and tell me what the page says."

Behind that request, the agent makes two tool calls. First it navigates:

{ "tool": "safari_navigate", "arguments": { "url": "https://example.com" } }

Then it reads the content:

{ "tool": "safari_read_page", "arguments": {} }

safari_read_page returns the page's title, URL, and text content with the HTML stripped out — exactly the form an LLM wants. The agent gets back something like this:

Example Domain
https://example.com/
This domain is for use in illustrative examples in documents. You may
use this domain in literature without prior coordination or asking for
permission.

And it relays that to you. You just watched your agent browse.

A quick note on how the agent should look at a page, because it changes everything downstream. safari_read_page is great for "what does this say." But when the agent needs to act — click a button, fill a field — text isn't enough. It needs to know what's actually there and how to target it. For that, the better first move is safari_snapshot:

{ "tool": "safari_snapshot", "arguments": {} }

This returns an accessibility-tree view of the page, where every interactive element has a stable ref ID:

[textbox ref=0_8] "Full Name" value=""
[combobox ref=0_10] "Subject"
[button ref=0_15] "Submit"

Those ref IDs are the agent's reliable handles. CSS selectors break when a page re-renders. A snapshot ref stays valid for the life of the page. Keep that in mind — it's the difference between an automation that works once and one that works every time.

The Payoff: Automating a Logged-in Workflow

Reading example.com is a wiring test. Here's the thing a headless browser genuinely cannot do.

Pick a site you're logged into in Safari right now — your analytics, your project board, your CI dashboard. We'll use GitHub, because every developer has an account and the notifications page is a real, mildly annoying chore. The task: have the agent open your GitHub notifications and summarize what actually needs your attention.

Ask the agent:

"Open my GitHub notifications, read them, and group them into 'needs a reply' versus 'just FYI'."

The agent navigates:

{ "tool": "safari_navigate", "arguments": { "url": "https://github.com/notifications" } }

Stop and notice what didn't happen. No login screen. No OAuth dance. No personal access token in an environment variable. Safari is already authenticated as you, so the agent lands directly on your real notifications. A headless Chromium would have hit a login wall here and stopped.

Notification lists load incrementally, so the agent should wait for content before reading. safari_wait_for polls the page until a selector or piece of text appears, or a timeout elapses:

{ "tool": "safari_wait_for", "arguments": { "text": "Inbox", "timeout": 10000 } }

Then it reads. safari_read_page scoped to the notifications region returns the list as clean text:

{ "tool": "safari_read_page", "arguments": { "selector": "main" } }

The agent reasons over that text and hands you the grouped summary. The whole loop — navigate, wait, read, summarize — is a handful of tool calls.

When you need data in a precise shape rather than prose — to feed another step, or to write to a file — the agent can reach for safari_evaluate, which runs custom JavaScript on the page and returns whatever you build:

{
  "tool": "safari_evaluate",
  "arguments": {
    "expression": "JSON.stringify([...document.querySelectorAll('li')].map(li => li.innerText.trim()))"
  }
}

The agent writes that expression itself, against the structure it just saw in the snapshot — you don't hand-author selectors.

You might be thinking: GitHub has an API, why scrape the page? Fair. For GitHub specifically, the API is excellent. But the point generalizes. Most of the dashboards you stare at every day — your billing portal, your error tracker's specific filtered view, a client's analytics, the admin panel of some tool your company pays for — either have no usable API or would cost you an afternoon of OAuth setup to reach. With Safari MCP, "the page I'm already looking at" is the API. The agent reads what you can see, because it's using the browser you're seeing it in.

That's the capability headless automation can't match. Not speed, not features — access.

Handling the Tricky Parts

A first automation always looks easy. Three things tend to bite on the second one.

Tab Safety — The Agent Must not Hijack Your Tabs

This is the scariest failure mode: you're typing in a tab, the agent navigates that tab, and your work is gone. Safari MCP guards against it by stamping each automation tab with an identity marker — it uses window.name, which survives page navigations — and resolving "the agent's tab" through that marker on every call. If it can't positively identify its own tab, it refuses to act and raises a re-anchor error rather than guessing.

The practical rule for you: let the agent open its own tab with safari_new_tab, and it will stay in its lane. Don't point it at "the current tab" and assume.

Waiting for Dynamic Content

Modern pages render after load. If the agent reads too early, it reads an empty shell. Don't have it guess with fixed sleeps — use safari_wait_for, which polls for a selector or text until it appears or the timeout elapses:

{ "tool": "safari_wait_for", "arguments": { "selector": ".results-list", "timeout": 8000 } }

This is the single most common fix for "the automation works when I step through it slowly but fails when it runs."

Framework Forms

Set a React or Vue input's .value directly and the framework never notices — its internal state stays empty, and your "filled" form submits blank. Safari MCP's safari_fill and safari_fill_form use the native value setters and dispatch the input and change events the framework listens for, so React, Vue, Angular, and Svelte state all stay in sync:

{
  "tool": "safari_fill_form",
  "arguments": {
    "fields": [
      { "selector": "#email", "value": "jane@example.com" },
      { "selector": "#message", "value": "Looks great." }
    ]
  }
}

For framework-heavy pages where CSS selectors are fragile, go back to the snapshot refs from the previous section — pass { "ref": "0_9" } instead of { "selector": "#email" }. Refs survive re-renders; selectors don't.

None of these are exotic. They're just the difference between a demo and an automation you'd actually leave running.

Limitations: When Not to Use This

A tool tutorial that only lists strengths isn't worth much. Here's where Safari MCP is the wrong choice.

It's macOS-only, and that's structural. Safari MCP is built on WebKit and AppleScript. There's no Windows or Linux port coming, because the foundation doesn't exist on those platforms. If your agent runs in Linux CI, use Playwright.

It drives one Safari, on one Mac. This is browser automation for your machine — a coding agent working alongside you. It is not a fleet. If you need 50 parallel browsers scraping in a data center, that's a headless-Chromium-in-containers job, and Safari MCP is the wrong shape for it.

Cross-browser test suites should stay on Playwright. If you're writing end-to-end tests that must pass on Chrome, Firefox, and Safari, use the tool built for that. Safari MCP drives exactly one engine: WebKit.

It shares a browser with you. Because it uses your real Safari, the agent and you are in the same browser. That's the entire point — but it means you should let the agent work in its own tabs and not fight it for the same window.

The honest summary: Safari MCP is built for one specific situation — an AI agent doing real browser work on the Mac you're sitting at, against sites you're already logged into. In that situation it's hard to beat. Outside it, reach for the headless tools. Knowing which situation you're in is the actual skill.

Wrapping Up

You've gone from an AI agent that could only see code to one that can see the web — the real web, behind your real logins.

To recap what you did: you learned what MCP is and why browser automation belongs behind that interface. You saw why a native Safari engine beats a headless Chromium for an agent working on your Mac and you installed Safari MCP with one command and two settings. You ran a first read, and then you did the thing that actually matters — an automation inside a logged-in page, with no auth code at all. Finally, you saw the edges: tab safety, waiting for dynamic content, framework forms, and the cases where you should pick a different tool.

The bigger idea is worth holding onto. An AI agent is only as capable as the tools you connect to it. Giving it a browser — a real one — turns "write me code" into "go look at the staging site, find the bug, and tell me what's wrong." That's a different kind of collaborator.

Safari MCP is open source under the MIT license, and it exposes around 80 tools beyond the handful you used here — screenshots, network inspection, storage, accessibility audits, multi-tab workflows. The repository and full tool reference are at github.com/achiya-automation/safari-mcp. Point your agent at it and see what it does when it can finally look around.

And to be a more effective GitHub user, you'll need to know how to search within the platform.

This involves using qualifiers to efficiently filter through millions of repositories and billions of lines of code. Precise queries help you locate specific function definitions, projects, people, issues, pull requests, code, security vulnerabilities, or contribution opportunities.

In this tutorial, you'll learn how to use GitHub search, whether you're a beginner or a pro developer.

To enhance your learning, I've divided this article into two sections:

1. Basic Search Functionality

2. Advanced Search Functionality

What We'll Cover:

• What We’ll Cover:

• Basic Search Functionality

  • How to Search Globally

  • How to Do a Scoped Search (for a Particular Repo or Organization)

• Advanced Search Functionality

  • Search Qualifiers

  • How to Save Searches

  • How to Manage Saved Searches on GitHub

  • Why Do We Need GitHub Advanced Search?

• Conclusion

Basic Search Functionality

Basic search here refers to the most commonly used search functionalities that are fast and easy to use.

To start, click the GitHub search icon, type your query, and GitHub will display your results. With basic search, you can search globally across all of GitHub or narrow your search to a specific repository or organization.

How to Search Globally

To search on GitHub, click the search tab or press the / key to open the search bar.

To search globally (across all of GitHub), open the search input, type your query, and select "Search all of GitHub" from the dropdown menu or press enter.

After clicking the "Search all of GitHub" button, you'll be directed to a page displaying all results related to your query.

How to Do a Scoped Search (for a Particular Repo or Organization)

To search within a specific repository or organization, go to the repository or organization page, enter your query in the search field at the top, and press Enter.

For instance, if you're searching for a file name starting with "pnpm" in the frontendweb repository:

In the search bar, you'll see four suggestions: the first is "Search in this repository," the second is "Search in this organization," the third is "Search all of GitHub," and the last is the code section "Display similar files." Clicking a file opens it in the GitHub web editor.

Advanced Search Functionality

In addition to the GitHub search bar, you can search on GitHub using the advanced search page.

GitHub's advanced search allows you to find specific code, repositories, and issues. You can filter your searches by factors such as the number of stars, owners, forks, followers, programming language, and creation dates.

As you complete the advanced search fields, your query is automatically generated in the top search bar, and you can click on the Search button.

For a basic example, let's search for React on GitHub, including recent pull and push requests, issues, commits, discussions, and so on, related to ReactJS. We can use GitHub's advanced search functionality for this. Type "React" in the first input field as text and add the owner, in this case, Facebook, to find everything related to ReactJS in the Facebook organization or user.

After clicking on the Search button, you should see the following results page:

As you can see, GitHub's advanced search functionality lets you find specific code, repositories and issues using a powerful set of qualifiers and options. Let's talk more about qualifiers now.

Search Qualifiers

You can filter your search directly using various key qualifiers. We can divide these qualifiers into different sections:

Advanced Options

• From these owners: type the specific user's or organization's name, such as GitHub, Atom, Electron, Octokit, and so on.

• In these repositories: type the specific user's or organization's name, such as Facebook/React, Vercel/Next.js, and so on.

• Created on these dates: Specify the repository creation date, for example >2016-04-29, =2016-04-29, etc., to learn more, check out the Query for dates documentation.

• Written in this language: Select the specific language that matches repositories from lists: JavaScript, TypeScript, Rust, and so on, or what it’s written in.

Repository Options

• With this many stars: Type the number of stars in the stars: field to filter and find repositories by star count. You can apply comparisons like >1000 (more than 1000 stars) or =1000 (exactly 1000 stars) to narrow results based on popularity.

• With this many forks: Type the number of forks to filter and find repositories by fork count. You can apply comparisons like 100..1000 (find repos with 100 to 1000 forks), >1000 (more than 1000 forks), or =1000 (exactly 1000 forks) to narrow results based on popularity.

• Of this size: type the repository size in KB to filter and find repositories, for example, size of 10000 KB

• Pushed to: type the date to filter and find repositories, for example >2013-02-01 matches repositories with the word "react" that were pushed to after January 2013.

• With this license: Select the license to filter or find repositories based on license, for example, those licensed under the Apache License 2.0.

Code Options

• With this extension: type the extension, such as rb, py, or jpg, that you want to search on GitHub.

• In this path: Type the path to filter on GitHub to search for files by their location within a repository. For example, you can find a header.tsx file specifically inside the ./components folder by combining filename: with path:.

• With this file name: Type the file name, such as app, footer, or header, that you want to search on GitHub.

Issue Options

• In the state: Select the issue state (whether the issue is open or closed), for example, libraries state:open mentions:rajdeep matches open issues that mention @rajdeep with the word "libraries," or language:JavaScript state:open matches open issues in JavaScript repositories.

• With this many comments: Enter the comment number based on the comment count. You can filter the issue, for example, state:closed comments:>100 matches closed issues with more than 100 comments, or comments:500..1000 matches issues with comments ranging from 500 to 1,000.

• With the labels: Enter the label to filter or narrow your results by labels. Since issues can have multiple labels, you can list and add multiple label qualifiers for each issue.

  For example, first, label:bug label:resolved matches issues with the labels "bug" and "resolved." Second, label:bug,resolved matches issues with the label "bug" or the label "resolved." Third, example broken in:body -label:bug label:priority matches issues with the word "broken" in the body, that lack the label "bug," but do have the label "priority."

• Opened by the author: Enter the name or username to filter or find issues created by a user or integration account, or filter the issues based on the author.

  For example, author:rajdeep matches issues with the word "fixed" that were created by @rajdeep, or author:octocat matches issues created by the account named "octocat."

• Mentioning the users: Enter the name or username to find issues that mention the user. For example, fixed mentions:rajdeep matches issues with the word "fixed" that mention @rajdeep in the issue.

• Assigned to the users: Enter the name or username to find or filter issues based on the specific username assigned to the issue. For example, state:open assignee:rajdeep matches open issues that are assigned to @rajdeep.

• Updated before the date: Enter the date, filter issues based on the time of creation, or when they were last updated.

  For example language:c# created:<2011-01-01 state:open matches open issues that were created before 2011 in repositories written in C# or weird in:body updated:>=2013-02-01 matches issues with the word "weird" in the body that were updated after February 2013.

User Options

• With this full name: Enter a full name to filter repositories whose name includes “rajdeep singh” on GitHub.

• From this location: Enter a location to find users on GitHub. For example, location:russia language:javascript returns users based in Russia whose repositories are primarily written in JavaScript.

• With this many followers: Enter a follower count to filter users by popularity. For example, followers:>=1000 finds users with 1,000 or more followers, while followers:1..10 rajdeep returns users with 1–10 followers whose name includes “rajdeep” on GitHub.

• With this many public repositories: Enter a repository count to filter users by the number of public repositories they have. For example, repos:>10 finds users with more than 10 repositories, while repos:10..30 returns users who have between 10 and 30 public repositories on GitHub.

• Working in this language: Select the language to find users based on the primary languages of their repositories. For example, language:javascript location:russia returns users in Russia whose repositories are mostly written in JavaScript, while language:javascript fullname:rajdeep finds users with JavaScript repositories whose full name includes "rajdeep" on GitHub.

Wiki Options

• Updated before the date: Enter a date to filter wiki pages containing “next.js” that were last updated after 2016-01-01 in your GitHub wiki.

The best way to use advanced search qualifiers is to combine one or multiple qualifier/search options to achieve the best result.

How to Save Searches

I don't often use GitHub Advanced Search, but I used it to find open-source projects to learn from and contribute to. If you take a moment to fill in the information in GitHub Advanced Search, you can save the search for future use:

Enter the name and click the "Create saved search" button:

You can show a list of all your saved searches:

How to Manage Saved Searches on GitHub

To manage a saved search, open the search bar and type "saved:" in the search bar, then click the "Manage saved searches" button.

To edit a saved search, click the pencil icon next to it. To delete a saved search, click the trash icon.

Why Do We Need GitHub Advanced Search?

As mentioned, GitHub Advanced Search helps you find the best issues to contribute to in open source repositories.

For example, I'm an expert in Next.js and React.js, and I can use GitHub Advanced Search to locate suitable issues in open-source projects for contribution.

Even as a beginner developer, you can use GitHub Advanced Search to find "good first issues" labeled by maintainers, making it easier to contribute.

Conclusion

GitHub Advanced Search is versatile. t's not just for searching but also for researching recent issues, pull requests, and push requests that may be related to your query, repository, user, or anything else. My favorite use is finding open-source contribution opportunities with GitHub Advanced Search.

Millions of developers have published extensions to the Chrome Web Store, and building one is more approachable than you might think.

In this handbook you'll go from zero to a published Chrome extension using TypeScript, React, and Plasmo, a modern framework that handles the repetitive setup and configuration so you can focus on writing features instead of boilerplate.

Along the way you'll touch the real Chrome extension APIs that power production extensions: querying tabs, creating tab groups, and passing messages between different parts of an extension.

By the end you'll have working code, a mental model of how extensions are structured, and everything you need to publish your own ideas to the Chrome Web Store.

Table of Contents

• What is Plasmo?

• What You Will Build

• What You Will Learn

• Prerequisites

• Project Setup

• Understanding the Background Script

• Building the Popup UI

• Testing Your Extension

• Next Steps and Extension Ideas

• Deploying to Chrome Web Store

What is Plasmo?

Plasmo is an open-source framework for building browser extensions. Think of it as the equivalent of Create React App or Next.js, but for Chrome extensions.

Without Plasmo, building a Chrome extension requires manually writing a manifest.json file, wiring up build tooling, and configuring TypeScript and React yourself. Plasmo handles all of that.

A single command scaffolds a working project with TypeScript and React already configured. It reads your package.json and generates the manifest.json Chrome requires, so you never edit it directly.

Moreover, changes to your source files automatically rebuild and reload the extension in Chrome during development, and full type safety including types for Chrome's own APIs is available out of the box.

Plasmo doesn't hide the Chrome extension concepts from you. You still use chrome.tabs, chrome.runtime, and the rest of the Chrome APIs directly. It just removes the tedious scaffolding so you can start building immediately.

What You Will Build

In this tutorial, you'll build a Tab Grouper Chrome extension from scratch.

This extension automatically organizes your browser tabs by grouping them based on their website domain.

Example Use Case

Imagine you have 20 tabs open: 5 from GitHub, 4 from YouTube, 3 from Stack Overflow, and 8 from other websites.

With one click, the Tab Grouper extension will automatically create colored groups for each website, making it straightforward to find and manage your tabs.

What You Will Learn

By completing this tutorial, you'll get hands-on experience in three areas.

First, Chrome Extension Basics: how extensions work under the hood, the anatomy of an extension (manifest, background scripts, popups), and how to load and test extensions in Chrome during development.

Second, Chrome APIs: specifically chrome.tabs for managing browser tabs, chrome.tabGroups for creating and customizing tab groups, and chrome.runtime for passing messages between different parts of your extension.

Third, Modern Web Development tooling: TypeScript for type-safe JavaScript, React for building the popup UI, and the Plasmo framework that ties it all together.

Prerequisites

You don't need to be an expert in any of these, but you'll have the smoothest experience if you're comfortable with basic JavaScript or TypeScript and have a general understanding of HTML and CSS.

Some familiarity with React is helpful but not required. The pop-up component we'll build is simple enough to follow even if you're new to it.

On the software side, you'll need Node.js version 18 or higher (download here), Google Chrome, a code editor (VS Code is recommended), and pnpm as your package manager.

Verify Your Setup

Open your terminal and run these commands to confirm everything is installed:

node --version
# Should output v18.0.0 or higher

npm --version
# Should output 9.0.0 or higher

Getting Help

If you get stuck, review the complete code in the repository, consult the Chrome Extension documentation, or ask for help in the community forums.

Ready to Begin?

In the next section, you'll set up your development environment and create your first Chrome extension project.

Let's get started!

Project Setup

In this section, you'll use Plasmo to scaffold your Chrome extension project, then customize it for the Tab Grouper.

Rather than creating files manually, you'll let Plasmo generate a starter project with all required configuration, then explore what was created before customizing it for our needs.

Step 1: Install pnpm (Recommended)

Plasmo officially recommends pnpm for faster installs and better disk space usage. Check if you already have it:

pnpm --version

If you see a version number, skip to Step 2.

If you get "command not found", install it with:

npm install -g pnpm

Step 2: Create Your Extension Project

Run this command to create a new Plasmo project:

pnpm create plasmo tab-grouper

You'll see:

🟣 Creating a new Plasmo extension
📁 Project name: tab-grouper
? Extension description: (Give your extension a nice description)
? Author name: (Your Name)

Plasmo will then scaffold the project and install dependencies automatically. You might be prompted to enter a description and author name.

Fill these in however you like.

Step 3: Navigate to Your Project

cd tab-grouper

Step 4: Explore What Was Created

List the files that Plasmo generated:

ls -la

You should see something like this:

tab-grouper/
├── .git/                 # Git repository (already initialized!)
├── .github/              # GitHub Actions workflows
├── assets/
│   └── icon.png          # Default Plasmo icon 
├── node_modules/         # Dependencies (already installed!)
├── package.json          # Project configuration
├── popup.tsx             # Default popup 
├── .prettierrc.cjs       # Code formatting rules
├── .gitignore            # Git ignore rules
├── README.md             # Default readme
└── tsconfig.json         # TypeScript configuration

The key files to know about:

• assets/icon.png: The extension icon required by Chrome.

• package.json: Lists dependencies and scripts, and is where you configure the extension manifest.

• popup.tsx: The UI that appears when you click the extension icon.

• tsconfig.json: Contains TypeScript settings that are already correctly configured.

Step 5: Test the Default Extension

Make sure everything works before you customize it.

You can do this by starting the development server:

pnpm dev

You should see output like this:

🟣 Plasmo v0.90.5
🔴 The Browser Extension Framework
🔵 INFO   | Starting the extension development server...
🔵 INFO   | Building for target: chrome-mv3
🔵 INFO   | Loaded environment variables from: []
🟢 DONE   | Extension re-packaged in 1842ms! 🚀

View Extension:
📦 build/chrome-mv3-dev

Your extension is ready. Keep this terminal window open.

Plasmo watches for file changes and rebuilds automatically.

Step 6: Load the Extension in Chrome

Now load the extension into Chrome to test it:

1. Open Google Chrome

2. Go to chrome://extensions/

3. Enable Developer mode (toggle in top-right)

4. Click "Load unpacked"

5. Navigate to your project folder

6. Select the build/chrome-mv3-dev folder

7. Click "Select Folder"

Your extension should now appear in the list.

Step 7: Test the Default Popup

1. Click the puzzle piece icon in Chrome's toolbar

2. Find "tab-grouper" and pin it

3. Click the extension icon

You will see a default popup that says "Welcome to Plasmo!"

The extension is working. Now you can customize it.

Step 8: Update Extension Information

Open package.json in your editor. This file stores metadata about your project. name, version, description, dependencies, and scripts for building and running your extension.

Find these lines near the top:

{
  "name": "tab-grouper",
  "displayName": "tab-grouper",
  "version": "0.0.0",
  "description": "A basic Plasmo extension.",

Change them to:

{
  "name": "tab-grouper",
  "displayName": "Tab Grouper",
  "version": "1.0.0",
  "description": "A simple Chrome extension - group tabs by domain",

Save the file.

Step 9: Add Required Permissions (Critical!)

This is a critical step. Without permissions, your extension will fail with errors like:

TypeError: Cannot read properties of undefined (reading 'query')

Chrome extensions must declare which browser APIs they intend to use. In package.json, find the "manifest" section.

It looks like this:

"manifest": {
  "host_permissions": [
    "https://*/*"
  ]
}

Replace it with:

"manifest": {
  "permissions": [
    "tabs",
    "tabGroups"
  ]
}

Save the file. The tabs permission allows you to read tab information (required for chrome.tabs.query()), and tabGroups allows you to create and manage tab groups (required for chrome.tabGroups.update()).

Finding the right permissions for your own extensions:

The Chrome Extension Permissions Reference lists every available permission and what it unlocks.

Each API's documentation page also lists which permissions it requires, for example, the chrome.tabs API page specifies the "tabs" permission.

If you're using Plasmo, the Manifest Configuration docs explain how to add permissions through package.json.

As a general rule: if you're getting undefined errors when calling a Chrome API, a missing permission is the first thing to check.

Step 10: Verify Hot Reload Works

Plasmo automatically reloads your extension when you save changes.

Check the terminal where pnpm dev is running. After saving package.json you should see something like:

🔄 Reloading extension...
✅ Ready in 0.8s

Your project is now ready: a working extension loaded in Chrome, a development server running with hot reload, and the required permissions in place.

Leave the dev server running and the extension loaded as you work through the next sections. Your changes will reload automatically.

Section Summary

In this section you installed pnpm, scaffolded a new extension with pnpm create plasmo, explored the generated project structure, started the development server, loaded the extension in Chrome, and updated the extension metadata and permissions.

Next: You'll create the background script that handles the tab grouping logic.

Understanding the Background Script

The background script is the heart of your extension. It runs persistently behind the scenes and contains the core logic.

In this case, the code that groups your tabs by domain.

What is a Background Script?

A background script runs continuously even when the popup is closed.

It can listen to browser events like tabs opening, closing, or updating, perform tasks that don't require direct user interaction, and communicate with other parts of the extension by passing messages.

Think of it as the server-side of your extension. The popup is just a UI that talks to it.

Step 1: Create background.ts

Plasmo's scaffolding didn't create a background script by default, so you'll create this file from scratch. Create a new file called background.ts in your project root (the same level as popup.tsx):

export {}

// Background script - runs in the background and handles tab grouping logic

console.log("Tab Grouper background script loaded!")

// Listen for messages from the popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

The export {} at the top is required by Plasmo to treat this file as a module. Without it you may get errors about conflicting global variable declarations.

The console.log will help you verify the script loaded correctly (you'll see it in the extension's DevTools console). chrome.runtime.onMessage sets up a listener so the background script can receive instructions from the popup.

When it receives a "GROUP_TABS" message, it calls the grouping function.

You can read more about this messaging pattern in the Chrome Extensions documentation.

Step 2: Implement Tab Grouping Logic

Now add the main grouping function below the message listener:

async function groupTabsByDomain() {
  try {
    // Step 1: Get all tabs in the current window
    const tabs = await chrome.tabs.query({ currentWindow: true })

    // Step 2: Create a Map to organize tabs by domain
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    // Step 3: Loop through each tab and group by domain
    tabs.forEach(tab => {
      // Skip tabs without URLs
      if (!tab.url) return

      // Extract the domain from the URL
      const domain = getDomainFromUrl(tab.url)

      // Skip invalid domains (like chrome:// pages)
      if (!domain) return

      // Add tab to the appropriate domain group
      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    // Step 4: Create tab groups for each domain (only if 2+ tabs)
    for (const [domain, domainTabs] of domainGroups) {
      // Skip domains with only 1 tab
      if (domainTabs.length < 2) continue

      // Get all tab IDs
      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      // Create the tab group
      const groupId = await chrome.tabs.group({ tabIds })

      // Customize the group with a title and color
      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain) // Randomized Tab Group colors.
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

The function starts by querying all tabs in the current window, then iterates over them to build a Map keyed by domain name.

Once every tab has been sorted into a domain bucket, it loops through the map and calls chrome.tabs.group() for any domain that has two or more tabs, then immediately customizes the resulting group with a title and color.

Domains with only a single tab are skipped. There's no point grouping a lone tab.

Step 3: Extract Domain Helper

Add a helper function to pull the hostname out of a URL:

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)

    // Skip Chrome internal pages (chrome://, chrome-extension://)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }

    // Remove "www." prefix and return the hostname
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    // Return null if URL is invalid
    return null
  }
}

new URL(url) gives us a structured object to work with rather than string-parsing the URL manually.

The protocol check filters out Chrome's internal pages like chrome://extensions and chrome://settings, which extensions can't access.

The .replace(/^www\./, "") ensures that www.github.com and github.com are treated as the same domain rather than two separate groups.

The whole thing is wrapped in a try-catch so malformed URLs simply return null and get skipped.

In practice: https://www.github.com/user/repo becomes github.com, https://youtube.com/watch?v=123 becomes youtube.com, and chrome://extensions returns null.

Step 4: Color Assignment Helper

Add a function to deterministically assign a color to each domain:

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  // Available colors in Chrome
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  // Create a simple hash from the domain name
  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  // Return a color based on the hash
  return colors[Math.abs(hash) % colors.length]
}

Chrome supports eight colors for tab groups. Rather than assigning them randomly (which would change every time you group), this function hashes the domain name to a number and uses the modulo operator to pick a consistent index into the color array.

The result is that github.com always gets the same color across sessions, while different domains are likely to get different colors.

Complete background.ts File

Your complete background.ts should look like this:

export {}

console.log("Tab Grouper background script loaded!")

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "GROUP_TABS") {
    groupTabsByDomain()
    sendResponse({ success: true })
  }
  return true
})

async function groupTabsByDomain() {
  try {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const domainGroups = new Map<string, chrome.tabs.Tab[]>()

    tabs.forEach(tab => {
      if (!tab.url) return
      const domain = getDomainFromUrl(tab.url)
      if (!domain) return

      if (!domainGroups.has(domain)) {
        domainGroups.set(domain, [])
      }
      domainGroups.get(domain)!.push(tab)
    })

    for (const [domain, domainTabs] of domainGroups) {
      if (domainTabs.length < 2) continue

      const tabIds = domainTabs
        .map(t => t.id!)
        .filter(id => id !== undefined)

      if (tabIds.length === 0) continue

      const groupId = await chrome.tabs.group({ tabIds })

      await chrome.tabGroups.update(groupId, {
        title: domain,
        color: getColorForDomain(domain)
      })
    }

    console.log(`Successfully grouped ${domainGroups.size} domains`)
  } catch (error) {
    console.error("Error grouping tabs:", error)
  }
}

function getDomainFromUrl(url: string): string | null {
  try {
    const urlObj = new URL(url)
    if (urlObj.protocol === "chrome:" || urlObj.protocol === "chrome-extension:") {
      return null
    }
    return urlObj.hostname.replace(/^www\./, "")
  } catch {
    return null
  }
}

function getColorForDomain(domain: string): chrome.tabGroups.ColorEnum {
  const colors: chrome.tabGroups.ColorEnum[] = [
    "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"
  ]

  let hash = 0
  for (let i = 0; i < domain.length; i++) {
    hash = domain.charCodeAt(i) + ((hash << 5) - hash)
  }

  return colors[Math.abs(hash) % colors.length]
}

Testing the Background Script

If your development server isn't already running from the previous section, start it:

pnpm dev

To verify the background script loaded correctly, go to chrome://extensions, find "Tab Grouper Tutorial", and click the "service worker" link.

A DevTools console will open and you should see "Tab Grouper background script loaded!" confirming everything is wired up.

Building the Popup UI

The popup is the small window that appears when a user clicks your extension icon in the Chrome toolbar.

It can display information, provide buttons for actions, and show settings.

In this section you'll build a React-based popup that shows live tab statistics and triggers the grouping logic in the background script.

Step 1: Replace popup.tsx

When you ran pnpm create plasmo, a default popup.tsx was created that just displays a welcome message.

Open that file and replace all of its contents with this starting skeleton:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  return (
    <div>
      <h2>Tab Grouper</h2>
      <button>Group Tabs</button>
    </div>
  )
}

export default IndexPopup

Save the file and the extension will automatically reload.

The three state variables track the number of open tabs, the number of existing groups, and whether a grouping operation is currently in progress.

That last one lets us disable the button and show a loading state so users can't trigger multiple groupings at once.

Step 2: Load Statistics

Now add the logic to load tab and group counts when the popup opens. Add this inside the IndexPopup function, right after the state declarations:

// Load tab statistics when popup opens
useEffect(() => {
  loadStats()
}, [])

async function loadStats() {
  const tabs = await chrome.tabs.query({ currentWindow: true })
  const groups = await chrome.tabGroups.query({
    windowId: chrome.windows.WINDOW_ID_CURRENT
  })

  setTabCount(tabs.length)
  setGroupCount(groups.length)
}

The useEffect with an empty dependency array [] runs once when the component first mounts. In other words, every time the popup opens.

It calls loadStats, which queries Chrome for the current window's tabs and groups, then updates the state variables with the counts.

Step 3: Trigger Tab Grouping

Add the handler that sends a message to the background script when the button is clicked:

async function handleGroupTabs() {
  setIsGrouping(true)

  // Send message to background script
  await chrome.runtime.sendMessage({ type: "GROUP_TABS" })

  // Refresh statistics
  await loadStats()
  setIsGrouping(false)
}

chrome.runtime.sendMessage delivers the { type: "GROUP_TABS" } message to the listener we set up in background.ts.

After the background script finishes, we reload the statistics so the group count updates immediately, then re-enable the button.

Step 4: Build the UI

Replace the placeholder return statement with this complete, styled version:

return (
  <div style={{
    width: 300,
    padding: 20,
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
  }}>
    {/* Header */}
    <div style={{ marginBottom: 20 }}>
      <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
        🗂️ Tab Grouper
      </h2>
      <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
        Organize your tabs by domain
      </p>
    </div>

    {/* Statistics */}
    <div style={{
      display: "flex",
      gap: 12,
      marginBottom: 20,
      padding: 12,
      background: "#f5f5f5",
      borderRadius: 8
    }}>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
          {tabCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Open Tabs
        </div>
      </div>
      <div style={{ flex: 1 }}>
        <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
          {groupCount}
        </div>
        <div style={{ fontSize: 12, color: "#666" }}>
          Tab Groups
        </div>
      </div>
    </div>

    {/* Group Button */}
    <button
      onClick={handleGroupTabs}
      disabled={isGrouping}
      style={{
        width: "100%",
        padding: "12px 16px",
        fontSize: 14,
        fontWeight: 500,
        color: "white",
        background: isGrouping ? "#ccc" : "#0066ff",
        border: "none",
        borderRadius: 8,
        cursor: isGrouping ? "not-allowed" : "pointer",
        transition: "background 0.2s"
      }}
    >
      {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
    </button>

    {/* Footer */}
    <div style={{
      marginTop: 16,
      padding: 12,
      fontSize: 12,
      color: "#666",
      background: "#fff9e6",
      borderRadius: 6,
      border: "1px solid #ffe066"
    }}>
      💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
    </div>
  </div>
)

The UI has four parts: a header with the extension title and a short description, a statistics box showing the live tab and group counts side by side, the main action button (which grays out and changes text to "Grouping..." while work is in progress), and a tip box at the bottom.

This tutorial uses inline styles for simplicity. In a production extension, you'd likely reach for CSS modules, Tailwind, or styled-components instead.

Complete popup.tsx File

Your complete popup.tsx should look like this:

import { useState, useEffect } from "react"

function IndexPopup() {
  const [tabCount, setTabCount] = useState(0)
  const [groupCount, setGroupCount] = useState(0)
  const [isGrouping, setIsGrouping] = useState(false)

  useEffect(() => {
    loadStats()
  }, [])

  async function loadStats() {
    const tabs = await chrome.tabs.query({ currentWindow: true })
    const groups = await chrome.tabGroups.query({
      windowId: chrome.windows.WINDOW_ID_CURRENT
    })

    setTabCount(tabs.length)
    setGroupCount(groups.length)
  }

  async function handleGroupTabs() {
    setIsGrouping(true)
    await chrome.runtime.sendMessage({ type: "GROUP_TABS" })
    await loadStats()
    setIsGrouping(false)
  }

  return (
    <div style={{
      width: 300,
      padding: 20,
      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
    }}>
      <div style={{ marginBottom: 20 }}>
        <h2 style={{ margin: 0, fontSize: 20, fontWeight: 600 }}>
          🗂️ Tab Grouper
        </h2>
        <p style={{ margin: "8px 0 0", fontSize: 13, color: "#666" }}>
          Organize your tabs by domain
        </p>
      </div>

      <div style={{
        display: "flex",
        gap: 12,
        marginBottom: 20,
        padding: 12,
        background: "#f5f5f5",
        borderRadius: 8
      }}>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#333" }}>
            {tabCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Open Tabs
          </div>
        </div>
        <div style={{ flex: 1 }}>
          <div style={{ fontSize: 24, fontWeight: 600, color: "#0066ff" }}>
            {groupCount}
          </div>
          <div style={{ fontSize: 12, color: "#666" }}>
            Tab Groups
          </div>
        </div>
      </div>

      <button
        onClick={handleGroupTabs}
        disabled={isGrouping}
        style={{
          width: "100%",
          padding: "12px 16px",
          fontSize: 14,
          fontWeight: 500,
          color: "white",
          background: isGrouping ? "#ccc" : "#0066ff",
          border: "none",
          borderRadius: 8,
          cursor: isGrouping ? "not-allowed" : "pointer",
          transition: "background 0.2s"
        }}
      >
        {isGrouping ? "Grouping..." : "🗂️ Group Tabs by Domain"}
      </button>

      <div style={{
        marginTop: 16,
        padding: 12,
        fontSize: 12,
        color: "#666",
        background: "#fff9e6",
        borderRadius: 6,
        border: "1px solid #ffe066"
      }}>
        💡 <strong>Tip:</strong> This will group all tabs in this window by their website domain.
      </div>
    </div>
  )
}

export default IndexPopup

Testing Your Extension

Now that you have both the background script and popup UI built, it's time to verify that everything works together in Chrome.

Step 1: Make Sure the Dev Server is Running

If pnpm dev isn't already running from an earlier step, start it now:

pnpm run dev # or pnpm dev

Plasmo will build the extension into build/chrome-mv3-dev and watch for changes.

Step 2: Load the Extension in Chrome

If you haven't already loaded the extension, go to chrome://extensions/, enable Developer mode, click Load unpacked, and select the build/chrome-mv3-dev folder.

Once loaded you should see the extension listed with the name "Tab Grouper Tutorial", version "1.0.0", and status Enabled.

Step 3: Pin the Extension

Click the puzzle piece icon in the Chrome toolbar, find "Tab Grouper Tutorial", and click the pin icon to keep it visible.

The extension icon will now appear directly in your toolbar.

Step 4: Test the Extension

Test 1: Open Multiple Tabs

Open several tabs across a few domains so there's something to group:

1. https://github.com/topics, https://github.com/trending, https://github.com/explore

2. https://www.youtube.com/ and https://www.youtube.com/trending

3. https://stackoverflow.com/questions and https://stackoverflow.com/tags

Have at least 7 tabs open.

Test 2: Group the Tabs

Click the Tab Grouper extension icon. The popup should appear showing your open tab count (7 or more) and group count (probably 0).

Click "Group Tabs by Domain" and watch your tabs get organized into colored groups.

Test 3: Verify Groups

After clicking the button, GitHub tabs should be grouped together with a label like "github.com" and a consistent color, and YouTube tabs similarly.

Click the extension icon again, the group count should now show 2, while the tab count stays the same.

Step 5: Debug the Extension

If something doesn't work, Chrome's DevTools are your best friend.

To inspect the background script, go to chrome://extensions/, find your extension, and click the "service worker" link.

A DevTools console opens where you can look for the "Tab Grouper background script loaded!" message and any error output in red.

To inspect the popup, right-click the extension icon and select "Inspect popup". This opens DevTools for the popup specifically — check the Console tab for any errors there.

If nothing happens when you click the button, check the background script console for errors, confirm you have at least 2 tabs from the same domain, and verify the message is being sent (look in the popup console for any sendMessage failures).

If tabs aren't grouping, double-check that you added the tabs and tabGroups permissions to package.json and reloaded the extension after saving.

If you see "Extension cannot access chrome://...", that's expected behavior — extensions can't interact with Chrome's internal pages and the code skips them intentionally.

Step 6: Hot Reloading

One of the benefits of Plasmo is hot reloading, which allows you to update code in a running app instantly without needing to restart it manually.

Open popup.tsx, change the header emoji from 🗂️ to 📁, and save.

The extension reloads automatically.

Click the icon and you'll see the updated emoji immediately.

Hot reloading is advantageous because it speeds up development by letting you see changes in real time.

You can change the emoji back afterward if you'd like to keep the extension consistent with the rest of the tutorial examples and screenshots.

Step 7: Test Edge Cases

It's worth testing a few scenarios to make sure the extension handles them gracefully.

If you close all tabs except one and click "Group Tabs", nothing should happen. The extension requires at least two tabs from the same domain to form a group. Opening chrome://extensions and chrome://settings and then grouping should also do nothing, since those pages are filtered out.

If you have one tab from reddit.com and one from freecodecamp.org, each domain appearing only once, no groups should be created.

Step 8: Production Build

When you're ready to share your extension, run:

pnpm run build

This creates a production-optimized version in build/chrome-mv3-prod, minified JavaScript, no development-only code, and smaller file size.

To verify the production build, go to chrome://extensions/, remove the development version, click "Load unpacked", and select build/chrome-mv3-prod. Test thoroughly before publishing.

The extension is lightweight (under 100 KB), only runs when you click the button, and has no background processes when idle.

Next Steps and Extension Ideas

Congratulations on building your first Chrome extension!

You now have a working tool that groups tabs by domain with one click, shows live statistics about open tabs and groups, and is built on modern tooling: TypeScript, React, and Plasmo following Chrome extension best practices.

The extension is a solid foundation. Here are some ideas for where to take it next.

1. Auto-Grouping

Instead of requiring a button click, you could automatically group new tabs as they're opened. You'd listen for the chrome.tabs.onCreated event in background.ts and trigger groupTabsByDomain() with a short delay to let the page URL load:

// In background.ts
chrome.tabs.onCreated.addListener(async (tab) => {
  // Wait a bit for the URL to load
  setTimeout(() => {
    groupTabsByDomain()
  }, 2000)
})

This gets into event listeners, asynchronous timing, and thinking carefully about when to fire — a good next step for understanding how background scripts can be more proactive.

2. Keyboard Shortcuts

You can trigger grouping without even opening the popup by adding a keyboard shortcut. Add a commands section to the manifest in package.json:

"manifest": {
  "commands": {
    "group-tabs": {
      "suggested_key": {
        "default": "Ctrl+Shift+G",
        "mac": "Command+Shift+G"
      },
      "description": "Group tabs by domain"
    }
  }
}

Then listen for the command in background.ts:

chrome.commands.onCommand.addListener((command) => {
  if (command === "group-tabs") {
    groupTabsByDomain()
  }
})

3. Category-Based Grouping

Rather than grouping by raw domain, you could group by category — putting GitHub, Stack Overflow, and npm together in a "Dev" group, for instance:

const categories = {
  social: ["facebook.com", "twitter.com", "instagram.com"],
  shopping: ["amazon.com", "ebay.com", "etsy.com"],
  dev: ["github.com", "stackoverflow.com", "npmjs.com"]
}

function getCategoryForDomain(domain: string): string {
  for (const [category, domains] of Object.entries(categories)) {
    if (domains.includes(domain)) {
      return category
    }
  }
  return "other"
}

4. Options Page

Plasmo makes it trivial to add a settings page by creating an options.tsx file.

This is where you'd let users toggle auto-grouping, choose between domain and category mode, or configure their own category mappings.

It's a good introduction to the Chrome Storage API and persisting user preferences.

function OptionsPage() {
  return (
    <div>
      <h1>Tab Grouper Settings</h1>
      <label>
        <input type="checkbox" />
        Enable auto-grouping
      </label>
      <label>
        <input type="checkbox" />
        Group by category instead of domain
      </label>
    </div>
  )
}

5. Tab Age Tracking

You could track when each tab was created and surface tabs that have been sitting untouched for a week or more, a nice way to encourage tab hygiene:

// Track tab creation times
const tabCreationTimes = new Map<number, number>()

chrome.tabs.onCreated.addListener((tab) => {
  if (tab.id) {
    tabCreationTimes.set(tab.id, Date.now())
  }
})

// Find old tabs (e.g., > 7 days)
function getOldTabs(): chrome.tabs.Tab[] {
  const sevenDaysAgo = Date.now() - (7 * 24 * 60 * 60 * 1000)
  return tabs.filter(tab => {
    const created = tabCreationTimes.get(tab.id!)
    return created && created < sevenDaysAgo
  })
}

6. Search Within Groups

A search bar in the popup would let users filter their open tabs by title, making it easy to jump to a specific tab:

const [searchQuery, setSearchQuery] = useState("")

const filteredTabs = tabs.filter(tab =>
  tab.title?.toLowerCase().includes(searchQuery.toLowerCase())
)

7. Export/Import Groups

You could let users save their current tab groups to a JSON file and restore them later. Useful for preserving a working session across restarts:

// Export
async function exportGroups() {
  const groups = await chrome.tabGroups.query({})
  const data = JSON.stringify(groups)
  const blob = new Blob([data], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  chrome.downloads.download({ url, filename: 'tab-groups.json' })
}

// Import
async function importGroups(file: File) {
  const text = await file.text()
  const groups = JSON.parse(text)
  // Restore groups...
}

8. Group Statistics Dashboard

An expanded popup could show browsing analytics, total tabs opened today, most-visited domain, and more:

function Statistics() {
  const [stats, setStats] = useState({
    totalTabs: 0,
    totalGroups: 0,
    mostUsedDomain: "",
    tabsToday: 0
  })

  return (
    <div>
      <h3>Browsing Statistics</h3>
      <p>Total tabs opened today: {stats.tabsToday}</p>
      <p>Most visited domain: {stats.mostUsedDomain}</p>
    </div>
  )
}

Learning Resources

If you want to go deeper, the official Chrome Extension docs are excellent and cover every API in detail.

The Chrome Extension Samples repository on GitHub has dozens of real examples to learn from. For Plasmo-specific questions, the Plasmo documentation and example repository are the best starting points, and the community is active on Plasmo Discord.

The React docs and TypeScript docs are worth bookmarking as reference material, and the React TypeScript Cheatsheet is handy when you're unsure about specific type patterns.

For community support, Stack Overflow's chrome-extension tag is well-monitored, and r/chrome_extensions on Reddit is a friendly place to ask questions.

Deploying to Chrome Web Store

Now that you've built and tested your extension, here's how to publish it and share it with the world.

What You'll Need

Before you can publish, you'll need a completed and tested extension, a Google account, a $5 USD one-time developer registration fee, and some store assets such as icons, screenshots, and a written description.

The $5 fee is a one-time charge (not annual) that Google uses to verify developer identity and reduce spam. It covers unlimited extension submissions and is processed immediately via Google Payments.

Step 1: Create a Production Build

Build your extension for production if you didn't do this before:

cd tab-grouper-tutorial
npm run build

This creates an optimized version in build/chrome-mv3-prod/. The production build minifies JavaScript and CSS for a smaller file size, strips out development-only code and console logs, and optimizes assets for faster loading.

Before uploading, load build/chrome-mv3-prod/ as an unpacked extension and test all features one more time to confirm nothing broke in the build process.

Step 2: Create Store Assets

Extension Icons

You'll need icons in three sizes: 128×128 pixels for the main store listing (required), 48×48 for the extension management page, and 16×16 for use as a favicon.

All should be PNG files with transparent backgrounds. Keep the design simple and recognizable at small sizes. Avoid putting text in the 16×16 version.

Figma is free and works well for this, as does Canva or GIMP.

Screenshots

Upload between 1 and 5 screenshots at either 1280×800 or 640×400 pixels (PNG or JPEG).

Show the extension in actual use rather than mockups. The popup with statistics, tabs being grouped, and the before/after state all work well.

Adding annotations to highlight key features helps users understand what they're looking at.

Promotional Images (Optional)

If you want to be featured on the store, you can also upload a small tile (440×280), large tile (920×680), and marquee image (1400×560). These are only needed if Google chooses to promote your extension.

Demo Video (Optional)

A short YouTube video (30–60 seconds) showing the extension in action can significantly increase conversions. Link to it in your store listing.

Step 3: Write Your Store Listing

Extension Name (45 character limit): Be clear and descriptive. "Tab Grouper - Organize Tabs by Domain" works well. Avoid keyword stuffing or excessive punctuation.

Summary (132 character limit): This is what appears in search results. Lead with what the extension does: "Automatically organize browser tabs by domain. One-click grouping keeps your workspace clean and productive."

Detailed Description (16,000 character limit): Start with what the extension does, list features clearly, explain how to use it, address privacy, and provide contact information. Here's a template you can adapt:

## What is Tab Grouper?

Tab Grouper automatically organizes your browser tabs by grouping them based on their website domain. No more hunting through dozens of tabs - everything is neatly organized.

## Features

- ✅ One-click tab grouping
- ✅ Automatic color-coding by domain
- ✅ Real-time statistics
- ✅ Works with all websites
- ✅ Lightweight and fast

## How to Use

1. Click the Tab Grouper icon in your toolbar
2. Click "Group Tabs by Domain"
3. Your tabs are instantly organized

## Why You Need This

If you regularly have numerous tabs open, finding the right one can waste valuable time. Tab Grouper solves this by automatically organizing tabs into colored groups, making navigation quick and straightforward.

## Privacy

This extension does not collect any personal data. It only accesses tab information locally to perform grouping. No data is sent to external servers.

## Support

Found a bug or have a suggestion? Contact us at support@example.com

Category: Choose Productivity for Tab Grouper. You can add additional languages later if you want to localize the listing.

Step 4: Register as a Chrome Web Store Developer

Go to the Chrome Web Store Developer Dashboard, sign in with your Google account, accept the Developer Agreement, and pay the $5 registration fee. Your account is activated within minutes.

Step 5: Submit Your Extension

In the Developer Dashboard, click "New Item" and upload your extension. You can either manually zip the build/chrome-mv3-prod/ folder or use Plasmo's package command:

# Option 1: Manual zip
cd build/chrome-mv3-prod
zip -r ../../tab-grouper.zip .

# Option 2: Use Plasmo package command
cd tab-grouper-tutorial
npm run package

Once uploaded, fill in all four sections of the store listing form: Product details (name, summary, description, category, language), Graphic assets (icon and screenshots), Privacy practices (see below), and Distribution (visibility, regions, pricing).

Single Purpose Description

Chrome requires each extension to have a single, clearly stated purpose. For Tab Grouper: "This extension organizes browser tabs by grouping them based on their domain name, helping users manage multiple open tabs efficiently."

Permission Justification

You'll need to justify each permission you declared. For tabs: "The tabs permission is required to read tab URLs and titles in order to group them by domain." For tabGroups: "The tabGroups permission is required to create and manage tab groups for organization."

Privacy Policy

Even though Tab Grouper doesn't collect personal data, Chrome may require a privacy policy. Host one on GitHub Pages or your personal website and link to it. Here's a minimal template:

# Privacy Policy for Tab Grouper

## Data Collection
Tab Grouper does not collect, store, or transmit any personal data.

## Permissions
- **tabs**: Used only to read tab URLs for grouping purposes
- **tabGroups**: Used only to create and manage tab groups

## Local Processing
All tab grouping happens locally in your browser. No data is sent to external servers.

## Contact
For questions: your-email@example.com

Last updated: [Current Date]

Step 6: Submit for Review

Before clicking submit, run through this checklist:

• Production build tested thoroughly

• All store assets uploaded (icon + at least one screenshot)

• Description is clear and accurate

• Permissions are justified

• Privacy policy is linked

• Extension name is descriptive

When you're ready, click "Submit for review", confirm your details, and click "Publish". Your extension enters the review queue.

Step 7: The Review Process

Google typically reviews extensions within 1–3 business days for straightforward submissions, though complex extensions or first submissions can take up to a week. Reviewers check that the extension works as described, that permissions are justified, that there's no malicious code, and that the listing complies with Chrome Web Store policies.

You can track your status in the Developer Dashboard: Pending review → In review → Approved or Rejected. If rejected, Google will email you specific reasons and instructions for resubmitting.

The most common rejection reasons are insufficient permission justification, misleading descriptions, missing privacy policies, and requesting more permissions than necessary. Address each point in the rejection email, update your submission, and resubmit.

Step 8: After Approval

Once approved, your extension is live at https://chrome.google.com/webstore/detail/[extension-id]. Share the link on social media, write a blog post, post to Reddit (r/chrome, r/chrome_extensions), or submit to Product Hunt to drive installs.

The Developer Dashboard gives you ongoing analytics — total and weekly installs, reviews and ratings, impressions, and uninstall counts. Check it regularly, especially in the first week. Respond to reviews (particularly negative ones), thank users for positive feedback, and use reported bugs to prioritize future updates.

Step 9: Publishing Updates

When you fix bugs or add features, bump the version number in package.json (following Semantic Versioning — patch for bug fixes, minor for new features, major for breaking changes), run npm run build, and upload the new package through the Developer Dashboard's Package tab. Updates are typically reviewed faster than initial submissions, often within 24 hours.

Step 10: Managing Your Extension Long-Term

The Chrome Web Store provides built-in analytics, but you can also add Google Analytics if you need more detail.

For user support, an email address in the description or a GitHub issues page both work well. As you add features, keep the description updated and maintain a changelog so users know what changed and when. Responding to user questions and reviews goes a long way toward building a loyal base of users who'll recommend the extension to others.

Troubleshooting Common Publishing Issues

"Package is invalid" on upload: Make sure you zipped the contents of build/chrome-mv3-prod/ rather than the folder itself, and verify the generated manifest.json is valid JSON.

Rejection: Permissions Not Justified: In the "Permission justification" field, be specific about which feature requires each permission and what would break without it.

Rejection: Single Purpose Unclear: Rewrite the single purpose description to focus on one main function, stated plainly.

Low installation rate after launch: Poor screenshots are often the culprit — they're the first thing most users look at. Make sure they clearly show the extension solving a real problem. Building even a small number of early reviews also makes a big difference to new visitors.

Alternative Distribution

The Chrome Web Store is the right choice for most public extensions. If you're building an internal tool, an Unlisted extension (accessible only via direct link, not searchable) is a good option.

If you need to restrict it to users in a specific Google Workspace organization, a Private extension is available for that. Self-hosting and sideloading is possible but requires users to enable Developer Mode manually, so it's only practical for very technical audiences.

Congratulations!

You've gone from an empty folder to a live Chrome extension on the Web Store. Along the way you learned how extensions are structured, how background scripts and popups communicate, how Chrome's tab APIs work, and how to navigate the publishing process end to end.

More than any specific API or configuration detail, the most important thing you've built is a mental model for how extensions work and that transfers directly to any extension idea you want to build next.

Keep building, keep learning, and keep shipping!

That is the problem Context Hub is trying to solve.

Context Hub (chub) gives coding agents curated, versioned documentation and skills that they can search and fetch through a CLI. It also gives them two learning loops: local annotations for agent memory and feedback for maintainers.

In this tutorial, you'll learn how the official chub workflow works, how Context Hub organizes docs and skills, how annotations and feedback create a memory loop, and how to build a companion relevance engine that improves retrieval without breaking the upstream content model.

This tutorial uses two public repositories side by side:

• the official upstream project: andrewyng/context-hub

• the companion implementation for this article: natarajsundar/context-hub-relevance-engine

I've also opened a corresponding upstream pull request from my fork to the main project. If you want to track that work from the article, use the upstream pull request list filtered by author: andrewyng/context-hub pull requests by natarajsundar.

What We'll Build

By the end of this tutorial, you'll have:

• a clear mental model for how Context Hub works

• a working local install of the official chub CLI

• a repeatable workflow for search, fetch, annotations, and feedback

• a companion repo that adds an additive reranking layer on top of a Context-Hub-style content tree

• a small benchmark and local comparison UI you can run end to end

• a clear bridge between the companion repo and the smaller upstream PR

Prerequisites

Before you start, make sure you have:

• Node.js 18 or newer

• npm

• comfort with the terminal

• basic familiarity with Markdown

Table of Contents

1. How to Understand Context Hub

2. How to Understand the Official Repo, the Companion Repo, and the Upstream PR

3. How to Install and Use the Official CLI

4. How to Understand Docs, Skills, and the Content Layout

5. How to Use Incremental Fetch and Layered Sources

6. How to Use Annotations and Feedback to Create a Memory Loop

7. How to See Where Relevance Still Misses

8. How the Companion Relevance Engine Improves Retrieval

9. How to Run the Companion Repo End to End

10. How to Read the Benchmark Honestly

11. How to Connect the Companion Repo to the Upstream PR

12. Conclusion

13. Sources

How to Understand Context Hub

Context Hub is easiest to understand as a workflow for turning fast-moving documentation into a reliable input for coding agents.

Instead of asking an agent to rely on whatever it remembers from training data, you give it a predictable contract:

1. search for the right entry

2. fetch the right doc or skill

3. write code against that curated content

4. save local lessons as annotations

5. send doc-quality feedback back to maintainers

That system boundary matters.

It makes the agent easier to audit, easier to improve, and easier to extend. It also keeps the interface small enough that you can reason about where the failures happen. If the agent still misses the answer, you can ask whether the problem happened during search, fetch, context selection, or generation.

How to Understand the Official Repo, the Companion repo, and the Upstream PR

This tutorial is intentionally split across two codebases and one contribution path.

The official upstream project, andrewyng/context-hub, is the source of truth for the real CLI, the content model, and the documented workflows. That's the codebase you should use to learn how chub works today.

The companion repository, natarajsundar/context-hub-relevance-engine, is where the relevant ideas in this article are made concrete. It's a companion implementation, not a replacement product. Its job is to make retrieval tradeoffs visible, measurable, and easy to run locally.

The upstream PR is the bridge between those two worlds. The companion repo is where you can iterate faster on benchmarks, reranking, and the comparison UI. The upstream PR is where the smallest reviewable slices can be proposed back to the main project. You can track that thread here: upstream PR search filtered by author.

That three-part framing keeps the article honest:

• use the upstream repo to understand the current system

• use the companion repo to explore relevant improvements end to end

• use the upstream PR to show how a larger idea can be broken into reviewable pieces

How to Install and Use the Official CLI

The official quick start is intentionally small.

npm install -g @aisuite/chub

Once the CLI is installed, you can search for what is available and fetch a specific entry:

chub search openai
chub get openai/chat --lang py

That's the happy path, but it helps to think through the request flow.

In practice, the most useful detail is that the CLI is designed for the agent to use, not just for the human to use by hand.

That's why the upstream CLI also ships a get-api-docs skill. For example, if you use Claude Code, you can copy the skill into your local project like this:

mkdir -p .claude/skills
cp $(npm root -g)/@aisuite/chub/skills/get-api-docs/SKILL.md \
  .claude/skills/get-api-docs.md

That step teaches the agent a retrieval habit:

Before you write code against a third-party SDK or API, use chub instead of guessing.

That behavioral rule is often as important as the docs themselves.

How to Understand Docs, Skills, and the Content Layout

Context Hub separates content into two categories:

• docs, which answer “what should the agent know?”

• skills, which answer “how should the agent behave?”

That distinction makes the content model easier to scale. Docs can be versioned and language-specific. Skills can stay short and operational.

The directory structure is also predictable. The content guide organizes entries by author, then by docs or skills, then by entry name.

A small example looks like this:

author/docs/payments/python/DOC.md
author/docs/payments/python/references/errors.md
author/skills/login-flows/SKILL.md

This is one of the reasons Context Hub is easy to work with.

The shape of the content is plain Markdown, the main entry file is predictable, and the build output is inspectable. You don't have to reverse engineer a hidden prompt layer to figure out what the agent is reading.

How to Use Incremental Fetch and Layered Sources

One of the best design choices in Context Hub is that it doesn't force you to inject every file into the model on every request.

Instead, the entry file gives you the overview, and the reference files hold the deeper material.

That lets you fetch content in progressively larger slices.

chub get stripe/webhooks --lang py
chub get stripe/webhooks --lang py --file references/raw-body.md
chub get stripe/webhooks --lang py --full

This is a token-budget feature as much as it is a documentation feature. A good agent should first load the overview, decide what part of the task matters, and only then fetch the specific supporting file.

Context Hub also supports layered sources. You can merge public content with your own local build output through ~/.chub/config.yaml.

A minimal configuration looks like this:

sources:
  - name: community
    url: https://cdn.aichub.org/v1
  - name: my-team
    path: /opt/team-docs/dist

That means you can keep public docs in one lane and team-specific runbooks in another lane while still giving the agent one search surface.

How to Use Annotations and Feedback to Create a Memory Loop

Context Hub has two different improvement channels.

Annotations are local. They help your agent remember what worked last time. Feedback is shared. It helps maintainers improve the docs for everyone.

That distinction matters because not every lesson belongs in the shared registry. Some lessons are environment-specific. Others point to content quality issues that should be fixed centrally.

Here is what local memory looks like in practice:

chub annotate stripe/webhooks \
  "Remember: Flask request.data must stay raw for Stripe signature verification."

And here's the feedback path:

chub feedback stripe/webhooks up

That loop is simple, but it's one of the most important ideas in the project. It turns a one-off debugging lesson into either persistent local memory or a signal that the shared docs need to improve.

How to See Where Relevance Still Misses

The upstream project already has a real ranking story. It uses BM25 and lexical rescue so that package-like identifiers, exact tokens, and fuzzy matches still have a chance to surface.

That is a strong baseline.

But developer queries are often much messier than package names.

People search for:

• rrf

• signin

• pg vector

• hnsw

• raw body stripe

Those aren't “bad” queries. They're realistic shorthand.

And they expose an opportunity in the content model itself: many of the exact answers live in reference files such as references/rrf.md, references/raw-body.md, and references/hnsw.md.

So the question is not whether the current search works at all. It clearly does. The better question is this:

How can you improve retrieval without breaking the content contract that already makes Context Hub useful?

The answer in the companion repo is to keep the current model and add a reranking layer on top of it.

How the Companion Relevance Engine Improves Retrieval

The companion repository in this article is context-hub-relevance-engine.

It keeps the same broad ideas that make Context Hub attractive:

• plain Markdown content

• DOC.md and SKILL.md entry points

• build artifacts you can inspect

• local annotations and feedback

• progressive fetch behavior

Then it adds one new build artifact: signals.json.

At build time, the engine extracts extra signals such as:

• headings from the main file

• titles and tokens from reference files

• language and version metadata

• source metadata and freshness

• annotation overlap

• feedback priors

The first pass stays cheap and transparent. The reranker only runs after the baseline has done its work.

That approach matters for two reasons.

First, it's additive. You don't have to redesign the content tree.

Second, it's measurable. You can define concrete failure modes, fix them one by one, and run the same benchmark every time you change the scorer.

How to Run the Companion Repo End to End

Open the repository on GitHub, clone it using GitHub’s normal clone flow, and then run the commands below from the project root.

cd context-hub-relevance-engine
npm install
npm run build
npm test

The repository has no third-party runtime dependencies, so npm install is mostly there to keep the workflow familiar. The main commands are all plain Node scripts.

How to Reproduce a Baseline Miss

Start with the query rrf.

node bin/chub-lab.mjs search rrf --mode baseline --lang python

Expected output:

No results.

Now run the improved mode.

node bin/chub-lab.mjs search rrf --mode improved --lang python

Expected top result:

langchain/retrievers [doc] score=320.24
  Composable retrieval patterns for hybrid search, parent documents, query expansion, and reranking.

That win happens because the improved mode looks beyond the top-level entry description. It also sees the reference file title rrf, the related terms from query expansion, and the broader token overlap in the extracted signals.

How to Reproduce a Workflow-intent Win

Try a sign-in query.

node bin/chub-lab.mjs search signin --mode baseline
node bin/chub-lab.mjs search signin --mode improved

The baseline misses. The improved mode returns playwright-community/login-flows because the reranker treats signin, sign in, login, and authentication as related intent.

How to Test the Memory Loop

Write a local note:

node bin/chub-lab.mjs annotate stripe/webhooks \
  "Remember: Flask request.data must stay raw for Stripe signature verification."

Then fetch the doc:

node bin/chub-lab.mjs get stripe/webhooks --lang python

You will see the main doc content, the list of available reference files, and the appended annotation.

That's the behavior you want from an agent memory loop: learn once, reuse many times.

How to Run the Benchmark

Start from an empty store:

npm run reset-store
node bin/chub-lab.mjs evaluate

The included synthetic stress set reports the following summary with an empty store:

You can also seed the store and rerun the evaluation:

npm run seed-demo
node bin/chub-lab.mjs evaluate

That demonstrates how annotations and feedback can push relevant entries even higher when the query overlaps with the agent’s own history.

How to Launch the Local Comparison UI

npm run serve

Then open http://localhost:8787 in your browser.

The UI lets you compare baseline and improved retrieval, inspect stored annotations and feedback, rebuild the local artifacts, and rerun the benchmark from one place.

How to Read the Benchmark Honestly

The benchmark in this repo is intentionally small.

That is a feature, not a flaw.

The point is not to claim universal search quality. The point is to make a handful of realistic failure modes easy to reproduce:

• acronym queries

• shorthand workflow queries

• reference-file topic queries

• memory-aware reranking

That keeps the evaluation honest.

If a future scoring change breaks rrf, signin, or raw body stripe, you'll know immediately. And if you add a stronger dataset later, you can keep these tests as regression guards.

The benchmark files included in the repo are:

• demo/benchmark.json

• docs/benchmark-empty-store.json

• docs/benchmark-seeded-store.json

• docs/relevance-improvement-plan.md

How to Connect the Companion Repo to the Upstream PR

A good companion repo is broad enough to explore ideas quickly. A good upstream PR is narrow enough to review.

That's why the two shouldn't be identical.

The companion repository is where you can keep the full relevance story together:

• the local comparison UI

• the synthetic benchmark

• the richer reranking signals

• the debug and explain surfaces

• the documentation that walks through tradeoffs end to end

The upstream PR should be smaller and more surgical. In practice, that usually means proposing the most reviewable slices first, such as:

1. reference-file signal extraction

2. explainable score output for debugging

3. a lightweight benchmark fixture format

4. one additive reranking hook behind a flag

That keeps the main repository maintainable while still letting the article and companion repo tell the full engineering story. The upstream thread for this work lives here: andrewyng/context-hub pull requests by natarajsundar.

Conclusion

What makes Context Hub interesting is not just that it stores documentation. It gives you a clear system boundary for improving coding agents.

You can inspect what the agent reads. You can decide when it should retrieve. You can layer public and private sources. You can persist local lessons. And you can improve ranking without tearing the whole model apart.

The companion relevance engine shows how to keep what already works, make one part of the system measurably better, and package the result in a way other developers can run, inspect, and extend. The upstream PR, in turn, shows how to turn a broad idea into smaller pieces that are realistic to review in the main project.

Diagram Attribution

All diagrams used in this article were created by the author specifically for this tutorial and its companion repository.

Sources

• Context Hub repository

• Context Hub README

• Context Hub CLI README

• Context Hub CLI reference

• Context Hub content guide

• Context Hub bring-your-own-docs guide

• Context Hub feedback and annotations guide

• Companion repository: context-hub-relevance-engine

• Upstream pull request search filtered by author

That matters because OpenClaw is self-hosted, multi-channel, open source, and built around agent workflows such as sessions, tools, plugins, and multi-agent routing. It feels less like a toy chatbot and more like an operator-controlled agent runtime.

In this guide, you'll do three things. First, you'll learn what OpenClaw is and why developers are paying attention to it. Second, you'll get it running the beginner-friendly way through the dashboard. Third, you'll walk through an original design contribution: a proposed OpenClaw-to-A2A plugin architecture and a proof-of-concept relay that shows how OpenClaw’s session model could map to the A2A protocol.

That last part is important, so I want to frame it carefully. The A2A integration in this article is not presented as a built-in OpenClaw feature. It's a documented architecture proposal built on top of the extension points OpenClaw already exposes.

Prerequisites

This guide is beginner-friendly for OpenClaw itself, but it assumes a few basics so you can follow the architecture and proof-of-concept sections comfortably.

Before you continue, you should be familiar with:

• Basic JavaScript or Node.js (reading and running scripts)

• How HTTP APIs work (requests, responses, JSON payloads)

• Using a terminal to run commands

• High-level concepts like services, APIs, or microservices

You don't need prior experience with OpenClaw or A2A. The setup steps walk through everything you need to get started.

Table of Contents

1. What OpenClaw Is

2. Why OpenClaw Is Getting So Much Attention

3. What the A2A Protocol Is

4. How OpenClaw and A2A Relate

5. What You Need Before You Start

6. Install OpenClaw

7. Run the Onboarding Wizard

8. Check the Gateway and Open the Dashboard

9. Use OpenClaw as a Private Coding Assistant

10. Understand Multi Agent Routing

11. Where A2A Could Fit Later

12. A Proposed OpenClaw to A2A Plugin Architecture

13. Build the Proof of Concept Relay

14. How the Proof of Concept Maps to a Real OpenClaw Plugin

15. Security Notes Before You Go Further

16. Final Thoughts

What OpenClaw Is

According to the official docs, OpenClaw is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, Discord, iMessage, and a browser dashboard to AI agents.

That wording is useful because it tells you where OpenClaw sits in the stack. It's not just a model wrapper. It's a Gateway that handles sessions, routing, and app connections, while agents, tools, plugins, and providers do the actual work.

Here is the simplest mental model:

If you're new to the project, this is the practical way to think about it:

• your chat apps are the front door

• the Gateway is the traffic and control layer

• the agent is the reasoning layer

• the model provider and tools are what let the agent actually do work

That's one reason OpenClaw feels different from a normal browser-only assistant.

Why Developers Are Paying Attention to OpenClaw

OpenClaw is getting a lot of attention for a few reasons.

The first reason is control. The docs position OpenClaw as self-hosted and multi-channel, which means you can run it on your own machine or server instead of depending on a fully hosted assistant.

The second reason is that OpenClaw already looks like an agent platform. The docs talk about sessions, plugins, tools, skills, multi-agent routing, and ACP-backed external coding harnesses. That's a much richer story than “ask a model a question in a web page.”

The third reason is workflow fit. A lot of people don't want another inbox. They want an assistant that can live in the tools they already check every day.

There's also a broader industry trend behind the hype. Developers are actively looking for ways to connect multiple agents and multiple tools without giving up visibility into what's happening. OpenClaw sits directly in that conversation.

What the A2A Protocol Is

A2A, short for Agent2Agent, is an open protocol for communication between agent systems. The A2A specification says its purpose is to help independent agent systems discover each other, negotiate interaction modes, manage collaborative tasks, and exchange information without exposing internal memory, tools, or proprietary logic.

That last point matters. A2A is about interoperability between agent systems, not about exposing all of one agent's internals to another.

A2A introduces a few core concepts that are worth learning early:

• Agent Card: a JSON description of the remote agent, its URL, skills, capabilities, and auth requirements

• Task: the main unit of remote work

• Artifact: the output of a task

• Context ID: a stable interaction boundary across multiple related turns

A2A tasks follow a fairly clean lifecycle:

The A2A docs also explain that A2A and MCP are complementary, not competing. A2A is for agent-to-agent collaboration. MCP is for agent-to-tool communication.

That distinction is useful when you compare A2A with OpenClaw, because OpenClaw already has strong local tool and session concepts.

How OpenClaw and A2A Relate

OpenClaw and A2A are not the same thing, but they line up in interesting ways.

OpenClaw already documents several features that point in a multi-agent direction:

• multi-agent routing for multiple isolated agents in one running Gateway

• session tools such as sessions_send and sessions_spawn

• a plugin system that can register tools, HTTP routes, Gateway RPC methods, and background services

• ACP support and the openclaw acp bridge for external coding clients

But it's still important to stay precise here.

OpenClaw documents ACP, plugins, and local multi-agent coordination today. The docs I checked do not describe native A2A support as a first-class built-in capability.

That means the honest claim is this:

OpenClaw can be meaningfully connected to A2A in theory because the architectural pieces line up, but the A2A bridge still has to be built.

ACP versus A2A

ACP and A2A solve different problems.

ACP in OpenClaw today is about bridging an IDE or coding client to a Gateway-backed session.

A2A is about one agent system talking to another agent system across a protocol boundary.

That difference is one reason I prefer the phrase plugin bridge here instead of native A2A support.

What You Need Before You Start

The easiest first run does not require WhatsApp, Telegram, or Discord.

The OpenClaw onboarding docs say the fastest first chat is the dashboard. That makes this a much more approachable beginner setup.

Before you start, you'll need:

1. Node 24 if possible, or Node 22.16+ for compatibility

2. an API key for the model provider you want to use

3. If you're on Windows, WSL2 is the recommended path for the full experience. Native Windows works for core CLI and Gateway flows, but the docs call out caveats and position WSL2 as the more stable setup.

4. about five minutes for the first dashboard-based run

Step 1: Install OpenClaw

The official getting-started page recommends the installer script.

On macOS, Linux, or WSL2, run:

curl -fsSL https://openclaw.ai/install.sh | bash

On Windows PowerShell, the docs show this:

iwr -useb https://openclaw.ai/install.ps1 | iex

If you're on Windows, the platform docs recommend installing WSL2 first:

wsl --install

Then open Ubuntu and continue with the Linux commands there.

Step 2: Run the Onboarding Wizard

Once the CLI is installed, run the onboarding wizard.

openclaw onboard --install-daemon

The onboarding wizard is the recommended path in the docs. It configures auth, gateway settings, optional channels, skills, and workspace defaults in one guided flow.

The most beginner-friendly choice is to keep the first run simple. Don't worry about chat apps yet. Get the local Gateway working first.

Step 3: Check the Gateway and Open the Dashboard

After onboarding, verify that the Gateway is running.

openclaw gateway status

Then open the dashboard:

openclaw dashboard

The docs call this the fastest first chat because it avoids channel setup. It's also the safest way to start, because the dashboard is local and the OpenClaw docs clearly say the Control UI is an admin surface and should not be exposed publicly.

The beginner setup flow looks like this:

If you can chat in the dashboard, your day-zero setup is working.

Step 4: Use OpenClaw as a Private Coding Assistant

The best first use case is not to drop OpenClaw into a public group chat.

Use it as a private coding assistant in the dashboard.

For example, try a prompt like this:

I am building a small Node.js utility that reads Markdown files and generates a table of contents. Turn this idea into a project plan, a README outline, and the first five implementation tasks.

That kind of prompt is ideal for a first run because it gives you something concrete back right away.

You can also use it to:

1. turn rough notes into a plan,

2. summarize a bug report into action items,

3. draft a README,

4. propose a folder structure, or

5. write a safe first implementation checklist.

That is already enough to make OpenClaw useful before you touch any advanced protocol work.

Step 5: Understand Multi Agent Routing

Once the basic setup is working, it helps to understand OpenClaw’s local multi-agent model.

The docs describe multi-agent routing as a way to run multiple isolated agents in one Gateway, with separate workspaces, state directories, and sessions.

That means you can imagine setups like this:

• a personal assistant

• a coding assistant

• a research assistant

• an alerts assistant

OpenClaw already has a model for that:

You don't need to set this up on day one.

But it matters for the A2A discussion, because once you understand how OpenClaw routes work between local agents, it becomes much easier to think about routing work to remote agents through a protocol like A2A.

Where A2A Could Fit Later

A2A could fit into OpenClaw in two broad ways.

Option 1: OpenClaw as an A2A Client

In this model, OpenClaw stays your personal edge assistant.

It receives a request from the dashboard or a chat app, decides the task needs a specialist, discovers a remote A2A agent through an Agent Card, sends the task, waits for updates or artifacts, and translates the result back into a normal OpenClaw reply.

This is the cleaner story for a personal assistant. OpenClaw stays the front door, and A2A becomes a delegation path behind the scenes.

Option 2: OpenClaw as an A2A Server

In this model, OpenClaw exposes some of its own capabilities to other agents.

A plugin could theoretically publish an A2A Agent Card, advertise a narrow skill set, accept A2A tasks, and map those tasks into OpenClaw sessions or sub-agent runs.

That's technically plausible because the plugin system can register HTTP routes, tools, Gateway methods, and background services.

It's also the riskier direction for a personal assistant, which is why I think client-first is the right starting point.

A Proposed OpenClaw to A2A Plugin Architecture

This section is my original contribution in the article.

I think the cleanest first architecture is not a full bidirectional bridge. It's a narrow outbound delegation plugin that lets OpenClaw call a small allowlist of remote A2A agents.

The design goal is simple:

Reuse OpenClaw for user-facing conversations and local tool access, but use A2A only when a remote specialist agent is the best place to do the work.

Here is the architecture I would start with:

Why This Design is a Good Fit for OpenClaw

This proposal is grounded in extension points OpenClaw already documents.

A plugin can register:

• an agent tool for delegation,

• a Gateway method for health and diagnostics,

• an HTTP route for future callbacks or webhook verification, and

• a background service for cache warming, task subscriptions, or cleanup.

That means the bridge doesn't have to modify OpenClaw core to be credible.

The Mapping Table

The most important design decision is how to map OpenClaw’s session model to A2A’s task model.

Here is the mapping I recommend:

This is the key architectural claim in the article:

Treat the OpenClaw session as the long-lived conversational boundary, and treat each remote A2A task as one delegated execution inside that boundary.

That preserves both sides cleanly.

The Design in One Sentence

The a2a_delegate tool should:

1. resolve an allowlisted remote Agent Card,

2. reuse an existing A2A contextId for the current sessionKey when possible,

3. create a fresh remote Task for the new delegated turn,

4. normalize remote artifacts back into a simple local answer, and

5. never expose the whole OpenClaw Gateway directly to the public internet.

I like this design because it is incremental, testable, and consistent with OpenClaw’s personal-assistant trust model.

Build the Proof of Concept Relay

To make the architecture concrete, I built a small proof-of-concept relay.

https://github.com/natarajsundar/openclaw-a2a-secure-agent-runtime

It's intentionally small. It doesn't try to become a full production plugin. Instead, it proves the hardest conceptual part of the bridge: how to map one OpenClaw session to a reusable A2A context while creating a fresh A2A task per delegated turn.

Here's the repository layout:

openclaw-a2a-secure-agent-runtime/
├── README.md
├── package.json
├── examples/
│   └── openclaw-plugin-entry.example.ts
├── src/
│   ├── a2a-client.mjs
│   ├── agent-card-cache.mjs
│   ├── demo.mjs
│   ├── mock-remote-agent.mjs
│   ├── openclaw-a2a-relay.mjs
│   ├── session-task-map.mjs
│   └── utils.mjs
└── test/
    └── relay.test.mjs

The PoC does six things:

1. fetches a remote Agent Card from /.well-known/agent-card.json,

2. caches it with simple ETag revalidation,

3. records local sessionKey to remote contextId mappings,

4. sends an A2A SendMessage request,

5. polls GetTask until the task finishes, and

6. converts the remote artifact into a local text answer.

Run the Demo

The repo uses only built-in Node.js modules.

cd openclaw-a2a-secure-agent-runtime
npm run demo

The demo spins up a mock remote A2A server, delegates one task, delegates a second task from the same local session, and shows that the same remote contextId is reused.

The Core Relay Idea

This is the important logic in plain English:

1. look up the most recent remote mapping for the current OpenClaw sessionKey

2. reuse the old contextId if one exists

3. create a fresh A2A Task for the new request

4. poll until that task becomes TASK_STATE_COMPLETED

5. turn the returned artifact into a normal text result that OpenClaw can send back to the user

That makes the bridge predictable.

Here's a shortened version of the relay logic:

const previous = await sessionTaskMap.latestForSession(sessionKey, remoteBaseUrl);
const contextId = previous?.contextId ?? crypto.randomUUID();

const sendResult = await client.sendMessage({
  text,
  contextId,
  metadata: {
    openclawSessionKey: sessionKey,
    requestedSkillId: skillId,
  },
});

let task = sendResult.task;
while (!isTerminalTaskState(task.status?.state)) {
  await sleep(pollIntervalMs);
  task = await client.getTask(task.id);
}

return {
  contextId,
  taskId: task.id,
  answer: taskArtifactsToText(task),
};

That's the heart of the design.

Why This Repo is a Useful Proof of Concept

A lot of “integration” articles stay too abstract. This repo avoids that problem in three ways.

First, it makes the session-to-context mapping explicit.

Second, it includes a mock remote A2A agent so you can test the flow without needing a large external setup.

Third, it includes a test that checks the most important invariant: repeated delegations from one local OpenClaw session reuse the same A2A context.

That is the piece I most wanted to make concrete, because it is where architecture turns into implementation.

How the Proof of Concept Maps to a Real OpenClaw Plugin

The proof of concept is the relay core.

A real OpenClaw plugin would wrap that relay with four extension surfaces that the OpenClaw docs already describe.

1: A Delegation Tool

This is the main entry point.

A plugin would register an optional tool like a2a_delegate so the local agent can explicitly choose to delegate work.

That tool should be optional, not always-on, because remote delegation is a side effect and should be easy to disable.

2: A Gateway Method for Diagnostics

A method like a2a.status would let you inspect whether the relay is healthy, which remote cards are cached, and whether any tasks are still being tracked.

That is much better than asking the model to “tell me if the bridge is healthy.”

3: A Plugin HTTP Route

You may not need this on day one.

But once you move beyond polling and want push-style callbacks or webhook verification, a plugin route gives you the right boundary for that work.

4: A Background Service

A small service is a clean place to do cache warming, cleanup, or later subscription handling.

That keeps the tool path focused on delegation instead of maintenance work.

If I were turning this into a real plugin package, I would sequence the work in this order:

1. wrap the relay in registerTool,

2. add a small config schema with an allowlist of remote agents,

3. add a2a.status,

4. keep polling as the first async model,

5. add a callback route only if a real use case needs it.

That is the most practical path from theory to a real extension.

I tested the relay flow locally with the mock remote agent and confirmed that repeated delegations from the same local session reused the same remote contextId.

Security Notes Before You Go Further

This is the section you should not skip.

The OpenClaw security docs explicitly say the project assumes a personal assistant trust model: one trusted operator boundary per Gateway. They also say a shared Gateway for mutually untrusted or adversarial users is not the supported boundary model.

That has a direct consequence for A2A.

A2A is designed for communication across agent systems and organizational boundaries. That is powerful, but it is also a different threat model from a single private OpenClaw deployment.

So the safer design is not this:

• expose your personal OpenClaw Gateway publicly,

• let arbitrary remote agents reach it,

• and hope the tool boundaries are enough.

The safer design is closer to this:

This diagram shows two separate trust boundaries.

On the left is your private OpenClaw deployment. This includes your Gateway, your sessions, your workspace, and any credentials or tools your agent can access. This boundary is designed for a single trusted operator.

On the right is the external A2A ecosystem, where remote agents live. These agents may belong to other teams or organizations and operate under different security assumptions.

The key idea is that communication between these two sides should happen through a controlled relay layer, not by directly exposing your OpenClaw Gateway. The relay enforces allowlists, limits what data is sent out, and ensures that remote agents cannot directly access your local tools or state.

This separation lets you experiment with agent interoperability while keeping your personal assistant environment safe.

In plain English, keep your personal assistant boundary private.

If you experiment with A2A, treat that as a separate exposure boundary with its own allowlists, auth, and operational controls.

That is why the proof-of-concept relay in this article starts with an explicit remote allowlist.

Why This Design and Not the Other One?

A natural question is why this article proposes an outbound-only A2A bridge first, instead of immediately building a full bidirectional or server-style integration.

The short answer is that OpenClaw’s current design is centered around a personal assistant trust boundary, where one operator controls the Gateway, sessions, and tools. Introducing external agents into that environment requires careful control over what is exposed.

Starting with outbound delegation gives you a safer and more incremental path.

Outbound-only first means:

• preserving the personal-assistant trust boundary, so your local OpenClaw deployment remains private and operator-controlled

• avoiding exposing the OpenClaw Gateway as a public A2A server before you have strong auth, policy, and monitoring in place

• allowing you to test remote delegation patterns (Agent Cards, tasks, artifacts) without committing to full interoperability complexity

• keeping OpenClaw as the user-facing control plane, while remote agents act as optional specialists

This approach follows a common systems design pattern: start with controlled outbound integration, validate behavior and constraints, and only then consider expanding to inbound or bidirectional communication.

In practice, this means you can experiment with A2A safely, learn how the models fit together, and evolve the system without introducing unnecessary risk early on.

Final Thoughts

OpenClaw is worth learning because it gives you a self-hosted assistant that can live in the communication tools you already use.

The simplest beginner path is still the right one:

1. install it,

2. run onboarding,

3. check the Gateway,

4. open the dashboard,

5. try one private workflow.

That is already a real end-to-end setup.

A2A belongs in the conversation because it gives you a credible way to connect OpenClaw to remote specialist agents later.

But the most important thing in this article isn't the buzzword. It's the boundary design.

If you keep OpenClaw as the private user-facing edge and use a narrow plugin bridge for outbound delegation, the OpenClaw session model and the A2A task model can fit together cleanly.

That is the architectural idea I wanted to make concrete here.

Diagram Attribution

All diagrams in this article were created by the author specifically for this guide.

Further Reading

• OpenClaw docs home

• OpenClaw Getting Started

• OpenClaw Onboarding Wizard

• OpenClaw Multi-Agent Routing

• OpenClaw Session Tools

• OpenClaw Plugin System

• OpenClaw Plugin Agent Tools

• OpenClaw ACP bridge

• OpenClaw Security

• A2A specification

• A2A Agent Discovery

• A2A and MCP

• A2A protocol definition and schema

• A2A version 1.0 announcement