Quick Start

This is the shortest path to a working Swan extension.

Quick command

Run the setup script from the repository root:

npm run setup

The script installs dependencies when needed, builds the extension, prints the absolute output/chrome-mv3 path, and tries to open chrome://extensions.

Requirements

RuntimeNode.js 20 or newer

Required by the VitePress docs and safe for the WXT extension toolchain.

BrowserChromium-based browser

Use a Chromium-based browser that can load unpacked Manifest V3 extensions.

VoiceElevenLabs agent

You need an API key, Agent ID, ElevenLabs agent phone number ID, and a paid/upgraded Twilio number.

Optional SMSTwilio account

Only needed if you want Swan to send text alerts in addition to calls.

Setup path

1. 1
   Install or build Swan.

   Run npm run setup from a source checkout.

2. 2
   Open the extension.

   Load the unpacked extension folder from chrome://extensions, then open Swan from the toolbar icon.

3. 3
   Configure Swan settings.

   Enter the recipient number and ElevenLabs call credentials in the Swan options page.

4. 4
   Add or review tracked domains.

   Swan ships with a seed list and lets you add, disable, or remove domain rules.

5. 5
   Send a test alert.

   Use the Send test alert button, confirm the call arrives, then review the Logs page.

1. Install prerequisites

• Node.js 20 or newer.
• npm.
• A Chromium-based browser that supports unpacked extensions.
• An ElevenLabs account with a Conversational AI agent.
• A paid/upgraded Twilio phone number connected in ElevenLabs for AI calls.
• Optional: a Twilio account with an SMS-capable phone number.

2. Build the extension

From the repository root:

npm run setup

The setup script:

• Installs npm dependencies if node_modules is missing.
• Generates bundled import data from config.yaml if that local file exists.
• Runs the production extension build.
• Verifies output/chrome-mv3/manifest.json exists.
• Prints the exact extension directory to load in Chromium.
• Tries to open chrome://extensions.

Optional: copy config.example.yaml to config.yaml before setup if you want to keep phone, provider, and tracked-domain values in one local file.

3. Load Swan in Chromium

1. Open chrome://extensions.
2. Enable Developer Mode.
3. Click Load unpacked.
4. Select the output/chrome-mv3 path printed by npm run setup.
5. Keep the folder in place. Chromium loads the extension from that local build output.

After first install, Swan opens its settings page automatically. If it does not, click the Swan extension icon.

4. Configure the options page

Open Swan settings and save each configuration group:

Group	Required values
Phone Configuration	Recipient phone number, Start voice call toggle, Send optional SMS toggle, monitoring toggle, cooldown minutes
ElevenLabs Voice Call	API key, Agent ID, Agent phone number ID
Twilio SMS	Optional Account SID, Auth Token, SMS From number

Use E.164 phone-number formatting, for example +15551234567.

If you built with config.yaml, open General and click Import data before manually editing these cards. Import merges configured values and tracked domains into this browser profile.

Before the first Swan test alert, configure the ElevenLabs agent prompt and knowledge base. Paste the Swan system prompt into the agent instructions, set the first message, and upload the recovery playbook as the agent knowledge base.

5. Test the intervention loop

1. Click Send test alert in Swan settings.
2. Confirm an AI call arrives from the ElevenLabs-connected number.
3. If SMS is enabled, confirm an SMS arrives from the Twilio From number.
4. Open Logs and verify the latest event has call and SMS statuses.

6. Add a domain

Open Domain Tracking, add a domain such as example.com, and keep it enabled. Swan matches the domain and its subdomains.

Swan v0 uses configured domain rules only. It does not inspect page contents, classify images or videos, install DNS rules, or run a proxy.

Next

• Provider console details: Provider setup
• Loading problems: Troubleshooting
• Runtime shape: Architecture