Markcat Docs Open app →

Getting Started

What is Markcat?

Markcat is an AI-powered bookmark manager that automatically classifies your bookmarks into a hierarchical category tree. Save a link, and Markcat fetches the page, reads the content, and sorts it into the right category — no manual tagging needed.

How It Works

  1. Save a bookmark (via extension, web app, or API).
  2. Fetch — Markcat downloads the page content: plain HTTP first, then a real browser for JS-heavy sites, then browser stealth mode for bot-protected sites.
  3. Classify — an LLM summarizes the content, then assigns a category path (e.g. Tech / Programming / Python).
  4. Browse — your bookmarks appear in a navigable category tree.

Installation

Option 1: Chrome Extension + Local Service (User A)

This runs entirely on your machine. No account needed. The source code will be available at public launch.

Requirements: Python 3.11+, Node.js 24+ with npm, Chrome/Chromium.

# From the project root
pip install -r service/requirements.in

# Start the service
python -m service.main
# → http://127.0.0.1:8080

Then install the Chrome extension:

  1. From the project root: npm install, then npm run build --workspace=markcat-extension
  2. Open chrome://extensions and enable “Developer mode”
  3. Click “Load unpacked” → select the markcat-extension/dist/ folder

Option 2: Markcat Web App (User D)

Visit markcat.app, create an account, and start saving bookmarks. No local setup or API keys needed — classification runs on the hosted service.

Option 3: Self-Hosted Cloud (User B/C)

See self-hosting.md for PostgreSQL setup and deployment.

First Run

Web app (hosted): register at markcat.app and save your first link — it is fetched and classified automatically, nothing to configure.

Chrome extension: open a new tab after installing — until the extension is connected, the new tab page is a short setup wizard:

  1. Choose Local or Cloud mode.
  2. Enter and test the service URL.
  3. (Cloud) Sign in or create an account. With the hosted service, Sign in via markcat.app opens markcat.app, where your password manager can fill the login; click Connect extension there and the wizard continues by itself. If markcat.app doesn’t recognise your extension build, use the sign-in form below the button.

Local / self-hosted: classification needs an LLM provider. Open Settings → LLM Provider (shown by default on a local service; otherwise tick Advanced settings in the settings sidebar), pick a provider, set its API key if it needs one (Set, paste, Save), and click Apply. The background worker starts with the service, and only when a provider is usable then (Ollama running, or an API key set) — if it was not, restart the service after Apply. There is no provider test button; provider errors appear in the worker log on the Processing page. The providers:

See llm-providers.md for details and costs.

Basic Usage

  1. Save a bookmark: Right-click any page → “Save to Markcat”, or click the extension icon.
  2. View bookmarks: Open the extension’s new tab page or the web app.
  3. Browse categories: The left sidebar shows your category tree. Click to filter.
  4. Search: Use the search bar to find bookmarks by title, URL, or content.
  5. Recategorize: right-click a bookmark and choose Move to category… (with several selected, use Move… in the selection bar), or drag it onto a category in the sidebar. Clicking a bookmark opens its preview.

Next Steps