This page walks through the three contributions anyone can make to BizPlug's public plug-in repository, msg2ai/bizplug-plugins, with the exact commands and what they print, and a short video for each. For what each contribution is and what happens to it, see Contribute a theme, a layout, an industry or a plug-in.
Before you start
You need a GitHub account, Git and Node.js 18 or later. No BizPlug account, no keys and no server of your own. Fork the repository on GitHub (if your fork is older, press Sync fork on its page first), clone your fork, and make one branch per contribution:
git clone https://github.com/<you>/bizplug-plugins cd bizplug-plugins git checkout -b theme/harbour
Each pull request adds only one file or one folder in the place named below. Everything else in the repository is generated from the BizPlug website, and a pull request that changes it fails its checks.
Add a card theme
A theme is five colours for a business's card in ChatGPT and Claude, in one file: themes/<id>.json. The full rules are in THEMES.md.
- 1Write the file. Copy one from
themes/and name it after itsid(2 to 24 lower-case letters or hyphens):themes/harbour.json. Give it aname(up to 24 characters), a one-sentencedescriptionof the look and who it suits, anauthor, and thecolors. - 2Check it:
npx tsx themes/check-theme.ts themes/harbour.json. It runs the same check BizPlug runs and prints what to fix, or the contrast of each pair. - 3See it on the real card:
npx tsx themes/preview.ts themes/harbour.jsonwrites the sample café's and hotel's cards in your colours, in dark and light mode, and prints where. Open them at about 680 px and 390 px wide and take a screenshot. - 4Open a pull request against
mainthat adds onlythemes/harbour.json. Keep the Card theme part of its checklist and paste the check's output and your screenshot. The Check card themes workflow runs the same check. - 5Review and merge. The BizPlug team looks at it on real cards, in dark and light mode, and may ask for changes. Once merged, every business is offered it in the portal within about ten minutes, on its plug-in page's Look tab under Card theme.
{
"id": "harbour",
"name": "Harbour",
"description": "Sea blue to sand on dark slate. Calm and clear: marinas, seafood restaurants and coastal stays.",
"author": "Your name or company",
"colors": { "a1": "#7dd3fc", "a2": "#fcd9a8", "ink": "#0b1620", "bg": "#0d1a24", "glow": "rgba(125,211,252,.14)" }
}
$ npx tsx themes/check-theme.ts themes/harbour.json
Harbour is ok. Contrast: ink on a1 10.95, ink on a2 13.59, a1 on bg 10.58, a2 on bg 13.13.| Colour | What it colours |
|---|---|
a1, a2 | The accent gradient: buttons, icon tiles and badges. a2 also colours links |
ink | Text and icons on the accent |
bg | The card's background in dark mode (light mode uses white) |
glow | A soft light in the card's corner, as rgba(r,g,b,alpha) with alpha .25 or less |
ink on both accents and both accents on bg need a contrast of at least 4.5: a dark ink, bright accents and a dark background. The colours must be your own, not another company's brand colours used without permission.
Add a menu layout
A layout decides how the card's menu is organised; the options, forms and results stay the same. It is a folder, community/layouts/<id>/, with layout.json, layout.js, layout.css and two pictures. The full reference, with everything render(ctx) receives, is in LAYOUTS.md.
- 1Copy the template:
cp -r layouts/_template community/layouts/compass. Use the sameidinlayout.jsonand in every.lay-<id>selector inlayout.css(the template'syour-layoutbecomescompasseverywhere). - 2Describe it in
layout.json:name,author(a name and an optional httpsurl),summary,suits, andownHeader: truewhen your layout draws the business's name, logo and banner itself. - 3Write `render(ctx)` in
layout.js: one pure function that returns the menu as HTML. Nodocument,window, events, timers,fetch, imports or template literals; escape every text withctx.h(). Buttons act throughdata-open(open an option),data-ask(ask in the chat),data-href(open an address) anddata-lay(your own state, such as a tab). Use the card's colour tokens (--a1,--a2,--ink,--fg,--muted,--card,--line) so it wears every business's colours. - 4Preview it:
npx tsx layouts/preview.ts community/layouts/compasswritespreview-demo-cafe-dark.htmland three more pages into your folder. Open them and resize the window to 680 px and 390 px. - 5Make the two pictures:
preview-desktop.pngis the sample hotel at 680 px in dark mode, andpreview-mobile.pngthe sample café at 390 px. Then delete the preview pages:rm community/layouts/compass/preview-demo-*.html. - 6Check it:
npx tsx layouts/check-layout.ts community/layouts/compass. Before the pictures exist it says they are missing; after, it prints✓ compass follows the layout rules. - 7Open a pull request against
mainthat adds onlycommunity/layouts/compass/(the three files and the two pictures), with the Menu layout checklist and the check's output. The Check contributions workflow runs the same check. - 8Review and merge. The team tries it in ChatGPT and Claude, in dark and light mode, on a computer and a phone. Once merged it stays in the repository, credited to you; it is offered in the portal once the BizPlug team adds it, with you as its author.
The card does not scroll inside itself and is about 680 px wide on a computer and 360 to 420 px on a phone: keep the menu short, make every control a button at least 40 px tall, and stop animations under prefers-reduced-motion.
Add a new industry
An industry is one file, community/industries/<slug>.json, that runs on one of the five engines. When the pull request is merged, the file is the industry: its plug-in, its page on this site and its place in the portal go live with the website's next build. The full field list is in INDUSTRIES.md.
| Engine | What customers do |
|---|---|
order | Browse a catalog with prices, send a pickup or delivery order, check its status |
stay | See what is free for dates and party size with the total price, send a booking request, check its status |
appt | Find open times on a day, request an appointment, check its status |
quote | Get an estimate from published price rules, request a quote or a visit, check its status |
track | Look up a reference the customer already has, send a new request, check its status |
- 1Check that no existing industry fits. Look through Industries and INDUSTRIES.md for the words your customers use. An industry is a kind of plug-in, not a business: every business in it gets its own plug-in with its own name, services, prices, hours and colours. So a yoga studio uses Fitness & Gyms, a dog groomer Veterinary & Pet Care or Beauty & Salons, and a vegan restaurant Restaurants & Food Service. If one fits, stop here: the business signs up in the portal and picks that industry (see Choose your industry plug-in).
- 2Pick the engine that fits what customers mainly want to do. Try an industry on the same engine on its sample business, which never sends anything:
npx tsx industries/test-industry.ts --plugin https://mcp.bizplug.ai/plugin/coffee-shops/demo-cafe. - 3Write the file.
cp industries/example.json community/industries/bicycle-shops.json, named after itsslug. Fill inname,group,engine,title, the threetools(your names for the look-up, the request and the status check),noun,ask,covers, an optionalrule, anexampleitem and theauthor.page(the words of its page here) andchat(a worked example) are optional. - 4Check it:
npx tsx industries/check-industry.ts community/industries/bicycle-shops.json. It uses the same function the website reads your file with. When the file passes, the check also lists the existing industries most like yours, from their names, what they cover and their engine: read each one again before you go on. - 5Open a pull request against
mainthat adds only that file, with the New industry checklist, and name the closest existing industry and what a customer does in yours that it cannot. Check contributions runs the check, and Test industry proposals builds your industry as a working plug-in for a sample business athttps://mcp-test.bizplug.ai/plugin/proposal/<pull request number>, tests it and comments the result. On a first pull request, GitHub may wait for a maintainer to approve the workflows. - 6Try it yourself. Add the preview address as a connector in ChatGPT developer mode and ask your
askquestion, or run the same test:npx tsx industries/test-industry.ts <pull request number>, and paste its output in the pull request. A sample business never sends a request. - 7Review and merge. Merging is the release: the website builds again, and usually a few minutes later the plug-in answers at
https://mcp.bizplug.ai/plugin/<slug>, its page is atwww.bizplug.ai/industries/<slug>, and businesses can add it in the portal. A comment on your pull request says when it is live.
$ npx tsx industries/check-industry.ts community/industries/bicycle-shops.json ✓ Bicycle Shops & Repair (bicycle-shops) is a valid industry: engine appt, tools find_repair_slots, book_repair, get_repair_status.
A new industry is right only when its customers mainly do something else (order, book dates, book a time, ask for a quote or follow a request), or when the words of every existing plug-in would be wrong for it. A different name, a niche, a city or a type of customer is not enough, and the team does not merge an industry that an existing one already covers. If an existing industry almost fits but lacks something, propose that with the issue form instead, naming the industry.
$ npx tsx industries/check-industry.ts community/industries/yoga-studios.json ✓ Yoga Studios (yoga-studios) is a valid industry: engine appt, tools find_class_times, book_class, get_class_booking. … ⚠ Before you propose it, look at these existing industries (INDUSTRIES.md): - Fitness & Gyms (fitness): shares class, membership, trial, pass; same group and engine A business that fits one of them uses that industry's plug-in, under its own name and with its own services, prices and colours: no new industry is needed. If none fits, say in your pull request which is closest and what a customer does in yours that it cannot.
Everything the file says must be true of the plug-in: it answers from a business's published profile and sends requests the business confirms. Do not promise live availability or payment in the chat. An industry that needs a new tool or data file is proposed with the issue form instead, and built by the BizPlug team.
Not on GitHub?
Use a form and the team adds the file for you: propose a card theme, a menu layout or a new industry. Questions: info@bizplug.ai.
Last reviewed 22 November 2026