Save, categorize, and track web resources directly into a Google Spreadsheet.
Knots is a browser extension that saves any webpage to a dedicated Google Spreadsheet with one click. It auto-categorizes pages, prevents duplicates via a local URL cache, and shows a badge indicator on previously saved pages.
- One-Click Save — Click the toolbar icon to save the current page (title, URL, category, timestamp)
- Right-Click Save with Notes — Highlight text, right-click → "Knots: Save Note" to save with annotations
- Smart Categorization — Automatically detects content type (Video, Article, Code, Q&A, Forum) based on the domain
- Duplicate Detection — Instant client-side URL cache prevents saving the same page twice
- Peek Indicator — Green ✓ badge on the toolbar icon when you visit an already-saved page
- Status Tracking — Each saved entry has a status column (Todo / In progress / Done) with dropdown validation and conditional row colouring
- Page Status Actions — When visiting a saved page, the popup shows "Viewing" (marks In progress) and "Done" buttons instead of the save button
- Inline Settings — Sheet name selection (with datalist), smart categorization toggle, and cache management directly in the popup
- Cross-Browser — Works on both Chrome and Firefox (Manifest V3)
Click "Save" → Check cache for duplicates → Categorize URL → Append row to Google Sheets → Update badge
Your data lives in a Google Spreadsheet called "Knots Sheets" with these columns:
| Date | Title | Link | Type | Notes | Status |
|---|---|---|---|---|---|
| 2026-03-14 09:30 | GitHub - torvalds/linux | https://github.com/... | Code | Todo |
- Node.js ≥ 18
- A Google Cloud project with Google Sheets API and Google Drive API enabled
- An OAuth 2.0 Client ID (setup guide)
git clone https://github.com/your-username/knots.git
cd knots
npm install
# Create .env from the example and add your Google Client ID
cp .env.example .env
# Build for Chrome
npm run build:chrome # → dist-chrome/
# Build for Firefox
npm run build:firefox # → dist-firefox/- Open
chrome://extensions - Enable Developer mode (top-right)
- Click Load unpacked → select the
dist-chrome/folder - Pin the Knots icon in your toolbar
- Open
about:debugging#/runtime/this-firefox - Click Load Temporary Add-on… → select any file in
dist-firefox/
- Go to Google Cloud Console → APIs & Services
- Enable Google Sheets API and Google Drive API
- Create OAuth 2.0 credentials:
- Chrome: Application type = "Chrome Extension", enter your extension ID
- Firefox: Application type = "Web Application", add
browser.identity.getRedirectURL()as a redirect URI
- Copy the Client ID into your
.envfile:VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
| Action | How |
|---|---|
| Sign in | Click Knots icon → Sign in with Google |
| Save a page | Click Knots icon → Save Current Page |
| Save with notes | Select text → right-click → Knots: Save Note |
| Mark as viewing | Visit a saved page → click Viewing (sets status to "In progress") |
| Mark as done | Visit a saved page → click Done (sets status to "Done") |
| Sync cache | Click Knots icon → Sync button (refreshes URL cache from spreadsheet) |
| View spreadsheet | Click Knots icon → Open Spreadsheet ↗ |
| Change target sheet | Click Knots icon → ⚙ Settings → set sheet name |
| Toggle categorization | ⚙ Settings → Smart Categorization toggle |
| Clear local cache | ⚙ Settings → Clear Local Cache |
| Sign out | Click Knots icon → Logout |
| Language | TypeScript (strict mode) |
| Build | Vite 8 + vite-plugin-web-extension |
| Styling | Tailwind CSS v4 |
| Browser APIs | webextension-polyfill |
| Testing | Vitest (37 tests) |
| APIs | Google Sheets v4 + Google Drive v3 (direct REST, no client libraries) |
src/
├── background/ # Service worker — auth, API, cache, save logic
├── content/ # Toast notification content script
├── popup/ # Toolbar popup UI
├── options/ # Settings page
├── shared/ # Shared TypeScript types
└── manifest.json # MV3 manifest
tests/ # Vitest test suite
.documentation/ # Architecture & onboarding docs
# Watch mode
npm run dev:chrome
npm run dev:firefox
# Run tests
npm test
npm run test:watch
# Type check
npx tsc --noEmitDetailed internal documentation is available in .documentation/:
- Architecture — system overview and module map
- Data Flow — end-to-end traces of every action
- Authentication — OAuth flow and token lifecycle
- Caching — URL cache design and consistency model
- API Layer — Google Sheets/Drive wrapper reference
- Testing — test strategy and mock architecture
- Setup — detailed developer onboarding
ISC