GitHub - aosmith/gremlin

A local, browser-native multi-agent coordinator. A TypeScript module routes all inter-agent messages; a Svelte UI lets you watch every conversation and inject human input at any point. No server required.

Getting started

Pick a provider, get a model, and run. Here are links for the most common setups:

Once you have a provider ready, open GREMLIN → Settings (⚙) → pick your provider → paste your key (if needed) → pick a model → Save. Type a task and hit Run.

Features

Quick start

Prerequisites

Run

git clone https://github.com/aosmith/gremlin.git
cd gremlin/web
npm install
npm run dev   # → http://localhost:5173

The Vite dev server is the runtime. It provides a built-in CORS proxy for web search, auto-starts Ollama (if installed), and launches the browser sidecar. Every user runs npm run dev locally — there is no separate production deployment step.

Build (optional)

npm run build   # → dist/index.html (single self-contained file)

The built file can be hosted statically, but loses the CORS proxy and sidecars. For the full experience, use npm run dev.

Modes

Switch modes with the tab bar below the navbar. Each mode loads a different set of agents. Agent configs are saved per-mode.

Click + New Mode to save your current agent configuration as a named mode. Custom modes can be deleted; the seven built-in ones cannot.

Dev mode (Engineering)

When the Engineering mode is active, a 📁 Open Folder button appears in the toolbar. Select a local project directory and the agents gain file system tools:

Tool calls appear as messages in the Activity Monitor. Written files show up in a file tree in the left sidebar; click any file to open it in the code viewer panel.

The File System Access API requires Chrome 86+ or Edge 86+. Firefox does not support it.

Browser tools

Agents can interact with a live browser when a sidecar server is running at http://127.0.0.1:3131:

Web search

Agents can search the web and fetch pages during a run. Two search tools are available:

DuckDuckGo is the default search provider — no API key needed. For better results, configure a provider in Settings:

WebLLM (in-browser inference)

Select WebLLM 🌐 in Settings to run a quantised model entirely in your browser using WebGPU. No API key or external server needed.

Requirements: Chrome 113+ or Edge 113+ (WebGPU). Firefox and Safari do not support WebGPU by default.

Workflow:

1. Open Settings → select WebLLM → pick a model
2. Click Run — the model downloads to your browser cache on first use (~500 MB – 4 GB depending on model)
3. A progress bar appears below the navbar during loading; subsequent runs use the cache instantly

Available models (curated list):

LLM providers

Open ⚙ Settings to pick a provider. The provider grid covers:

API keys are stored only in localStorage and never sent anywhere except your chosen endpoint.

Agent communication protocol

Agents respond with JSON. GREMLIN parses and routes the messages automatically:

{
  "analysis": "My reasoning goes here",
  "messages": [
    { "to": "critic",      "content": "Can you verify finding #3?" },
    { "to": "synthesizer", "content": "Final results: …" }
  ],
  "done": false,
  "result": null
}

