his Spec

Overview

One SQLite archive for all browser history, with WebUI.

Directory structure

core · server · three frontends — cli · webui · desktop

his/
🧠 core/                          # types · db · features · sync
    ├── package.json
    └── src/
        ├── index.ts
        ├── node.ts               # node entry
        ├── types.ts              # HistoryItem · VisitItem · Transition · epoch ms
        ├── db/                   # migrations/ · db.ts · schema.ts · query/
        ├── features/             # history/ · keywords/ · github/ · youtube/ · settings/ · sources/ · sync/
        ├── util/                 # url · top
        └── testing/              # fixtures
📦 cli/                           # npm package: his
    ├── package.json              # "bin": { "his": "./bin.ts" }
    ├── bin.ts
    └── src/
        ├── context.ts            # context for commands (home path)
        ├── sync.ts               # sync command
        ├── sources.ts            # sources command · list / add / remove targets
        ├── query.ts              # query command
        ├── serve.ts              # serve command · delegates to @his/server
        └── status.ts             # status command
🔌 server/                        # @his/server — transport over core
    ├── package.json
    └── src/
        ├── index.ts              # serve() · HTTP + RPC · state.json
        ├── app.ts                # static · entry token
        ├── rpc.ts                # WS JSON-RPC · framing · handlers
        ├── static.ts             # dist · MIME · cache
        └── sync-runner.ts        # in-process sync · 6h
🌐 webui/                         # React + @preact/signals SPA
    ├── package.json
    ├── vite.config.ts            # dist/ → served by `his serve`
    └── src/
        ├── main.tsx
        ├── App.tsx               # root · view nav
        ├── app/                  # app model · api
        ├── components/           # SearchBar · icons · ui
        ├── lib/                  # transport · date · domain · format · signals
        └── views/                # dashboard · visits · urls · keywords · github · youtube · sources · settings
🖥️ desktop/                       # Electron shell
    ├── package.json
    ├── vite.config.ts
    ├── assets/                   # tray icon
    └── src/
        ├── main.ts               # Electron entry · app events
        ├── app.ts                # HisApp · window · serve lifecycle
        └── tray.ts               # tray menu

Architecture

his serve owns the archive, the WebUI, and the RPC socket. Desktop just spawns it.

Desktop app

macOS menu bar client. Spawns his serve.

Tray menu

Open                           # BrowserWindow → serve URL
Open in Browser                # OS default browser
Sync Now                       # sync.run over RPC
─────────────────────────────
New version available — v0.3.0  # only when a newer release exists · opens the release page
Quit his                       # stop serve · quit

WebUI

React SPA served by his serve.

CLI

Syntax: his [command] [options]

RPC

JSON-RPC 2.0 over WS at /rpc.

# request / response
history.search       { query?, url?, from?, to?, cursor?, limit? }        → { items, nextCursor }
history.searchVisits { query?, url?, from?, to?, cursor?, limit? }        → { items, nextCursor }
history.stats        { month? }                                          → Stats
keywords.stats       { month? }                                          → KeywordStats
keywords.search      { month?, cursor?, limit? }                         → { items, nextCursor }
github.stats         { month? }                                          → GithubStats
github.search        { month?, owner?, repo?, kind?, cursor?, limit? }   → { items, nextCursor }
youtube.stats        { month? }                                          → YoutubeStats
youtube.search       { month?, kind?, cursor?, limit? }                  → { items, nextCursor }
sources.list         { check? }                                          → SourceEntry[]    # discovered ∪ registered · check probes source files
sync.run             { targets?, rescan? }                               → SyncSummary      # targets omitted → settings
sync.status                                                              → SyncSummary | null # latest server run; timestamps and errors included
settings.get                                                             → SettingsInfo     # { hidden_patterns, hidden_url_count, sync_targets }
settings.set         { hidden_patterns?, sync_targets? }                 → SettingsInfo

Data model

URLs and visits in one SQLite file.

Schema

