Civitai Companion
DISCLAMER
I built this tool because I needed it. I ship the extension as plain, unpacked source on purpose: partly for transparency, partly because if I ever stop maintaining it, anyone can point Codex or Claude at it to keep up with CivitAI API changes, add features, or fix bugs.
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 designed for recent desktop Chromium-based browsers, including Google Chrome, Microsoft Edge, Brave, Vivaldi, and Opera.
Browser-specific behavior may vary. Full functionality requires 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.