Civitai Companion

Civitai Companion is a lightweight tool for monitoring your Civitai account without keeping the website open.

It provides notifications, image and video previews, follower updates, Buzz balances, Buzz transaction history, configurable sounds and quick links back to Civitai.

Disclaimer

I originally built this tool because I needed it myself.

The browser extensions are intentionally distributed as plain, unpacked source for transparency. If I ever stop maintaining the project, anyone can inspect the code or use tools such as Codex or Claude to adapt it to future Civitai API changes, fix bugs or add features.

Windows standalone app

Civitai Companion is now also available as a standalone application for Windows 10/11 x64.

You can choose between:

- A standard Windows installer

- An MSI package

- A portable version that requires no installation

[Download the latest Windows release](https://github.com/Tar-Tarj/Civitai-companion/releases/latest)

The standalone app stores the API key securely in Windows Credential Manager and includes no telemetry, analytics, browser injection or automatic updater.

The Windows builds are currently unsigned, so Microsoft SmartScreen may display a warning.

Source code

The complete Windows application source is publicly available for transparency and inspection:

[Inspect the source code on GitHub](https://github.com/Tar-Tarj/Civitai-companion)

Also, all redirects point to civitai.red, because — DUH — that's the full version of the site 🤣.

Civitai Companion is a lightweight Manifest V3 extension for recent desktop browsers, including Firefox, Google Chrome, Microsoft Edge, Brave, Vivaldi, and Opera.

Browser-specific behavior may vary. Full functionality requires Firefox 140 or later, or Chromium 109 or later.

It keeps Civitai notifications, Buzz balances, and creator information available from one compact interface.

Version: 1.7.3

Main features

- View your Civitai profile, Blue Buzz balance, Yellow Buzz balance, and new followers received today.

- Browse recent notifications and filter comments, followers, reaction milestones, tips, and submission or bounty updates.

- Mark individual notifications or all notifications as read.

- Choose one notification delivery channel for all events: Chromium native notifications or on-page Civitai toasts.

- Assign bundled sounds separately to site activity, Tips, and follower notifications.

- Preview all four bundled sounds with direct buttons.

- Generate Creator Pulse reports on demand. Reports are never generated automatically.

- Enable an optional Floating Companion on normal websites.

- Select a preset or custom polling interval.

- Save and restore settings with a JSON backup. API key inclusion is optional and disabled by default.

Install on a Chromium-based browser

This folder is ready to load as an unpacked extension. Keep it in a permanent location after installation; moving or deleting it will break the installed extension.

1. Open the browser's extension management page:

- Brave: brave://extensions

- Google Chrome: chrome://extensions

- Microsoft Edge: edge://extensions

- Vivaldi: vivaldi://extensions

- Opera: opera://extensions

2. Enable Developer mode.

3. Select Load unpacked. Edge may label this action Load unpacked extension.

4. Select the Civitai-Companion-1.7.3 folder containing manifest.json.

5. Pin Civitai Companion to the browser toolbar for convenient access.

6. Open the extension and select the Settings button.

7. Add your personal Civitai API key, save it, and run Test connection.

When replacing files inside an already installed unpacked-extension folder, return to the extension management page and select Reload on the Civitai Companion card.

Configure the Civitai API key

Create a personal API key from your Civitai account settings. Recommended permissions:

- UserRead: account identity and profile information.

- BuzzRead: Buzz balances and supported Creator Pulse Buzz data.

- NotificationsRead: notification history and unread state.

- NotificationsWrite: mark notifications as read.

- MediaRead: optional thumbnails and media information.

Missing optional permissions disable only the related features. The Settings page includes an API Permission Inspector that shows which supported permissions are available.

The API key is stored locally in chrome.storage.local for the current browser profile. It is sent only to Civitai endpoints when the extension performs account requests.

Using the extension

Notifications and account summary

Select the toolbar icon to open the Companion. The main view shows your account, Buzz balances, followers received today, unread count, notification filters, and recent notification history. Use the refresh button for a manual update.

Notification delivery and sounds

Open Settings and choose one delivery channel:

- Native notifications displays Chromium desktop notifications.

- On-page toast displays notifications on open civitai.com or civitai.red pages.

Sound choices are divided into three groups: site activity, Tips, and followers. Only one sound is played for a polling batch, preventing overlapping audio.

Creator Pulse

Select the follower card in the main Companion view to open Creator Pulse. Reports run only when you select Generate Report or Refresh Report. The last successful report is cached locally.

Some metrics can be unavailable when the supported Civitai API does not expose enough exact data. The extension does not present approximations as exact values.

Floating Companion

Floating Companion is disabled by default. Enabling it requests optional access to normal HTTP and HTTPS pages. This permission is used only to render the isolated Companion interface; page content is not inspected.

The collapsed control is lightweight and can be dragged. Opening it loads the full Companion interface; closing it removes the full interface and returns to the small control. Browser-protected pages such as chrome:// and brave:// do not allow extension injection.

Settings backup

Use Save settings file to export preferences and Load settings file to restore them. Notification history, cached reports, trackers, and account activity are not included.

The Include API key option is disabled by default. If enabled, the exported JSON contains the API key as readable text. Store that file securely and do not share it. During import, a key in the file is ignored unless Include API key is enabled.

How it works

Civitai Companion uses one Manifest V3 background service worker as the authority for API requests, polling, account state, unread counts, notifications, and Creator Pulse reports. Chromium alarms schedule periodic work without keeping a permanent background page alive.

The toolbar popup and Floating Companion read the same shared state, so opening multiple views does not create duplicate API polling. On-page scripts handle only extension interface delivery and do not scrape page content.

All preferences, credentials, reports, and cached state remain in local browser storage. The extension has no analytics, telemetry, external companion server, cookie access, or browsing-history collection.

Troubleshooting

- Missing or invalid API key: open Settings, save the key again, then run Test connection.

- Feature reports a missing permission: create or update the Civitai API key with the required scope, then save the new key.

- No native notifications: allow notifications for the browser in both browser settings and operating-system settings.

- No on-page toasts: choose On-page toast and keep a civitai.com or civitai.red tab open.

- Floating Companion does not appear: confirm it is enabled and website access was granted. Reload existing tabs after enabling it.

- Extension changed after an update: open the extension management page and select Reload.

- Restricted browser page: Chromium blocks extensions from injecting into internal pages. This is expected.

Privacy and removal

The extension communicates directly with Civitai and stores data locally. It does not collect browsing history, inspect authentication cookies, upload page content, or send analytics.

Removing the extension clears its local browser storage, including the configured API key, settings, caches, and reports. Settings exported to JSON remain on disk until deleted manually.