-- history.db · WAL · foreign_keys=ON
CREATE TABLE source_profiles (          -- browser profiles
  id            INTEGER PRIMARY KEY,
  browser       TEXT    NOT NULL,       -- chrome, brave, ...
  profile       TEXT    NOT NULL,       -- profile dir
  kind          TEXT    NOT NULL,       -- engine
  source_path   TEXT    NOT NULL,
  UNIQUE(browser, profile)
);

CREATE TABLE urls (                     -- HistoryItem
  id               INTEGER PRIMARY KEY,
  url              TEXT    NOT NULL UNIQUE,
  title            TEXT,                -- last seen
  first_visit_time INTEGER NOT NULL,    -- epoch ms
  last_visit_time  INTEGER NOT NULL,
  visit_count      INTEGER NOT NULL DEFAULT 0,
  typed_count      INTEGER NOT NULL DEFAULT 0
);

CREATE TABLE visits (                   -- VisitItem
  id                INTEGER PRIMARY KEY,
  url_id            INTEGER NOT NULL REFERENCES urls(id),
  visit_time        INTEGER NOT NULL,   -- epoch ms
  transition        TEXT    NOT NULL,   -- LINK / TYPED / ...
  source_profile_id INTEGER NOT NULL REFERENCES source_profiles(id),
  source_visit_id   INTEGER NOT NULL,   -- native id · takeout: hash
  UNIQUE(source_profile_id, source_visit_id)
);
CREATE INDEX idx_visits_visit_time        ON visits(visit_time DESC);
CREATE INDEX idx_visits_url_id_visit_time ON visits(url_id, visit_time DESC);
CREATE INDEX idx_urls_last_visit_time     ON urls(last_visit_time DESC);      -- timeline sort

CREATE TABLE sync_checkpoints (         -- sync cursors
  source_profile_id    INTEGER PRIMARY KEY REFERENCES source_profiles(id),
  last_source_visit_id INTEGER NOT NULL DEFAULT 0,
  source_id_offset     INTEGER NOT NULL DEFAULT 0,  -- += last_raw_id on clear
  last_fingerprint     TEXT,                -- change gate
  last_run_at          INTEGER
);

CREATE VIRTUAL TABLE urls_fts USING fts5(
  title, url,
  content='urls', content_rowid='id',
  tokenize='trigram'                    -- trigger-maintained
);

CREATE TRIGGER urls_fts_after_insert AFTER INSERT ON urls BEGIN
  INSERT INTO urls_fts(rowid, title, url) VALUES (new.id, new.title, new.url);
END;

CREATE TRIGGER urls_fts_after_delete AFTER DELETE ON urls BEGIN
  INSERT INTO urls_fts(urls_fts, rowid, title, url) VALUES ('delete', old.id, old.title, old.url);
END;

CREATE TRIGGER urls_fts_after_update AFTER UPDATE ON urls BEGIN
  INSERT INTO urls_fts(urls_fts, rowid, title, url) VALUES ('delete', old.id, old.title, old.url);
  INSERT INTO urls_fts(rowid, title, url) VALUES (new.id, new.title, new.url);
END;

WebExtensions mapping

Based on the WebExtensions history API.

Sync

Sync the configured targets.

targets → gate → snapshot → parse → upsert → checkpoint

Targets come from settings.sync_targets; an empty list syncs nothing. his sync --target overrides them once. Edit the set in the WebUI Sources page or with his sources add / remove.

Sources

Transition mapping

Data directory

Default ~/.his, override with --home <dir> or HIS_HOME.

~/.his/
├── state.json    # running instance — {pid, port, url, db, token} (0600)
├── history.db    # the archive
└── snapshots/    # snapshot copies

Runtime state

The running instance keeps ~/.his/state.json.

State file

{
  "pid": 12345,                      // serve process
  "port": 4477,                      // bound port
  "url": "http://localhost:4477/",
  "db": "/Users/me/.his/history.db",  // archive path
  "token": "9f2c…"                   // required by /rpc
}