TOCus is an extension that gives you a short breathing pause before loading the websites you choose as distracting, so you can notice the impulse and decide what to do next.
TOCus is a free and open-source browser extension that adds a gentle breathing pause before websites you choose as distracting. The goal is to create a small moment to notice an impulse and decide what to do next, not to block, shame, or judge.
Important: TOCus is a wellbeing tool, not medical treatment. It doesn't diagnose OCD or any other condition, and it makes no clinical promises.
- Choose the websites where you want a pause.
- When you visit one, TOCus offers a brief, calm breathing moment.
- After the pause, decide for yourself whether to continue.
TOCus is and will remain local-only, with no account, TOCus server, cloud backup or synchronization, telemetry, or product analytics. Selected-site settings and pause interactions stay on your device. The extension makes no external network requests and does not access your browser's saved history. Opening the toolbar popup gives TOCus temporary access to the active tab so it can show or add that website; it does not grant ongoing access to other tabs. Browsers may describe the optional permission used to observe current navigation as access to browsing history; TOCus requests it only when you protect a site and does not retain or transmit a browsing history. This commitment covers the extension's own traffic; websites, the browser, and external pages you choose to open generate their own traffic.
Settings includes Privacy and local data, where you can review local storage and browser permissions. Reset statistics keeps your websites and preferences. Reset all TOCus data removes your choices and statistics, revokes website access, and reopens setup after confirmation. A non-personal reset marker remains locally to prevent older pages from restoring deleted data.
- WXT and React for the browser extension
- Mantine with shared TOCus theme tokens for controls across the extension and website
- Astro with React islands for the project website
- pnpm workspaces and Turborepo
- TypeScript, Vitest, and ESLint
- Node.js 24.16.0 or newer within the Node.js 24 release line (
.node-versionpins the 24.20.0 version used in CI) - pnpm 11.24.0
The repository pins its package-manager version in package.json.
git clone https://github.com/agustinbarrientos/TOCus.git
cd TOCus
corepack enable
pnpm install --frozen-lockfile
pnpm setup:browsersStart the workspace development tasks:
pnpm dev| Command | Purpose |
|---|---|
pnpm dev |
Run workspace development tasks in parallel |
pnpm setup:browsers |
Install pinned Chromium, Firefox and WebKit builds |
pnpm build |
Build all workspaces |
pnpm build:firefox |
Build the extension for Firefox |
pnpm build:safari |
Build Safari web-extension assets |
pnpm zip:chrome |
Build and ZIP the Chrome release |
pnpm zip:firefox |
Build and ZIP the Firefox release |
pnpm zip:safari |
Build and ZIP Safari web-extension assets |
pnpm lint |
Run script and stylesheet linting |
pnpm lint:fix |
Fix autofixable script and stylesheet issues |
pnpm typecheck |
Type-check all workspaces |
pnpm test |
Run unit coverage, build-contract, and browser tests |
pnpm test:unit |
Run unit tests with protection coverage thresholds |
pnpm test:build-contract |
Build all browser targets and validate generated artifacts |
pnpm test:build-browser |
Run isolated browser journeys against already-built files |
pnpm test:browser |
Run native media/Canvas coverage and all presentation tests |
pnpm test:ui |
Run shared controls and extension UI in all three engines |
pnpm check |
Run linting, type checks, and tests |
Use a clean checkout of the reviewed release commit, the Node.js version in .node-version, and the pinned pnpm version. Install dependencies with pnpm install --frozen-lockfile, then run pnpm check and pnpm test:visual in the supported environments described in CONTRIBUTING.md. Record the commit, operating system and architecture, tool versions, check results, and artifact SHA-256 values with the release.
Create production archives from the repository root:
pnpm zip:chrome
pnpm zip:firefox
pnpm zip:safariEach command uses WXT's built-in ZIP command to rebuild its target before archiving it. These commands create local files; store submission is a separate step. With extension version 0.1.0, the outputs under apps/extension/.output/ are:
| Archive | Manifest | Intended use |
|---|---|---|
tocusextension-0.1.0-chrome.zip |
V3, Chrome 120+ | Chrome Web Store upload |
tocusextension-0.1.0-firefox.zip |
V2, Firefox 140+ | Firefox Add-ons upload |
tocusextension-0.1.0-safari.zip |
V2, Safari 16.4+ | Input to Apple's Safari packaging workflow |
Verify ZIP integrity with unzip -t, inspect each archive's root manifest.json with unzip -p, and confirm the packaged icons, locale messages, page resources, and permissions match the reviewed build. For example:
unzip -t apps/extension/.output/tocusextension-0.1.0-firefox.zip
unzip -p apps/extension/.output/tocusextension-0.1.0-firefox.zip manifest.json
shasum -a 256 apps/extension/.output/tocusextension-0.1.0-chrome.zip apps/extension/.output/tocusextension-0.1.0-firefox.zip apps/extension/.output/tocusextension-0.1.0-safari.zipRe-run pnpm exec vitest run --config config/vitest.config.ts --project build-contract for static artifact checks and pnpm test:build-browser for packaged browser journeys after packaging. Browser journeys run sequentially with no retries and retain traces and screenshots only on failure under test-results/build-browser/; their HTML report is under playwright-report/build-browser/. The separate pnpm test:ui command uses Playwright Test for shared controls and extension presentation, reusing one fixture server and worker-owned browsers with isolated test contexts. Its diagnostics are under test-results/ui/ and playwright-report/ui/. CI uploads both suites' diagnostics on failure. Replace 0.1.0 in filenames when the extension version changes. The declared minimum browser versions are compatibility targets; successful builds do not establish runtime support across every version.
WXT also creates tocusextension-0.1.0-sources.zip when packaging Firefox. Its default source root is apps/extension, so it omits this monorepo's root lockfile, build configuration, and shared packages. That automatic archive is insufficient for Mozilla to reproduce this build.
After confirming git status --short is empty and HEAD is the reviewed release commit used above, create a complete tracked-workspace source archive instead:
git rev-parse HEAD
git archive --format=zip --output=apps/extension/.output/tocus-0.1.0-workspace-sources.zip HEAD
unzip -t apps/extension/.output/tocus-0.1.0-workspace-sources.zip
shasum -a 256 apps/extension/.output/tocus-0.1.0-workspace-sources.zipSupply that workspace archive and these build instructions with the Firefox submission. Before submitting, extract it into an empty directory, install the pinned tools and dependencies with pnpm install --frozen-lockfile, and run pnpm zip:firefox from its root. Compare the extracted release file contents with the submitted Firefox ZIP and investigate any differences. The source archive includes README.md, pnpm-lock.yaml, pnpm-workspace.yaml, lingui.config.ts, apps/extension, and packages; it excludes ignored output, installed dependencies, and uncommitted changes. Follow Mozilla's source-code submission instructions for the actual review.
The Safari ZIP contains HTML, CSS, JavaScript, and other web-extension resources. It is not a signed Apple app or an App Store distribution archive. For the local Xcode workflow, run Apple's Safari web-extension packager against apps/extension/.output/safari-mv2/, using --copy-resources so the generated project has its own reviewed resource copy. Current Xcode calls this tool xcrun safari-web-extension-packager; older versions use safari-web-extension-converter.
Before creating the release app, confirm the intended Apple platforms, developer team, registered bundle identifiers, signing identities, entitlements, and minimum supported OS versions. Review packager compatibility warnings, add the final public privacy-policy URL to the containing app and App Store Connect, then build, sign, archive, and test installation and extension behavior on the supported Safari platforms. The web-assets archive alone does not complete those steps.
The following release inputs were unresolved on September 9, 2026:
- Supply the final public Chrome, Firefox, and Safari listing URLs. The approved temporary URLs remain centralized in
apps/website/src/config/downloads/index.ts; replace each when its listing is public and verify the destination while signed out. - Choose the canonical HTTPS website origin and hosting provider. The repository has no production host configuration or Astro
siteorigin; the repository homepage is empty, GitHub reportshas_pages: false, and its Pages endpoint returns 404. These checks do not rule out an externally configured host. - Confirm the host/CDN request-log fields, retention and deletion behavior, access controls, subprocessors, and region; update the website privacy copy using those verified facts. Configure canonical URLs, redirects, and production headers, then inspect the deployed site's cookies, scripts, and network requests.
- Enable GitHub private vulnerability reporting and verify the private report route from an account without repository access. A read-only check of
repos/agustinbarrientos/tocus/private-vulnerability-reportingreturned{"enabled":false}on September 9, 2026. GitHub documents the repository setting. - Confirm Apple release identifiers and signing details and finish the Safari app packaging steps above.
- Complete each store's privacy, data-use, and permission declarations from the exact packaged behavior, provide the final public privacy-policy URL, and resolve store review findings.
- Recheck the deployed homepage and translated routes,
/privacy/,/support/, local assets, and deliberate outbound links with clean browser profiles before announcing availability.
.
|-- apps/
| |-- extension/ # WXT + React browser extension and extension-owned tests
| `-- website/ # Astro website with React islands
|-- packages/
| |-- theme/ # Shared icons and design tokens
| `-- ui/ # Shared Mantine theme, provider and UI compositions
`-- eslint.config.js # Repository lint configuration
Contributions are welcome while the project is young. Read CONTRIBUTING.md for branch naming, quality checks, and pull request guidance.
Please report suspected vulnerabilities privately as described in SECURITY.md, not in a public issue.
TOCus is available under the MIT License.