Create a Toggl Browser Integration (with Claude)

What you're building

A Toggl integration injects the Toggl button into a third-party website (GitHub, Jira, GitLab, Asana…) and teaches it how to read a task title + metadata from that page's DOM. An integration is a single JSON document. Claude drives the whole authoring loop — finding selectors, injecting the button on the live page, verifying placement — so you don't write selectors by hand.

Prerequisites

• Claude Code (any project folder works — the work happens in the browser, not the repo).
• The Toggl browser extension installed in Chrome and signed in, with a workspace/organization available.
• The Claude-in-Chrome extension connected (Claude drives the page through it).
• Recommended: for the session, enable only Claude-in-Chrome and the Toggl extension — disable others. Extensions like 1Password can silently intercept clicks/inputs Claude drives.

Step 0 — Install the skill (one time)

Install the Toggl skills globally so Claude knows the integration-authoring flow:

npx skills add toggl/skills 

The CLI detects your installed agents and symlinks the skill into ~/.claude/skills/. This makes the toggl-browser-integrations skill available. Source: https://github.com/toggl/skills

Once installed, the skill triggers automatically when you ask Claude to add the Toggl button to a website.

Step 1 — Open the target page & ask Claude

1. In Chrome, open the exact page/item you want the button on (e.g. a GitLab board, an issue detail, a list view) — already authenticated and in the right state.
2. In Claude Code, ask it to build the integration, e.g.:

   Create a Toggl browser integration on this page: https://gitlab.com/<group>/<project>/-/boards

3. Claude selects your Chrome browser, navigates/confirms it's on the tab you see (it injects a banner + checks the tab is visible/focused), and inspects the page DOM — thinking about the page structure and probing elements for stable anchors and the text to track.

💡 It works from any folder — you only need Claude Code running plus the skill and the browser. Nothing is committed to your repo.

Step 2 — Answer Claude's intent questions

Before writing JSON, Claude asks what it can't reliably infer:

• What to track as the task title? — e.g. issue number + title (#43198 Auto DevOps callout banner…).
• Any extra metadata? — project, labels, milestone… or none (just the title).
• Single vs. one-per-card — Claude usually infers this from how many times the anchor matches (a board → one button per card; a detail view → one button). It states its inference; you only correct it if wrong.

In the worked example we chose #number + title and no metadata.

Step 3 — Open the Toggl side panel

Claude can't click browser chrome, so this part is you:

1. Right-click the Toggl extension icon → "Open side panel" on the same tab Claude is driving.
2. In the panel header ("Saving to"), pick an organization.

⚠️ The bridge is per-tab: the side panel must be open on the exact tab Claude is posting to, with an org selected — otherwise nothing injects. When it opens, the panel pulls your organization's integrations first. If the org already has one for this site, it loads that and a save updates it rather than creating a second one. If the site has none, the panel starts empty and Claude authors from scratch. If the panel says it couldn't check your organization's integrations, fix that before saving, or use Apply locally until it can.

Step 4 — Claude injects & verifies

Claude posts the definition to the page (via a shared-DOM bridge), which applies it locally and injects the button(s) immediately. Claude then verifies automatically (takes ~1–2 min):

• Counts the injected wrappers (e.g. 10/10 cards on the board).
• Confirms each button reads its own card's text (per-card scoping).
• Hit-tests that the button is actually clickable — boards often have a "click anywhere to open" overlay covering the card, and visible ≠ clickable.
• Screenshots/zooms to check alignment and theming.

Step 5 — Tweak placement (iterate)

If the spot isn't right, just say so — e.g. "put it on the bottom-right of each card." Claude reworks the anchor and adds any CSS needed to beat the card's click-overlay (giving the button its own stacking context with isolation: isolate), reloads, re-posts, and re-verifies. Repeat until it's where you want it and reads correctly.

Step 6 — Test it 

Open one of the items, click the injected Track button, confirm the tracked title is correct (e.g. #number + description), start tracking, then stop it. Confirm it behaves end-to-end.

Step 7 — Save (or keep local)

• Local draft: what Claude applied is a local draft — injected on this tab and it survives a page refresh, but isn't synced anywhere.
• Save to org: click Save & sync in the side panel to persist the integration to your organization (needs the manage-integrations permission). This enables it for everyone in the org. If the org already had an integration for this site, this replaces it under the same id.

🔁 One integration can cover multiple pages. The board and the issue-detail view are different button placements in the same definition. You initially build for one surface; just continue the conversation ("also add it on the issue detail page") and Claude adds the extra button. Don't force one button to serve two surfaces.

Worked example recap — GitLab boards

{
  "name": "GitLab Boards",
  "domain": "gitlab.com",
  "selectors": { "card": "[data-testid=\"board-card\"]" },
  "resolvers": {
    "idText": { "closest": "@card", "query": "[data-testid=\"work-item-id-text\"]" },
    "title":  { "closest": "@card", "query": "[data-testid=\"board-card-title-link\"]" }
  },
  "buttons": [{
    "name": "card-button",
    "anchor": ".board-card-footer",
    "append": "last",
    "multiple": true,
    "variant": "minimal",
    "iconSize": 14,
    "description": { "resolvers": ["idText", " ", "title"] }
  }],
  "cssContent": "[data-toggl-button-wrapper=\"card-button\"]{position:relative;isolation:isolate;z-index:1;margin-left:auto;align-self:center;}",
  "themeDetector": { "colorElement": "body" }
}

Tips & gotchas

• Prefer stable selectors — data-testid, roles, ARIA — over hashed CSS-module class names, which change between deploys.
• List vs. detail are different buttons — separate entries with their own anchor, multiple, and scoping.
• Stretched click-overlays — cards that are "click anywhere to open" can cover your button even when it looks on top; the fix is a separate stacking context, not just a bigger z-index.
• If nothing injects — check the side panel is open on this tab, an org is selected, and only Claude + Toggl extensions are enabled.
• Per-tab bridge — keep the side panel and Claude on the same visible tab.