IntentLock

Declare what you are doing. IntentLock watches your tabs and locks the page when you drift.

Heuristics run with no API key. An optional AI provider in Settings is a second opinion only.

1. Open Releases and download the latest IntentLock-*.zip.
2. Unzip it.
3. Chrome → chrome://extensions → enable Developer mode.
4. Load unpacked → select the unzipped folder.
5. Open a new tab. Declare your intent. → set default policy → Lock in an intent.

From source: clone this repo, load the repo folder unpacked, then npm test.

1. Declare your intent.
2. Default intent type + strictness (you can change this later in Settings)
3. Type this session's intent and optional time budget. Click Lock in.

AI providers are not part of setup. Add one in Settings if you want a second drift check.

• Blocks the page when you leave your declared intent
• Requires a written reflection to continue, or Close tab / End session
• Stores session data only on this device

• No accounts, cloud sync, or telemetry
• No habit dashboard or rewards
• No Chrome Web Store listing yet (use the GitHub Release zip)

See docs/privacy-policy.md. Optional remote LLM providers receive minimized intent and origin-only context when you configure a key.

MIT © 2026 Harsha Balakrishnan

flowchart TD
    A([User starts session on new tab]) --> B[Background monitors tabs]
    B --> C{Tab switch or page load?}
    C --> D[Log event to session]
    D --> E{On cooldown for this domain?}
    E -- Yes --> F[Skip — user already overrode]
    E -- No --> G[Heuristic drift check\nevaluatePolicyDrift]
    G -- Score ≥ 0.7 --> I[Trigger intervention]
    G -- Below threshold --> H[LLM drift check\nif API key set]
    H -- Not aligned + confident --> I
    H -- Aligned or no API key --> J[Continue browsing]
    I --> K[Try shadow-DOM overlay\non current tab]
    K -- Content script present --> L[Full-screen overlay]
    K -- No content script --> M[Replace tab with intervention.html]
    L --> N{User choice}
    M --> N
    N -- Override + reflection --> O[Return to URL · 5 min cooldown]
    N -- Close tab --> P[Tab closed]

Two-step wizard on the new tab page, then the session form:

After onboarding, each new tab shows the session form: type your specific intent, set an optional time budget, and click Lock in. AI providers are configured later in Settings, not during onboarding.

graph LR
    subgraph Pages
        NT[newtab.html\nnewtab.js]
        OPT[options.html\noptions.js]
        INT[intervention.html\nintervention.js]
        DIAG[diagnostics.html\ndiagnostics.js]
        POP[popup.html\npopup.js]
    end

    subgraph Content
        CS[content.js]
        PT[page-tracker.js]
        OV[intervention-overlay.js]
    end

    subgraph Background["background.js (service worker)"]
        BG[Session · Drift · Intervention\nCooldown · Config · History]
    end

    subgraph Modules
        HP[heuristic-policy.js\nIntent + Site taxonomy\nPolicy engine]
        DR[drift.js\nLegacy heuristics]
        LLM[llm.js + providers.js\nLLM drift check]
        DC[drift-cache.js\n60s TTL cache]
        EL[error-log.js\nDiagnostics]
        LB[llm-backoff.js\nQuota guard]
        DS[distraction-sites.js\nDefault domain list]
    end

    CS -->|CONTENT_EVENT\nSHOW_INTERVENTION| BG
    PT -->|PAGE_DWELL\nSPA_NAVIGATION| CS
    OV -->|INTERVENTION_TRANSITION| BG
    NT -->|SESSION_STARTED\nEND_ACTIVE_SESSION| BG
    POP -->|GET_SESSION\nSESSION_CLEARED| BG
    BG -->|CONFIG_UPDATED reload| BG
    BG --> HP
    BG --> DR
    BG --> LLM
    LLM --> DC
    LLM --> LB
    BG --> EL

Every tab switch or page load runs through this pipeline:

flowchart TD
    A[URL arrives in evaluateDrift] --> B{Active session?}
    B -- No --> Z[Exit]
    B -- Yes --> C{Debounce\n< 2s since last eval?}
    C -- Yes --> Z
    C -- No --> D{Domain on\noverride cooldown?}
    D -- Yes --> Z
    D -- No --> E[evaluatePolicyDrift\nheuristic-policy.js]
    E --> F{shouldIntervene?}
    F -- Yes --> G[triggerIntervention]
    F -- No --> H{LLM configured?}
    H -- No --> Z
    H -- Yes --> I{Cache hit?}
    I -- Yes --> J{confidence ≥ 0.7\n+ not aligned?}
    I -- No --> K[callLLM\nprompt → JSON]
    K --> L[setCachedDrift\n60s TTL]
    L --> J
    J -- Yes --> G
    J -- No --> Z
    G --> M{Content script\nresponding?}
    M -- Yes --> N[SHOW_INTERVENTION\nshadow-DOM overlay]
    M -- No --> O[Tab redirect →\nintervention.html]

See docs/heuristic-policy.md for the full reference.

Intent categories (12): job_search, deep_work, coding, learning, writing, research, admin, creative, health, shopping, communication, entertainment_allowed

Site categories (21, 529 domains): social_media, short_video, streaming, gaming, news, forums, shopping, email, messaging, job_boards, professional_network, documentation, code_forge, ai_tools, finance, sports, adult, gambling, memes, productivity, health, travel

Strictness presets:

Category alignment: job_search intent + hostname in job_boards or professional_network → aligned even without keyword match. Same logic for all 12 intent categories.

Configured in Settings → LLM provider. The API key is stored in chrome.storage.session when available (cleared on browser close), with a local fallback only when session storage is unavailable. Remote providers receive minimized intent and origin-only context.

LLM is optional. Without a key, only heuristic scoring runs. With a key, LLM provides a second opinion only when heuristics score below the threshold.

Open via the extension's options page (right-click icon → Options, or Settings button in popup).

See docs/storage-schema.md for full field-by-field reference.

Key chrome.storage.local entries:

chrome.storage.session (cleared on browser close when available):

node --test tests/heuristic-policy.test.mjs   # 48 tests — policy engine
node --test tests/background.test.mjs          # 2 tests  — service worker helpers
node --test tests/drift.test.mjs               # heuristic drift scoring
node --test tests/drift-cache.test.mjs         # TTL cache
node --test tests/llm-backoff.test.mjs         # quota backoff
node --test tests/providers.test.mjs           # provider config validation
node --test tests/page-tracker.test.mjs        # dwell tracking + SPA detection
node --test tests/error-log.test.mjs           # diagnostic log
node --test tests/static-smoke.test.mjs        # manifest + asset integrity
npm test                                        # all tests
npm run verify:static                           # static/runtime/release checks

Uses Node's built-in node:test + assert/strict. No dependencies or test runner to install.

To validate and build a release artifact locally:

npm run validate:version -- v1.5.1
npm run package

The package command creates a deterministic ZIP containing only the extension runtime allowlist. Tests, docs, and development files stay out of the release artifact.

See docs/development.md for full setup, reload workflow, and contribution guide.

Quick start:

# No build step — ES modules loaded directly by Chrome
# Load the folder in chrome://extensions → Developer mode → Load unpacked

# After any JS change: Extensions page → refresh icon on the IntentLock card
# After manifest.json change: same as above
# After content.js change: also reload the affected tab

See CHANGELOG.md.