# Anouk

> A lightweight, MIT-licensed framework from Skelf-Research for building AI-powered browser extensions. Plugs into any OpenAI-compatible provider, ships a CLI scaffold, a per-request response cache, a per-provider rate-limit queue, and a runtime settings panel.

## What Anouk Is

Anouk is two things in one package:

1. A runtime library (`AIService`, `configManager`, `settingsPanel`) you can import into any browser extension to add AI features.
2. A CLI (`anouk init`, `anouk generate`) that scaffolds a working Manifest V3 extension with the runtime pre-wired.

It is published to npm as `anouk` and developed in the open at `github.com/skelf-research/anouk` under the MIT license. The framework expects Manifest V3 (Chrome / Chromium-style) extensions and ships a default template tested against that target.

## The Architectural Bet

Anouk is built on the bet that, for a meaningful slice of AI features, the model call belongs in the extension itself rather than on a backend you operate. The user supplies their own provider URL, API key, and model in the runtime settings panel. The extension calls the provider directly over fetch. There is no server on the critical path.

This produces three properties:

1. **Lower latency.** No extra hops through your backend.
2. **Stronger privacy.** Your content never crosses a server the developer controls.
3. **Zero operating cost.** Static marketing site + open-source distribution; the user pays their own provider directly.

For features that need centralized guardrails, evaluation, billing, or multi-user coordination, a backend is still required — Anouk's `AIService` happily points at one. But the defaults assume the simpler architecture.

## Verified from the Repo

- Package name: `anouk` on npm.
- License: MIT.
- Author: Dipankar Sarkar / Skelf-Research.
- Source: `src/aiService.js`, `src/configManager.js`, `src/settingsPanel.js`, `src/extension.js`, `src/extensionInjector.js`, `src/gmailJsLoader.js`.
- CLI entry: `bin/anouk-cli.js` (commands: `init`, `generate extension|service|config`, `help`).
- Templates: `templates/extension-template.js`, `templates/service-template.js`, `templates/config-template.js`.
- Build: esbuild bundles `src/*` to `dist/`.
- Manifest: Manifest V3 with `host_permissions` for the provider URLs you use, `storage` and `unlimitedStorage` permissions.

## Provider Support

The README documents the following OpenAI-compatible endpoints:

| Provider | URL |
|----------|-----|
| OpenAI | `https://api.openai.com/v1/chat/completions` |
| Anthropic | `https://api.anthropic.com/v1/messages` |
| Together.xyz | `https://api.together.xyz/v1/chat/completions` |
| Ollama | `http://localhost:11434/v1/chat/completions` |
| Hugging Face Inference | `https://api-inference.huggingface.co/models/<model>` |

Any other provider that speaks the OpenAI chat-completions request shape will work by setting `providerUrl` to its endpoint.

## CLI Surface

- `anouk init <project-name>` — scaffold a new Manifest V3 extension with the AI service, config manager, and settings panel pre-wired.
- `anouk generate extension <name>` — drop an extension template into an existing project.
- `anouk generate service <name>` — drop an AI service template.
- `anouk generate config <name>` — drop a config template.
- `anouk help` — show the help message.

## Configuration

Configuration can be supplied two ways:

1. **At runtime via the settings panel.** The user opens the bundled settings panel and supplies `providerUrl`, `apiKey`, `model`, and `systemPrompt`. Values persist in `chrome.storage.local`.
2. **In code via `aiConfig.js`.** Export a default object with the same fields. Useful for hardcoded development setups.

```javascript
// src/aiConfig.js
export default {
  providerUrl: 'https://api.together.xyz/v1/chat/completions',
  apiKey: 'your-api-key',
  model: 'meta-llama/Llama-3-70b-chat-hf',
  systemPrompt: 'You are a helpful assistant.'
};
```

## How AIService Works

`AIService.call(instruction, content, requestId, cacheKey?)` is the main entry point.

- The cache is keyed by `${requestId}_${cacheKey}`. If a cached response exists, it is returned immediately.
- Otherwise the request is dispatched to the configured provider in the OpenAI chat-completions request shape.
- The response is parsed, cached, and returned to the caller.
- The per-provider queue serializes requests so click-heavy users do not stampede the API.

## Comparisons

- **vs Plasmo:** Plasmo is a full extension framework (build, manifests, React components, multi-browser targets). Anouk is narrower — it is the AI runtime you import into a Plasmo-built extension. They compose.
- **vs WXT:** WXT is a Vite-powered extension framework with first-class TypeScript and multi-browser targets. Anouk is, again, the AI runtime inside it. They compose.