• "done": true marks the agent's task as complete
• "result" contains the final output (the synthesizer's result is shown to the user)
• Plain-text responses are accepted as a fallback — treated as a final result

Agents also have access to protocol tools (send_message, mark_done) for providers that support tool calling.

Architecture

┌──────────────────────────────────────────────────────────┐
│                         Browser                          │
│                                                          │
│  ┌─────────────────┐    ┌────────────────────────────┐   │
│  │  Svelte 5 UI    │───▶│  Coordinator (TypeScript)  │   │
│  │  (TypeScript)   │◀───│  • Agent registry          │   │
│  │                 │    │  • Message routing         │   │
│  │  Activity       │    │  • Session state           │   │
│  │  Monitor        │    └────────────────────────────┘   │
│  │  File Tree      │                                     │
│  │  Code Viewer    │                                     │
│  └────────┬────────┘                                     │
│           │                                              │
│  ┌────────▼────────┐    ┌────────────────────────────┐   │
│  │  AgentRunner.ts │    │  File System Access API    │   │
│  │  • Calls LLM    │    │  write_file / read_file /  │   │
│  │  • Tool loop    │───▶│  list_directory            │   │
│  │  • Routes msgs  │    │  (Engineering mode only)   │   │
│  │  • Web search   │    └────────────────────────────┘   │
│  └────────┬────────┘                                     │
│           │ fetch()  or  WebGPU (WebLLM)                 │
└───────────┼──────────────────────────────────────────────┘
            ▼
   ┌─────────────────────────────────┐
   │  LLM                            │
   │  Anthropic / OpenAI / Gemini    │
   │  Ollama / Groq / OpenRouter     │
   │  Together / WebLLM (WebGPU)     │
   └─────────────────────────────────┘

Project structure

gremlin/
├── web/
│   ├── src/
│   │   ├── App.svelte              # Main layout, navbar, mode bar, modals
│   │   ├── app.css                 # Glass-morphism design system
│   │   ├── lib/
│   │   │   ├── types.ts            # Types, providers, mode presets, agent configs
│   │   │   ├── coordinator.ts      # In-memory agent state & message router
│   │   │   ├── api.ts              # LLM call functions (all formats + tool loops)
│   │   │   ├── agentRunner.ts      # Multi-agent orchestration engine
│   │   │   ├── store.svelte.ts     # Reactive global state (Svelte 5 runes)
│   │   │   ├── filesystem.ts       # File System Access API wrapper
│   │   │   ├── tools.ts            # Tool definitions + executor (dev/search/protocol)
│   │   │   ├── webllm.ts           # WebLLM / WebGPU wrapper
│   │   │   ├── cleanContent.ts     # Protocol JSON → readable display text
│   │   │   ├── tableCards.ts       # Prose enhancement (tables, callouts)
│   │   │   ├── sanitize.ts        # DOMPurify XSS sanitization wrapper
│   │   │   ├── search.ts          # Web search implementation
│   │   │   ├── cloudflare.ts     # Cloudflare Browser Rendering crawl
│   │   │   ├── teamGenerator.ts   # Dynamic team generation
│   │   │   └── headless.ts        # Headless browser integration
│   │   └── components/
│   │       ├── ActivityMonitor.svelte  # Real-time message feed
│   │       ├── AgentCard.svelte        # Sidebar agent widget
│   │       ├── AgentPanel.svelte       # Agent detail + human input
│   │       ├── AgentEditModal.svelte   # Add/edit agent dialog
│   │       ├── SettingsModal.svelte    # Provider + API settings
│   │       ├── HelpModal.svelte        # Setup guide + onboarding
│   │       ├── SessionHistory.svelte   # Past session browser
│   │       ├── FileTree.svelte         # Project file tree (dev mode)
│   │       ├── CodeViewer.svelte       # File content viewer (dev mode)
│   │       └── NewModeModal.svelte     # Create custom mode dialog
│   ├── scripts/
│   │   └── smoke-test.mjs          # Post-build smoke test
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── proxy/
│   ├── worker.js                   # Cloudflare Worker CORS proxy
│   └── wrangler.toml
├── setup.sh                        # One-shot build script
└── package.json                    # Root npm scripts

Deployment

The recommended way to run GREMLIN is npm run dev on your local machine. The Vite dev server provides a CORS proxy, auto-starts Ollama, and launches the browser sidecar — none of which are available when hosting the built file statically.

Static hosting (advanced)

The built file (web/dist/index.html) can be hosted on Cloudflare Pages, GitHub Pages, Netlify, etc. Most LLM providers (OpenAI, Anthropic, OpenRouter, Gemini, Together) support browser CORS natively, so they work without a proxy. However, web search and some services (Groq, DuckDuckGo, Brave Search) need a CORS proxy.

To deploy your own proxy for static hosting:

cd proxy
npx wrangler login
npx wrangler deploy

Then update the proxy URL in Settings → Advanced.

Local LLM providers (Ollama, LM Studio)

If you host the site on a custom domain (e.g. gremlin.example.com) and want to use a local Ollama instance, you need to allow the origin:

OLLAMA_ORIGINS=https://gremlin.example.com ollama serve

Ollama only accepts requests from localhost by default. LM Studio has a similar CORS setting in its server preferences.

Troubleshooting

API 401 / 403 → Check your API key in Settings.

CORS error or Failed to fetch in browser console → Make sure you are running via npm run dev — the dev server provides the CORS proxy → If using the built HTML file: serve over HTTP, not file://, and configure a proxy URL in Settings → If using Ollama from a hosted site: set OLLAMA_ORIGINS=https://your-domain.com when starting Ollama

WebLLM: WebGPU is not available → Use Chrome 113+ or Edge 113+. Firefox and Safari do not support WebGPU by default.

WebLLM: model loads but produces garbled output → Some quantised models struggle with strict JSON. Switch to a larger model or use a server-side provider.

Agents produce plain text instead of JSON → Smaller or older models sometimes ignore the JSON format instruction. Try a larger or more instruction-tuned model.

License

PolyForm Noncommercial 1.0.0 — free for personal and noncommercial use.