| name | workflows |
| description | When and how to use the repoindex plugin surface (MCP tools, agents, slash commands) for collection queries, release prep, activity summaries, and tag discipline. Use when users ask repoindex questions, mention their repo catalog, or want to know which repoindex tool fits their task. |
repoindex: which tool for which task
The plugin exposes three layers. Pick the smallest one that answers the question.
| Layer | Use when |
|---|
MCP tool calls (run_sql, get_manifest) | Single question, clear query, one answer. |
Slash commands (/repo-week, /repo-status, /repo-audit, /repo-sprint, /repo-mirror) | Named recurring task with a fixed shape. |
Agents (repo-doctor, repo-polish, repo-explorer) | Multi-step reasoning, prose synthesis, or file writing. |
Picking the layer
Use raw MCP when the user asks one question
"Show me my Python repos" is one run_sql. Do not invoke an agent. Do not reach for a slash command.
SELECT name, path FROM repos WHERE language = 'Python' ORDER BY name
Same for "how many repos do I have", "which repos are on PyPI", "what are my most starred repos". Direct SQL wins.
Use a slash command for recurring shaped queries
These have a known output format and the user invokes them by name:
/repo-week [Nd]: weekly activity. Top churn, releases, dormant-wake, totals./repo-status [name]: collection overview or single-repo detail card./repo-audit [filters]: read-only summary of ops audit findings./repo-sprint: "what's open?" kickoff context (dirty, unpushed, recent, release candidates)./repo-mirror [flags]: dry-run-first wrapper around ops mirror for redundancy pushes.
Slash commands never write files on their own (mirror is the one exception, and only with --force-real).
Use an agent for multi-step or prose work
repo-doctor: fixed triage workflow. "What needs attention?" Produces a prioritized action list.repo-polish: single-repo release prep. Audits, generates citation/license/codemeta, writes README improvements, syncs GitHub metadata. Writes files.repo-explorer: open-ended analysis. Custom SQL across multiple tables with narrative synthesis.
Common patterns
Language-filtered audit
/repo-audit --language python --severity critical
Summary first. If the user wants to fix a specific repo, hand off to repo-polish.
Release prep flow
/repo-status <name> to confirm state.repo-polish agent for the full audit-fix-improve cycle./repo-audit --language <lang> after the release to confirm nothing regressed collection-wide.
Cross-platform status
SELECT r.name, p.registry, p.package_name, p.current_version, p.published, p.downloads_30d
FROM repos r JOIN publications p ON p.repo_id = r.id
WHERE p.published = 1
ORDER BY p.downloads_30d DESC NULLS LAST
Direct SQL. No agent needed. Join tags if filtering by classification.
Weekly standup for myself
/repo-week 7d
Or 30d for a monthly rollup.
Tag strategy
Tags live in the tags table. The source column tells you where a tag came from:
| Source | Meaning |
|---|
user | Explicitly assigned via mcp__repoindex__tag or repoindex tag add |
implicit | Derived by repoindex from repo state (for example has:ci, has:license) |
github | Imported from GitHub topics |
gitea | Imported from Gitea topics |
pyproject | Extracted from pyproject.toml keywords |
pypi / cran | Registry-derived |
Naming conventions that work well for user-source tags:
work/<area> for work-in-progress groupings: work/active, work/paused, work/release-queue.lang:<name> is already reserved for the implicit language tag. Do not duplicate.published:<registry> is already reserved for implicit publication tags.- Project-domain tags: short nouns like
ml, cli, dsl, paper, plugin.
Use mcp__repoindex__tag to add/remove user tags. Filter by tag with the --tag flag (accepted by copy, link, ops subcommands, and export; supports * wildcards, for example --tag 'work/*'), or from run_sql with the EXISTS (SELECT 1 FROM tags t WHERE t.repo_id = r.id AND t.tag = '...') pattern.
Anti-patterns to avoid
- Do not invoke
repo-explorer for a question that is one run_sql call.
- Do not invoke
repo-doctor for single-repo questions. That is /repo-status or repo-polish.
- Do not run
repoindex ops commands without --dry-run on the first pass. /repo-mirror enforces this; other ops commands rely on the user choosing.
- Do not bypass MCP. The CLI and the MCP server share a database, but MCP is the canonical read path inside Claude Code sessions.
Quick reference
Single question → run_sql
Weekly rollup → /repo-week
Glanceable status → /repo-status
Read-only audit → /repo-audit
Morning kickoff → /repo-sprint
Redundancy push → /repo-mirror
Fixed triage → repo-doctor agent
Release prep (writes) → repo-polish agent
Ad-hoc deep analysis → repo-explorer agent
