| name | research-github |
| description | GitHub Awesome-List Registry โ discover, browse, and create deep-research notebooks from GitHub repos. 6 commands for Alex research phase. |
/research-github Command (GitHub Knowledge Discovery)
Overview
*research-github manages the GitHub Awesome-List Registry as TAD's open-source discovery layer.
Use to find relevant repos before starting a project, then create deep-research NotebookLM notebooks.
Key principle: Awesome-lists are community-curated "book lists" โ leverage existing curation, don't reinvent.
This skill is Alex-domain only โ research happens in design/discuss phase, not implementation.
Preflight Check (runs before every sub-command)
preflight:
notebooklm_bin: "~/.tad-notebooklm-venv/bin/notebooklm"
registry_path: ".tad/github-registry/REGISTRY.yaml"
checks:
- "gh CLI authenticated: gh auth status 2>&1 | grep -q 'Logged in'"
- "notebooklm CLI available: test -x ~/.tad-notebooklm-venv/bin/notebooklm"
- "notebooklm version โฅ0.3.4: ver=$(~/.tad-notebooklm-venv/bin/notebooklm --version | awk '{print $NF}'); printf '%s\\n0.3.4\\n' \"$ver\" | sort -V | head -1 | grep -qx '0.3.4'"
- "REGISTRY exists: test -f .tad/github-registry/REGISTRY.yaml"
on_fail_gh: "Output: 'โ ๏ธ gh CLI not authenticated. Run: gh auth login'"
on_fail_notebooklm: "Output: 'โ ๏ธ NotebookLM not ready. Run: bash .tad/cross-model/setup-notebooklm.sh'"
on_fail_version: "Output: 'โ ๏ธ notebooklm-py < 0.3.4 has broken AI endpoints โ re-run: bash .tad/cross-model/setup-notebooklm.sh'"
on_fail_registry: "Output: 'โ ๏ธ REGISTRY.yaml not found. Expected at .tad/github-registry/REGISTRY.yaml'"
on_pass: "Proceed to sub-command"
note: "gh auth check is NOT required for: list, scan-log. Required for all other commands (explore, notebook, search, refresh, scan, add)."
Note: All notebooklm CLI invocations use the absolute path ~/.tad-notebooklm-venv/bin/notebooklm
to avoid PATH/venv activation dependency. Never use bare notebooklm.
Commands
*research-github list
Show all domains with awesome-list count and notebook status.
Step 1: Read .tad/github-registry/REGISTRY.yaml
โ Parse all domains
Step 2: Read research-notebooks REGISTRY for staleness check:
โ Load .tad/research-notebooks/REGISTRY.yaml
โ Build lookup set: {notebook.id โ notebook.status}
Step 3: Format table output:
| Domain | Slug | # Lists | Notebook | Last Researched |
|--------|------|---------|----------|-----------------|
For each domain:
- Domain = domain.name
- Slug = domain.slug
- # Lists = len(domain.awesome_lists)
- Notebook: if domain.notebook_id is null โ "โ"
if domain.notebook_id found in research-notebooks lookup โ domain.notebook_id
if domain.notebook_id NOT found in research-notebooks lookup โ "{notebook_id} (stale ref)"
- Last Researched = domain.last_researched (or "never" if null)
Step 4: Display summary line:
"{N} domains, {M} total awesome-lists registered."
"{K} domains have associated NotebookLM notebooks."
*research-github search <topic>
Search GitHub for new awesome-lists related to a topic.
Step 1: Run GitHub search:
โ gh search repos "awesome {topic}" --limit 10 --sort stars --json fullName,stargazersCount,description,url
โ Parse JSON output
Step 2: Format results:
| Repo | Stars | Description |
|------|-------|-------------|
For each result, display fullName, stargazersCount, description (truncated to 80 chars)
Step 3: AskUserQuestion โ "Found {N} repos. What would you like to do?"
Options:
- "Add one to the registry" โ go to *research-github add
- "Add multiple" โ loop through add
- "Just exploring, no action needed"
- "Research one of these now" โ go to *research-github notebook
Note: This searches for new lists to add โ not for researching existing ones.
*research-github add <repo>
Add a new awesome-list to the registry under a domain.
Step 1: Validate repo exists:
โ gh api repos/{repo} --jq '.full_name,.stargazers_count,.description' 2>/dev/null
โ If error: "โ ๏ธ Repo '{repo}' not found on GitHub. Check repo name (format: owner/repo)."
Note: gh api (REST) uses snake_case (.full_name, .stargazers_count).
gh search repos --json uses camelCase (fullName, stargazersCount) โ these are different APIs.
Step 2: Fetch repo metadata:
stars = gh api repos/{repo} --jq '.stargazers_count'
url = "https://github.com/{repo}"
description = gh api repos/{repo} --jq '.description'
Step 3: AskUserQuestion โ "Which domain should this go under?"
Options: [list of domain names from REGISTRY.yaml] + "Create new domain"
Step 4: If "Create new domain":
AskUserQuestion: "Enter domain name and slug"
โ Add new domain entry to REGISTRY.yaml with empty awesome_lists
Step 5: Add entry to REGISTRY.yaml under selected domain:
Entry format:
- repo: "{owner}/{repo}"
stars: {stars}
url: "{url}"
last_checked: {today YYYY-MM-DD}
description: "{description}"
Step 6: Confirm: "โ
Added {repo} ({stars} โญ) to '{domain}' domain."
*research-github explore <domain>
Browse a domain's awesome-list README, extract top repos, present selection.
Step 1: Look up domain in REGISTRY.yaml by name or slug
โ If not found: "Domain '{domain}' not in registry. Available: {list}. Try *research-github search <topic> to find new lists."
Step 2: For each awesome-list in domain.awesome_lists:
Read README via raw content API:
โ gh api -H "Accept: application/vnd.github.raw+json" repos/{owner}/{repo}/contents/README.md
โ This returns raw markdown text directly (no JSON envelope, no base64 decode needed)
โ On error: "โ ๏ธ Could not fetch README for {repo}: {error}"
Step 3: Extract repo links from README:
โ grep -oE 'https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+' | sort -u
โ De-duplicate by {owner}/{repo}
โ Filter: exclude links to issues, pulls, wiki, user profiles
(keep only repo root URLs: no /issues, /pull, /wiki, /blob, /tree suffixes)
Step 4: Fallback โ if <5 links extracted from a list:
โ Show README section headers (lines starting with ##)
โ "Could only auto-extract {N} repos from {repo}. Here are the README sections โ pick repos manually."
Step 5: Collect extracted repos across all awesome-lists in the domain
โ Deduplicate across lists
Step 6: Fetch metadata for extracted repos, then present selection:
โ For each extracted repo (best-effort, skip on error):
gh api repos/{owner}/{repo} --jq '.stargazers_count,.description'
โ Attach {stars} and {description} to each repo object
AskUserQuestion (multiSelect) โ "Found {N} repos in '{domain}'. Select which to research:"
Options: each repo as "[owner/repo] ({stars}โญ) โ {description}"
Note: stars must be fetched here โ needed for Step 6 of notebook command's "Keep top 3" reduction.
Step 7: Store selection in conversation for *research-github notebook to use
โ "Selected {N} repos. Ready to create a research notebook with: *research-github notebook '{domain}'"
*research-github notebook <domain>
Create a NotebookLM notebook from selected repos (the full research pipeline).
PREREQUISITE: Run *research-github explore <domain> first to select repos.
If no repos selected yet, run explore internally (Step 2).
Step 1: Confirm domain and selected repos from explore step
AskUserQuestion: "Creating notebook for '{domain}' with these repos: {list}. Proceed?"
Options: "Yes, proceed" | "Change selection (re-run explore)" | "Cancel"
Step 2: If no prior explore selection, run explore algorithm (see explore command above)
โ Present selection โ user picks repos
Step 3: For each selected repo, query default branch:
โ gh api repos/{owner}/{repo} --jq '.default_branch'
โ Store as {branch} per repo (NOT hardcoded 'main' โ repos may use 'master' or other)
Step 4: For each selected repo, list ALL files (recursive):
โ gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1 --jq '{truncated: .truncated, paths: [.tree[] | select(.type == "blob") | .path]}'
โ Returns flat list of ALL file paths in repo (recursive, blob-type only)
Note: Do NOT use gh api .../contents/ โ it returns only ROOT-level entries (not subdirs).
The recursive tree API is the correct primitive for path enumeration.
Truncation check: if .truncated == true:
โ Log: "โ ๏ธ {repo} tree was truncated (>100K files or >7MB). Using root-level files only."
โ Fallback: gh api repos/{owner}/{repo}/contents/ --jq '[.[] | select(.type == "file") | .path]'
โ Tier selection will be limited to root-level files only for this repo.
Step 5: Smart file selection per repo (tier-based, max 10/repo):
tier_1_always: ["README.md", "docs/README.md"]
tier_2_docs: paths matching docs/*.md, *.md at root (exclude CHANGELOG.md, CONTRIBUTING.md, LICENSE.md) โ up to 5 files
tier_3_source: paths matching src/index.*, src/main.*, lib/index.*, app/main.* โ up to 3 files
tier_4_config: paths matching package.json, pyproject.toml, Cargo.toml, go.mod โ up to 2 files
Selection logic:
1. Always include tier_1 paths that exist in the recursive file list
2. Fill remaining slots from tier_2 (alphabetical, prefer shorter paths)
3. If <8 selected, add tier_3 files
4. If <9 selected, add tier_4 files
5. Cap at 10 per repo
Step 6: Source limit check (NotebookLM per-notebook limit = 50):
total_sources = sum of selected files across all repos
If total_sources > 50:
AskUserQuestion: "Total {total_sources} sources exceeds NotebookLM limit (50). How to reduce?"
Options:
- "Remove a repo from selection" โ let user deselect
- "Reduce files per repo to 5 max" โ apply 5-cap to tier selection
- "Keep top 3 repos only" โ discard lowest-star repos
Step 7: Create NotebookLM notebook:
โ ~/.tad-notebooklm-venv/bin/notebooklm create "{domain} Research"
โ Parse output to capture notebook_id
โ If error: "โ ๏ธ Failed to create notebook: {error}. Check NotebookLM auth."
Step 8: Add sources โ for each selected file in each repo:
Construct URL: https://github.com/{owner}/{repo}/blob/{branch}/{path}
Determine type flag:
Code files (.py/.js/.ts/.go/.rs/.java/.rb/.sh/.c/.cpp/.h) โ --type text
Config files (.json/.yaml/.toml) โ --type text
Doc files (.md/.txt) โ no flag (auto-detected by NotebookLM)
Execute: ~/.tad-notebooklm-venv/bin/notebooklm source add "{url}" [--type text] -n {notebook_id}
Track: success_count, fail_count, failed_urls
On individual failure: log warning, continue with next source
Failure threshold: if fail_count > total_sources ร 0.5:
AskUserQuestion "High failure rate ({fail_count}/{total_sources} failed). How to proceed?"
Options: "Keep notebook with partial sources" | "Retry failed URLs manually later" | "Delete notebook and abort"
If Delete: ~/.tad-notebooklm-venv/bin/notebooklm delete {notebook_id} -- do NOT update registries
Step 9: Initial synthesis query:
AskUserQuestion: "Choose synthesis question for notebook '{domain} Research':"
Options:
- "่ฟไบ้กน็ฎ็ๅ
ฑๅๆถๆๆจกๅผๆฏไปไน๏ผๆ้ๅๅไบบๅผๅ่
็ๆนๆก๏ผ" (default)
- "่ฟไบๅบ/ๆกๆถ่งฃๅณไบไปไนๆ ธๅฟ้ฎ้ข๏ผๆไปไน่ฎพ่ฎกๅ่๏ผ"
- "Custom question" โ AskUserQuestion for free text
โ ~/.tad-notebooklm-venv/bin/notebooklm ask "{question}" -n {notebook_id}
โ Present synthesis result to user
Step 10: Update BOTH registries (cross-registry sync):
Write order: (b) first, then (a) โ if (b) fails, abort before touching (a) to avoid stale ref
If (a) fails after (b) succeeds: display "โ ๏ธ Notebook registered in research-notebooks but github-registry not updated. Manually set notebook_id: {notebook_id} for domain '{domain}' in REGISTRY.yaml"
b. Update .tad/research-notebooks/REGISTRY.yaml FIRST:
Add new notebook entry:
id: "{domain-slug}-github-research"
topic: "{domain} Research (GitHub Awesome-Lists)"
created: "{today YYYY-MM-DD}"
status: active
last_queried: "{today YYYY-MM-DD}"
source_count: {success_count}
notes: "Created by *research-github from awesome-lists. Repos: {repo list}"
created_by: "research-github" # extension field โ identifies github-registry-created notebooks
sources:
- (list of successfully added URLs with type and added date)
Note: `created_by` is an extension field not in the original template schema.
It allows *research-github list to distinguish stale refs from archive events.
The *research-notebook archive command does NOT auto-null github-registry's notebook_id โ
this is a manual action (see Cross-Registry Sync Contract rule #2 below).
a. Update .tad/github-registry/REGISTRY.yaml SECOND:
Set domain.notebook_id = {notebook_id}
Set domain.last_researched = {today YYYY-MM-DD}
Step 11: Confirm summary:
"โ
Research notebook created for '{domain}':
- notebook_id: {notebook_id}
- {success_count} sources added ({fail_count} failed)
- Initial synthesis: [displayed above]
- Query more: *research-notebook ask '{question}' --notebook {notebook_id}"
*research-github refresh [--domain <slug>]
Check awesome-lists for updates (check last commit dates).
Step 1: Determine scope:
โ If --domain <slug>: check only that domain's awesome_lists
โ If no flag: check all domains (may be slow; warn user: "Checking {N} awesome-lists โ this may take 1-2 minutes")
Step 2: For each awesome-list in scope:
โ gh api "repos/{owner}/{repo}/commits?per_page=1" --jq '.[0].commit.committer.date'
Note: Use `committer.date` (reliable merge date โ matches GitHub "last updated" display).
Never use `author.date` โ can be stale when old PRs are merged recently.
Note: Use ?per_page=1 query param (NOT --limit flag โ --limit is for gh search, not gh api)
โ Parse date as last_commit_date
โ Compare to last_checked in REGISTRY.yaml
Step 3: Detect stale lists:
โ If last_commit_date > last_checked: mark as "UPDATED since last check"
โ If repo returns 404: mark as "ARCHIVED or DELETED"
โ Stars change: note new stars count
Step 4: Display results:
| Repo | Status | Last Commit | Stars (was โ now) |
For each checked list, show UPDATED / CURRENT / ARCHIVED status
Step 5: AskUserQuestion โ "Found {N} updated lists. Update REGISTRY.yaml last_checked dates?"
Options: "Yes, update all" | "Select which to update" | "No, just showing"
Step 6: Update REGISTRY.yaml for confirmed lists:
โ Set last_checked = today for updated entries
โ If repo ARCHIVED: add note field: "archived: true" to entry (don't delete โ preserve history)
*research-github scan [--domain <slug>]
Manual trigger for weekly scan logic: check freshness + discover new lists. Writes results to scan-log.yaml (single-writer principle โ does NOT update REGISTRY.yaml last_checked).
API call budget: ~75 calls total (50 REST commits + 24 gh search). gh search has 30/min limit โ builds in 2s delay between search calls.
Step 1: Determine scope:
โ If --domain <slug>: check only that domain
โ If no flag: check all domains
Step 1b: Today-guard (avoid duplicate scan):
โ Read scan-log.yaml: if last_scan == today YYYY-MM-DD:
โ If running in non-interactive/scheduled context (the invoking prompt declares
"non-interactive mode" โ e.g., the weekly cron routine):
Output one line: "Already scanned today ({last_scan}) โ non-interactive mode, exiting without changes."
โ EXIT. NEVER call AskUserQuestion in non-interactive context.
โ Else (interactive/manual invocation โ unchanged behavior):
AskUserQuestion: "Already scanned today ({last_scan}). Re-scan?"
Options: "Yes, re-scan" / "Show last results โ *research-github scan-log"
โ "Show last results": redirect to *research-github scan-log + EXIT
Step 2: Freshness check (Behavior A โ already-registered lists)
For each awesome_list in scope:
โ gh api "repos/{owner}/{repo}/commits?per_page=1" --jq '.[0].commit.committer.date'
Note: Use `committer.date` (reliable merge date), not `author.date`
Note: Use ?per_page=1 query param (NOT --limit โ --limit is for gh search, not gh api)
โ If last_commit_date > awesome_list.last_checked โ mark as "updated"
โ If repo returns 404 โ mark as "archived"
โ Collect {repo, domain_slug, last_commit, previous_checked} per updated entry
Step 3: Discovery check (Behavior B โ new awesome-lists, with rate-limit guard)
For each domain in scope:
โ gh search repos "awesome {domain.slug}" --sort stars --limit 5 \
--json fullName,stargazersCount,description
Note: --json uses camelCase (fullName, stargazersCount) โ gh search CLI convention
โ Rate-limit handling: if gh search returns HTTP 403 / rate-limit error:
โ Wait 60s and retry once
โ If still fails: log {domain, error: "rate_limited"} and continue to next domain
โ Sleep 2s between domain searches to stay under 30/min limit
โ For each result NOT already in domain.awesome_lists (match by fullName):
โ If stargazersCount > 500: mark as "new_candidate"
โ Collect {repo, domain, stars, description} (status assigned in Step 4 merge)
(Repos with โค500 stars are silently filtered โ avoids noise)
Step 4: Merge-write scan-log.yaml (NEVER full overwrite โ preserve user decisions):
โ Read existing scan-log.yaml (if exists)
โ Build merged new_candidates list:
For each newly-found candidate {repo, domain}:
If already exists in scan_results.new_candidates with status == "accepted":
SKIP (already in REGISTRY โ drop from scan-log)
If already exists with status == "rejected":
PRESERVE rejected status (do NOT reset to pending)
If new entry: status = pending
โ GC: remove entries with status: accepted (in REGISTRY already)
remove entries with status: rejected AND first_seen < previous last_scan date
(first_seen field: written as {today} when a new candidate is first added to scan_results.new_candidates)
โ Ensure new_candidates entries include first_seen field: {today YYYY-MM-DD} for new entries
โ Write merged result to .tad/github-registry/scan-log.yaml:
version: 1.0.0
last_scan: {today YYYY-MM-DD}
scan_results:
updates: [{repo, domain, last_commit, previous_checked}]
new_candidates: [{repo, domain, stars, description, status}]
Step 5: Display summary:
"โ
Scan complete: {N} lists updated, {M} new candidates found ({K} previously rejected preserved)."
"Results saved to .tad/github-registry/scan-log.yaml"
"Alex will report next time on session start (STEP 3.9)."
Single-writer for scan-log.yaml data: scan command + routine write scan data here.
Status mutations (accept/reject) are also written to scan-log.yaml but via separate yq commands
in scan-log interactive flow and STEP 3.9 โ see mutation_protocol in those commands.
REGISTRY.yaml is NOT modified. To update last_checked: use *research-github refresh.
*research-github scan-log
Display the most recent scan results from scan-log.yaml.
Step 1: Read .tad/github-registry/scan-log.yaml
โ If file not found or last_scan == null: "๐ก No scan results yet. Run *research-github scan to start."
Step 2: Display scan summary header:
"๐ก Last scan: {last_scan} ({N_days} ago)"
Step 3: Display updates section:
If scan_results.updates is empty: "โ
No updates โ all lists are current."
Else:
"๐ Updated lists ({N}):"
| Repo | Domain | Last Commit | Was Checked |
|------|--------|-------------|-------------|
For each updated entry.
โ Suggest: "Run *research-github refresh to update REGISTRY.yaml last_checked dates."
Step 4: Display new candidates section:
If scan_results.new_candidates is empty: "๐ No new candidates found."
Else:
"๐ New candidates ({M}) โ status: pending:"
| Repo | Domain | Stars | Description |
|------|--------|-------|-------------|
For each candidate with status == "pending".
If any pending candidates:
AskUserQuestion: "ๆ {M} ไธชๆฐๅ็ฐ็ awesome-listใ่ฆ็ฐๅจๅค็ๅ๏ผ"
Options:
- "้ไธๆฅ็ๅนถๅณๅฎ (accept/reject)"
- "ๅ
จ้จๆฅๅ (add to REGISTRY)"
- "ๅ
จ้จ่ทณ่ฟ (mark rejected)"
- "็จๅๅค็ (leave as pending)"
โ "้ไธๆฅ็":
For each candidate: display + AskUserQuestion "ๅ ๅ
ฅ Registry๏ผ"
โ "ๅ ๅ
ฅ":
1. call *research-github add {candidate.repo} (writes to REGISTRY.yaml)
2. If add SUCCEEDS: write status to scan-log.yaml (scan-log status update ONLY after add succeeds):
yq -i '(.scan_results.new_candidates[] | select(.repo == "{candidate.repo}")).status = "accepted"' \
.tad/github-registry/scan-log.yaml
3. If add FAILS: do NOT update scan-log.yaml; display: "โ ๏ธ Add failed โ scan-log unchanged. Retry manually."
โ "่ทณ่ฟ":
yq -i '(.scan_results.new_candidates[] | select(.repo == "{candidate.repo}")).status = "rejected"' \
.tad/github-registry/scan-log.yaml
โ "ๅ
จ้จๆฅๅ": loop each pending candidate through the "ๅ ๅ
ฅ" mutation_protocol above (REGISTRY write first, scan-log second)
โ "ๅ
จ้จ่ทณ่ฟ":
yq -i '.scan_results.new_candidates[] |= (select(.status == "pending") | .status = "rejected")' \
.tad/github-registry/scan-log.yaml
โ "็จๅๅค็": no action (Alex will prompt again next session)
Step 5: Display archived entries (if any):
If any entries marked "archived" in updates: warn user, suggest removing from REGISTRY.
Setup: Scheduled Routine
Weekly automatic scanning runs as a Claude Code scheduled routine (registered by the
Conductor / main session via CronCreate, or manually via /schedule).
The routine prompt DELEGATES to this SKILL's scan protocol โ it deliberately contains
NO inline scan logic. A duplicated copy of the scan steps drifts from the protocol
(the previous inline version full-overwrote scan-log.yaml, violating Step 4 merge-write
and destroying user accept/reject decisions). Single source of truth: the scan protocol above.
Routine prompt (canonical standalone copy: .tad/evidence/spikes/cron-github-scan-2026-07/cron-prompt.md):
Non-interactive mode. You are a scheduled weekly GitHub registry scan session.
1. Read .claude/skills/research-github/SKILL.md.
2. Execute the `*research-github scan` protocol in full (Step 1 through Step 5,
including the Step 4 merge-write), in non-interactive mode:
- Today-guard (Step 1b): if last_scan == today, print the one-line log and exit.
Never prompt โ this session has no human attached.
- Step 4 MERGE-write semantics are mandatory: NEVER full-overwrite scan-log.yaml;
preserve existing accepted/rejected candidate statuses and first_seen fields.
3. Write ONLY .tad/github-registry/scan-log.yaml. Do NOT modify REGISTRY.yaml or any
other file. Single-writer principle: scan-log.yaml is the only output of this routine.
4. If any prerequisite or step fails (gh CLI not authenticated, unrecoverable API errors
beyond the protocol's built-in wait-60s-retry-once rule): print one error line and
exit quietly. Do not retry, do not loop.
5. Do nothing else.
Schedule: Weekly (Sunday 23:00)
Setup steps (Conductor / main session โ sub-agents cannot use CronCreate):
- Register via CronCreate (or
/schedule): weekly, Sunday 23:00, prompt = the text
above (take verbatim from cron-prompt.md)
- Optional first-run verification: a one-shot cron (+5 min) with the same prompt proves
cron-fires-at-all before waiting a week
Verification:
- After first run:
*research-github scan-log shows last_scan date
- Alex will automatically report in STEP 3.9 on next session start
Cross-Registry Sync Contract
Two registries coexist with different concerns:
.tad/github-registry/REGISTRY.yaml โ discovery layer (domains โ awesome-lists).tad/research-notebooks/REGISTRY.yaml โ understanding layer (notebooks โ sources)
Sync rules:
*research-github notebook writes to both: github-registry gets notebook_id + last_researched; research-notebooks gets full entry with created_by: "research-github"*research-notebook archive of a github-created notebook โ caller should null notebook_id in github-registry (manual action; display reminder)*research-github list checks notebook_id validity: if referenced notebook_id not found in research-notebooks REGISTRY โ show "(stale ref)" warning next to the domain- Staleness is acceptable โ display warning, don't auto-fix (no silent mutations)
Anti-Patterns
- โ Don't try to clone repos locally โ GitHub sub-page URLs give NotebookLM full code-level access
- โ Don't auto-add all files from a repo โ use smart tier selection (README + docs + key source files, max 10/repo)
- โ Don't hardcode
main as branch โ always query .default_branch via gh api
- โ Don't use bare
notebooklm command โ always use absolute path ~/.tad-notebooklm-venv/bin/notebooklm
- โ Don't exceed 50 total sources per NotebookLM notebook โ check before adding
Usage Examples
*research-github list
*research-github search "vector database"
*research-github explore "mcp-servers"
*research-github notebook "mcp-servers"
*research-github add "modelcontextprotocol/servers"
*research-github refresh --domain mcp-servers
*research-github refresh
Quick Reference
| Command | Purpose | gh auth needed? | notebooklm needed? |
|---|
list | Show all domains | No | No |
search <topic> | Find new lists | Yes | No |
add <repo> | Add to registry | Yes | No |
explore <domain> | Read README, pick repos | Yes | No |
notebook <domain> | Create research notebook | Yes | Yes |
refresh | Check for updates | Yes | No |
scan | Manual weekly scan (freshness + discovery) | Yes | No |
scan-log | Display latest scan results | No | No |
[[LLM: When activated via /research-github, always run preflight checks before any operation. For notebook command, follow the 11-step pipeline exactly โ especially Step 3 (query default_branch) and Step 10 (update BOTH registries). Use absolute notebooklm path everywhere.]]
