Quick Start

Add Coign to any HTML page in two lines:

<script>
  window.Coign = window.Coign || function() {
    (window.Coign.q = window.Coign.q || []).push(arguments);
  };
  Coign('init'); // shell first — model loads on ask
</script>
<!-- Prefer the ES loader (code-split). IIFE is ~2.1 MB gzip. -->
<script type="module" src="./dist/coign-loader.es.js"></script>
<!-- or: <script src="./dist/coign-sdk.iife.js"></script> -->

The window.Coign stub queues calls before the SDK loads. Prefer coign-loader.es.js so WebLLM stays deferred; use the IIFE only when you need a single classic script tag (~2.1 MB gzip).

Edit on GitHub

Installation

CDN (Recommended)

Use coign-loader.es.js with the queue stub above (ES modules). Fall back to coign-sdk.iife.js for classic script tags — that bundle includes WebLLM (~2.1 MB gzip).

ESM (npm)

npm install coign-sdk

import { init, config } from 'coign-sdk';

init(); // or init({ preset: 'coign-lite', engage: 'ask' });
config({ theme: { accent: '#6366f1' } });

Edit on GitHub

Configuration

The config function accepts a flat object of options. Coign is client-side only: no cloud API calls are made during inference, so no API key or remote endpoint is required.

Edit on GitHub

API Reference

init(options)

Initializes the SDK with a model preset or custom configuration. Must be called before other API methods.

init(); // or init({ preset: 'coign-lite', engage: 'ask' });
init({ model: 'Llama-3.2-3B-Instruct-q4f16_1-MLC' });

config(options)

Updates configuration after init. Merges with existing config.

config({ theme: { accent: '#10b981' } });

ask(message)

Sends a message to the agent and returns a Promise that resolves with the response string.

const answer = await Coign.ask('Summarize this page');

createWidget()

Creates and mounts the chat widget into the page. The widget is a singleton — calling this again returns the same instance.

Coign.createWidget();
Coign.showWidget();   // open panel
Coign.hideWidget();   // close panel
Coign.destroyWidget(); // remove from DOM

showConfirmDialog(message, risk, confirmationValue?)

Shows a native <dialog> for risky operations. Returns Promise<boolean>.

const allowed = await Coign.showConfirmDialog(
  'Delete all user data?',
  'destructive',
  'DELETE'
);

Edit on GitHub

Browser Check

Use checkSupport() to verify WebGPU and estimate available VRAM before calling init():

const check = await Coign.checkSupport();
if (!check.supported) {
  alert('Coign requires WebGPU. Reason: ' + check.reason);
}

Returns an object with:

• supported — boolean, true if browser can run Coign
• reason — human-readable explanation when unsupported
• webgpu — boolean, true if navigator.gpu exists
• browser — detected browser name
• estimatedVramMb — rough VRAM estimate from GPU adapter

Edit on GitHub

Download Progress

Model downloads are large (400 MB–4.5 GB). You can track progress with callbacks or events:

init({
  preset: 'coign-balanced',
  onDownloadProgress: (p) => {
    console.log(p.stage, p.progress); // 'downloading', 0.42
  },
  onDownloadComplete: () => console.log('Done!'),
  onDownloadError: (err) => console.error(err.message),
});

The built-in widget also shows a progress overlay automatically. You can cancel a slow download:

Coign.cancelEngineInit(); // or click Cancel in the widget overlay

Edit on GitHub

Lifecycle

Check SDK state at any time:

Coign.isInitialized(); // true after init() resolves
Coign.isReady();       // true when model is loaded and engine is ready

Retry a failed init with exponential backoff:

Coign.retryInit({ preset: 'coign-balanced', maxRetries: 3, retryDelayMs: 2000 });

Swap models without destroying history or tools:

await Coign.swapModel('coign-code');

Edit on GitHub

Architecture

Coign is designed as a set of layered modules:

• Core (src/core/) — Configuration, preset resolution, and model initialization
• LLM (src/llm/) — WebLLM engine wrapper, chat engine, tool loop (manual and native)
• Tools (src/tools/) — Built-in tools (searchPage, getPageOutline, getElement) and host tool registration
• Store (src/store/) — Page outline store and MiniSearch index for in-page search
• UI (src/ui/) — Shadow DOM chat widget, theming, inline mount, focus trap, and modal dialog
• Events (src/events.ts) — Typed event bus for loose coupling between modules
• Queue Loader (src/queue-loader.ts) — IIFE stub/replay for CDN loading

All modules are pure ESM with .js extensions. Browser-only code guards with typeof window !== 'undefined' so it can be imported in Node/Vitest contexts.

Edit on GitHub

Model Presets

Preset names resolve to WebLLM model IDs. Models are downloaded once and cached for offline inference — no cloud calls.

Edit on GitHub

Custom Tools

Register custom tools with Coign.registerTool:

Coign.registerTool({
  name: 'sendAnalytics',
  description: 'Send a page-view event to analytics',
  parameters: {
    type: 'object',
    properties: {
      page: { type: 'string', description: 'Page path' }
    },
    required: ['page']
  },
  execute: async ({ page }) => {
    gtag('event', 'page_view', { page });
    return { sent: true };
  }
});

Tools are called via an XML-based manual loop by default. The LLM generates <tool> tags, the SDK parses them, executes the matching tool, and feeds the result back into the conversation.

Edit on GitHub

Theming

Pass a theme object to config():

Coign.config({
  theme: {
    accent: '#6366f1',
    text: '#1e293b',
    bg: '#ffffff',
    radius: '0.5rem'
  }
});

Edit on GitHub

Risk Tiers

Operations that modify state or access sensitive data require user confirmation:

Edit on GitHub