Flick

A command palette for Chrome. Press a shortcut, type a command, and go — custom URL aliases, text snippets, and built-in developer tools in one fast, keyboard-first overlay.

---

Overview

Flick brings the speed of macOS Spotlight to your browser. Instead of reaching for the mouse or typing long URLs, press ⌘⇧K and type a few characters to jump anywhere or trigger an action.

What you type	What happens
gh	Opens github.com in a new tab
mdn	Opens MDN Web Docs
email	Copies your email address to the clipboard
ss	Takes a screenshot of the current tab
cp	Picks a color from anywhere on the page
dark	Toggles dark mode on the page
grid	Overlays a 12-column design grid
cache	Clears cache and reloads the page
yt tony stark	Searches YouTube for "tony stark"

Everything is configurable from a polished settings page — add your own shortcuts, snippets, and toggle built-in tools on or off.

---

Features

URL Aliases

Custom triggers that navigate to any URL. Managed from the Settings page or added via quick-add chips right inside the palette.

• Case-insensitive trigger matching (exact match ranks highest)
• Fuzzy search across trigger, description, keywords, and URL (powered by Fuse.js)
• Open in current tab or new tab
• Enable/disable without deleting
• Synced across devices via chrome.storage.sync
• 12 popular-site suggestions ready to add in one click

URL Templates

Shortcuts can include a {variable} placeholder that accepts input from the palette. Type the trigger followed by a value to search or navigate with dynamic parameters.

You type	Result
yt	Opens youtube.com
yt tony stark	Searches YouTube for "tony stark"
backend-pull 123	Opens github.com/../pull/123

• One {variable} placeholder per template URL
• URL-encoded substitution for safe navigation
• Falls back to the bare url when no value is provided
• Set up in Settings → Shortcuts → New/Edit → Template URL field

Text Snippets

Reusable text blocks that copy to your clipboard on select. Perfect for email addresses, phone numbers, signatures, or any frequently-typed text.

• Fuzzy-searchable by trigger, label, and keywords
• Synced alongside aliases via chrome.storage.sync
• One-click suggestions for common snippets (email, address, phone, name)

Developer Tools

Thirteen built-in commands that run directly on the active tab. Search by name or keyword — no setup required.

Category	Commands
Capture & Visual	Screenshot (viewport / select element), Color picker, Toggle dark mode, Toggle column grid, Toggle pixel rulers
Tab Management	Duplicate tab, Toggle pin, Toggle mute, Move to new window
Page Actions	Bookmark page, Copy URL, Copy as Markdown link
Cache & Storage	Clear cache + reload

Design & UX