Anouk does not compete with Plasmo or WXT on build tooling. It competes with the hand-rolled fetch wrapper + cache + queue + settings panel + manifest you would otherwise build yourself.

## Blog Topics

- [Browser extensions as AI app distribution](https://anouk.skelfresearch.com/blog/browser-extensions-as-ai-app-distribution/) — why the browser is one of the best distribution channels for AI features.
- [What ships in 5 minutes of scaffolding vs 5 days of hand-rolling](https://anouk.skelfresearch.com/blog/scaffold-in-5-minutes-vs-5-days/) — a line-by-line accounting of the boilerplate Anouk replaces.
- [Why AI features belong in the extension, not the backend](https://anouk.skelfresearch.com/blog/ai-belongs-in-the-extension-not-the-backend/) — the architectural argument for client-side AI calls.

## Use Cases

Four worked examples, each a real page on the site with code:

- [AI writing assistant in the sidebar](https://anouk.skelfresearch.com/use-cases/ai-writing-assistant/) — a sidebar that rewrites the selected text (shorter, friendlier, more formal) using whatever model the user configured. No backend; the user's own key. Cache and queue keep rapid rewrites cheap and rate-limit safe.
- [One-click page summarizer](https://anouk.skelfresearch.com/use-cases/page-summarizer/) — a toolbar button that summarizes the current page. The content script reads the DOM and calls the provider directly, so the article text never touches a server you run. The cache is URL-keyed, so re-clicking the same article returns the cached summary.
- [Private, local-only extension with Ollama](https://anouk.skelfresearch.com/use-cases/local-ollama-extension/) — point `providerUrl` at a local Ollama server and the extension gets AI features with no cloud call at all. Because Anouk speaks the OpenAI chat-completions shape, Ollama is a drop-in; the user can flip between local and hosted at runtime.
- [Inbox copilot for webmail](https://anouk.skelfresearch.com/use-cases/inbox-copilot/) — a content script that suggests reply drafts inside a webmail UI. The draft is keyed by thread id, so re-opening a thread reuses the earlier draft, and the queue paces requests as the user moves through the inbox.

## Full Page Index

Every content page on the site:

- Home — https://anouk.skelfresearch.com/
- Features — https://anouk.skelfresearch.com/features/
- How it works — https://anouk.skelfresearch.com/how-it-works/
- Quickstart — https://anouk.skelfresearch.com/quickstart/
- FAQ — https://anouk.skelfresearch.com/faq/
- Glossary — https://anouk.skelfresearch.com/glossary/
- About — https://anouk.skelfresearch.com/about/
- Use cases (index) — https://anouk.skelfresearch.com/use-cases/
- Use case: AI writing assistant — https://anouk.skelfresearch.com/use-cases/ai-writing-assistant/
- Use case: page summarizer — https://anouk.skelfresearch.com/use-cases/page-summarizer/
- Use case: local Ollama extension — https://anouk.skelfresearch.com/use-cases/local-ollama-extension/
- Use case: inbox copilot — https://anouk.skelfresearch.com/use-cases/inbox-copilot/
- Compare (index) — https://anouk.skelfresearch.com/compare/
- Compare: Anouk vs Plasmo — https://anouk.skelfresearch.com/compare/plasmo/
- Compare: Anouk vs WXT — https://anouk.skelfresearch.com/compare/wxt/
- Blog (index) — https://anouk.skelfresearch.com/blog/
- Blog: Browser extensions as AI app distribution — https://anouk.skelfresearch.com/blog/browser-extensions-as-ai-app-distribution/
- Blog: 5 minutes of scaffolding vs 5 days of hand-rolling — https://anouk.skelfresearch.com/blog/scaffold-in-5-minutes-vs-5-days/
- Blog: Why AI features belong in the extension — https://anouk.skelfresearch.com/blog/ai-belongs-in-the-extension-not-the-backend/

## What Anouk Is Not

- Not a build tool. It does not bundle, hot-reload, or generate manifests.
- Not a multi-browser framework today. The current template targets Chrome / Chromium-style Manifest V3.
- Not a hosted product. There is no SaaS to sign up for; the framework is npm + GitHub.
- Not a model provider. It speaks to providers you choose; it does not run inference.

## Links

- Home: https://anouk.skelfresearch.com/
- Docs: https://docs.skelfresearch.com/anouk/
- GitHub: https://github.com/skelf-research/anouk
- npm: https://www.npmjs.com/package/anouk
- RSS: https://anouk.skelfresearch.com/rss.xml