Listkeeper

Listkeeper turns a Markdown list of GitHub projects into a sortable table in an Obsidian vault.

Give Listkeeper an awesome list, a best-of list, or another Markdown file that links to GitHub repositories. It reads links from Markdown bullets and tables, fetches repository data from GitHub, and creates two notes:

• A view note contains the rendered table.
• An entries note contains one Markdown bullet for each project and stores its data in inline fields.

Listkeeper can refresh the GitHub data on a schedule. It can also read the source list again, add newly listed repositories, and mark repositories that the source removed. Each table row receives an ok, caution, check, or unknown verdict based on documented rules. The verdict is a review aid, not a security guarantee or installation recommendation.

Why use two notes

• Large lists remain manageable. A list with 1,000 projects still uses two notes instead of creating 1,000 files in the vault.
• The source can be any supported Markdown list. Listkeeper accepts repository links in bullets and tables. It can read a repository README or another Markdown file in the repository.
• Repository data stays with each entry. The entries note records activity, issues, pull requests, releases, license information, security information, and derived values when the GitHub API provides them.
• Star history is collected locally. Listkeeper saves dated star counts and calculates the change from an earlier sample once it has a sample between 20 and 60 days old.
• Manual notes are preserved. A refresh replaces recognized entry lines but preserves your headings, surrounding prose, edited descriptions, custom sections, and indented sub-bullets.
• The plugin has no build step or third-party runtime package. The distributed plugin consists of main.js, manifest.json, and styles.css. It uses the Obsidian API and works on desktop and mobile.

Using the table

The filter accepts words, quoted phrases, and field comparisons. For example:

verdict:check
stars>1000 lang:rust pushed>2026-06-01
-lic:noassertion
"local model"

All active terms must match a row. A leading - excludes matches.

Up to 14 columns are selected by default. A column appears only when at least one entry contains that field. Use Columns, or right-click the header row, to change the selection. Hidden columns can still be used in filters.

When you add a list, you can set the source repository, note name, vault folder, minimum star count, maximum age of the last push, advisory collection, peer lists, Markdown file, and an optional entry limit.

On a narrow screen, the table scrolls horizontally while the Verdict and Name columns remain visible. The screenshots use the Minimal theme.

Installation

Listkeeper is not yet listed in the Obsidian community plugin directory. Install it with BRAT or from the GitHub release:

With BRAT: install BRAT, run Add a beta plugin for testing, and enter amoslives/listkeeper. BRAT downloads the latest Listkeeper release and handles later updates.

Manually: download main.js, manifest.json, and styles.css from the latest GitHub release. Copy them into <vault>/.obsidian/plugins/listkeeper/, restart Obsidian, and enable Listkeeper under Settings > Community plugins.

Installation through the Obsidian community plugin directory will be available only if the plugin is submitted and accepted there.

Quick start

1. Open Settings > Listkeeper and enter a fine-grained GitHub token. For public repositories, Listkeeper only needs read access to public repository metadata; it does not need write access.
2. Run Add a list from GitHub from the command palette.
3. Enter owner/repository, a GitHub repository URL, a URL with a heading anchor, or a /blob/ link to a Markdown file.
4. Open the generated view note. Click a header to sort, Shift-click another header to add a second sort key, type in the filter box, or select a preset.
5. If required, open Settings > Listkeeper and choose a daily or weekly schedule. Reload Obsidian after changing the schedule.

The token is optional, but the unauthenticated mode has important limits. It uses one REST request per repository and processes only the first 55 entries by default. It does not rotate through the remaining entries on later runs. A token is therefore recommended for lists longer than the configured unauthenticated request limit and is required for advisory data and the full set of activity fields.

The token is stored in the plugin's data.json file inside the vault. Do not publish or share that file.

With a token, a list of about 180 repositories usually refreshes in under two minutes. Advisory collection makes one additional request per repository and adds about 90 seconds for a list of that size.

Commands

Command	What it does
Add a list from GitHub	It reads the source Markdown, fetches repository data, creates the view and entries notes, saves the first star-count sample, and opens the view note.
Refresh every list	It updates GitHub-derived fields and star history for every managed list. It does not read the source list again.
Sync every list with its source	It reads each source list again, adds newly listed GitHub repositories, marks missing repositories as delisted, and then refreshes repository data. It does not move existing entries between sections or replace their descriptions from the source.
Rescan peer lists	It recalculates how many configured peer lists contain each repository and then refreshes repository data.
Refresh one list	It lets you choose one managed list, then syncs it, rescans its peer lists, and refreshes its repository data.
Convert a folder of notes into a list	It converts supported frontmatter fields from a folder of one-note-per-project files into the two-note format. It can move the original folder to the system trash after the new notes are written.

The ribbon button syncs, rescans, and refreshes every managed list.

Presets

Some presets appear only when the required field exists in the entries note.

Preset	What it shows
All	It shows every entry and sorts them by stars in descending order.
Best bets, ok with high criticality	It shows entries with an ok verdict, a partial OpenSSF criticality score of at least 0.7, and no high or critical advisory.
Check before installing	It shows entries with a check verdict.
Caution	It shows entries with a caution verdict.
Rising, under a year old	It shows repositories created within the last 365 days and sorts them by average stars per day.
Momentum, stars gained in 30d	It shows entries with a calculated star-count change and sorts them by that change. The calculation uses the most recent stored sample between 20 and 60 days old.
Abandoned, no commits in 90d	It shows repositories with no commits on the default branch during the last 90 days.
Backlog, over half of issues open	It shows repositories with at least five open issues and an open-issue ratio above 0.5.
Advisories, published CVEs	It shows repositories with at least one published GitHub security advisory.
Low engagement for its stars	It shows repositories with at least 1,000 stars whose closed-issue and merged-pull-request rate is in the bottom tenth of comparable entries in the current list.
Dormant, no push in a year	It shows repositories whose last push was more than 365 days ago.
Above the star floor and age limit	It shows entries that meet the minimum-star and maximum-last-push-age limits configured for the list.
Delisted by the source	It shows entries that a later source-list sync marked as removed.

Data storage

Lists/
  Best Of Agent Harnesses.md
  entries/
    Best Of Agent Harnesses.md

The first file is the view note. The file under entries/ is the entries note. Each bullet in the entries note stores values in Obsidian inline-field syntax such as [stars:: 120]. Dataview can read these fields.

List configuration, including the GitHub token and schedule, is stored in the plugin's data.json. Star history and run logs are stored in the plugin's data/ folder.

See the complete reference for accepted input formats, settings, fields, formulas, verdict rules, filter syntax, scheduling, and file operations.

Development

The source is main.js; there is no build step. Run the smoke test from the repository root:

node test/smoke.js

The test loads the plugin against a stubbed Obsidian API and fixed GitHub responses. After changing the plugin, copy the three distribution files into a test vault, reload the plugin, and check the Obsidian developer console.

License

Listkeeper is distributed under the MIT License.