• Shadow DOM isolation — the palette renders in a closed shadow root, immune to host-page CSS
• Keyboard-first — full cmdk navigation with ↑/↓, Enter, Esc
• Page interaction guard — while the palette is open, keyboard events are captured so host-page shortcuts (e.g. GitHub's /) never fire
• Restricted-page detection — gracefully handles chrome://, Web Store, and other blocked URLs
• Toast feedback — every action confirms with a lightweight toast
• Polished settings — sidebar navigation, modal-based forms, sticky positioning, ambient accents

---

Installation

From source (development)

Prerequisites: Node.js 20+, npm, Google Chrome

git clone https://github.com/Anikets08/flick.git
cd flick
npm install
npm run dev

WXT launches Chrome with the extension loaded and hot-reloading enabled. If it doesn't open automatically:

1. Go to chrome://extensions
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked
4. Select the .output/chrome-mv3 directory

Production build

npm run build      # outputs to .output/chrome-mv3/

Load the built folder unpacked, or run npm run zip to package for the Chrome Web Store.

---

Usage

Opening the palette

Platform	Shortcut
macOS	⌘⇧K (Command + Shift + K)
Windows / Linux	Ctrl+Shift+K

Fallback: click the Flick icon in the toolbar.

Chrome requires Ctrl or ⌘ on every extension shortcut. Change it anytime at chrome://extensions/shortcuts.

Palette controls

Key	Action
↑ / ↓	Navigate results
Enter	Select highlighted item
Esc	Close palette
Click outside	Close palette

Managing shortcuts & snippets

Open the settings page from the palette footer (Settings button) or by clicking the toolbar icon. The settings page features:

• Sticky sidebar navigation between Shortcuts, Snippets, and Features
• Modal-based forms — click New to add, or Edit on any row to modify
• Toggle switches to enable/disable individual entries without deleting
• One-click suggestions to bootstrap an empty collection

---

Tech Stack

Layer	Choice	Why
Extension framework	WXT	Vite-native, file-based entrypoints, cross-browser, excellent DX
UI	React 19 + TypeScript	Strong ecosystem, type safety, matches modern standards
Styling	Tailwind CSS 4	Utility-first, fast iteration, scoped via Shadow DOM
Command palette	cmdk	Accessible, keyboard-first, battle-tested
Fuzzy search	Fuse.js	Lightweight, typo-tolerant, ideal for palette-scale datasets
State	Zustand	Minimal, works well in extensions
Icons	Lucide React	Consistent, tree-shakeable

---

Project Structure

flick/
├── docs/                          # Design docs & architecture
├── public/                        # Extension icons & static assets
├── src/
│   ├── assets/styles/             # Global CSS + Tailwind theme
│   ├── components/                # React UI (FlickShell)
│   ├── data/                      # Default aliases, snippets, dev tools
│   ├── entrypoints/
│   │   ├── background/            # Service worker — commands, actions
│   │   ├── flick.content/         # Overlay UI (Shadow DOM)
│   │   ├── flick-guard.content/   # Keyboard event guard
│   │   └── options/               # Settings page
│   ├── hooks/                     # Search & interaction hooks
│   ├── lib/
│   │   ├── actions/               # Action execution (screenshot, copy, etc.)
│   │   ├── search/                # Fuse.js providers (aliases, snippets, tools)
│   │   ├── storage/               # chrome.storage wrappers
│   │   └── open-flick.ts          # Shortcut → active tab logic
│   └── types/                     # Shared TypeScript types
├── wxt.config.ts                  # Manifest + Vite config
└── package.json

---

Architecture

Keyboard shortcut (⌘⇧K)
        │
        ▼
Background service worker
        │  injects + sends FLICK_TOGGLE
        ▼
Flick content script (Shadow DOM)
        │  mounts React + cmdk overlay
        ▼
User types → Fuse.js search
  ├── Alias provider    (chrome.storage.sync)
  ├── Snippet provider  (chrome.storage.sync)
  └── Dev tool provider (static registry)
        │
        ▼
Select → EXECUTE_ACTION message → Background
        │
        ▼
tabs API / scripting API / clipboard / downloads

The palette communicates with the background service worker via browser.runtime.sendMessage. All actions requiring privileged APIs (tabs, bookmarks, captureVisibleTab, downloads, browsingData) execute in the background. The content script handles UI, search, and element-selection screenshots.

A separate guard content script runs at document_start to intercept keyboard events while the palette is open, preventing host-page shortcuts from firing.

For the full design document, see docs/ARCHITECTURE.md.

---

Development

Commands

Command	Description
npm run dev	Start dev server + load extension in Chrome with HMR
npm run build	Production build → .output/chrome-mv3/
npm run compile	TypeScript typecheck (no emit)
npm run zip	Build + zip for Chrome Web Store upload
npm run dev:firefox	Dev build for Firefox
npm run build:firefox	Production build for Firefox

Path aliases

@/ maps to src/:

import { cn } from '@/lib/cn';
import type { UrlAlias } from '@/types';

Debugging

• Background service worker: chrome://extensions → Flick → Service worker → Inspect
• Content script / overlay: Right-click the page → Inspect → Console (filter by extension context)
• Storage: DevTools → Application → Extension Storage, or run chrome.storage.sync.get(null, console.log) in the service worker console

Firefox

npm run dev:firefox
npm run build:firefox

Some APIs differ between Chrome and Firefox — test before shipping.

For the full guide, see docs/DEVELOPMENT.md.

---

Roadmap

Done

• WXT + React 19 + TypeScript + Tailwind 4 scaffold
• Shadow DOM–isolated palette with cmdk
• URL aliases with Fuse.js fuzzy search
• Text snippets with clipboard paste
• 14 built-in developer tools (screenshot, color picker, dark mode, grid, rulers, tab management, copy, bookmark, clear cache)
• Element-selection screenshot mode
• Settings page with sidebar nav, modal forms, sticky positioning
• URL templates with {variable} placeholder (yt tony stark → YouTube search)
• Toast notifications for all actions
• Page interaction guard (keyboard event blocking)
• Restricted-page detection

Planned

• Tab search & switching provider
• Bookmark search provider
• History search provider
• Alias import/export (JSON)
• Recent commands
• Light/dark theme toggle for the palette
• Omnibox integration (flick in address bar)
• Firefox build verification

See docs/ROADMAP.md for the full phased plan.

---

Contributing

Contributions are welcome. To get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Run npm run dev to start developing with HMR
4. Make your changes — ensure npm run compile passes
5. Open a pull request with a clear description

See CONTRIBUTING.md for the full guide, including how to add new developer tools and search providers.

---

Documentation

Document	Description
TECH_STACK.md	Framework comparison & decisions
ARCHITECTURE.md	System design, data flow, messaging
FEATURES.md	Complete feature reference
ALIASES.md	Alias format & template spec
ROADMAP.md	Phased build plan
DEVELOPMENT.md	Dev workflow, debugging, publishing

---

License

MIT