pardeike/githubcodesearch/github-code-search

GitHubCodeSearch

GitHubCodeSearch is intended to make broad code research repeatable: GitHub is for repository discovery and fetching; the local corpus is the source of truth for code evidence.

Workflow

1. Start with corpus_status.

Check implementedTools, corpus paths, backend status, and next actions before assuming a tool produces evidence.

1. Use corpus_discover for repository discovery.

Pack as much intent as possible into one rich request instead of spending quota on several narrow searches. Use dryRun:true first whenever shaping the query.

1. Treat discovery results as leads.

corpus_discover uses GitHub repository search metadata. It can identify candidate repos, but it does not prove a symbol, call site, Harmony patch, or return behavior exists in code.

1. Acquire repositories before evidence claims.

Use corpus_acquire on selected candidate IDs. Acquisition clones or refreshes working trees under the local corpus cache and records the resolved commit.

1. Use local evidence.

Prefer code_search, harmony_find_patches, and evidence_get over GitHub web or API search for final answers. code_search currently searches acquired working trees with ripgrep; Zoekt remains deferred.

Discovery Query Shape

Prefer structured arguments:

{
  "query": "rimworld harmony",
  "terms": ["TickManager"],
  "exactTerms": ["DoSingleTick Prefix"],
  "in": ["name", "description", "readme", "topics"],
  "language": "C#",
  "topic": "rimworld",
  "stars": ">=5",
  "pushed": ">=2024-01-01",
  "forkMode": "include",
  "archived": false,
  "sort": "stars",
  "order": "desc",
  "limit": 100,
  "dryRun": true
}

Useful fields:

• query, terms, exactTerms: put the broad concept, names, and exact phrases here.
• language/languages, topic/topics, organization/organizations, user/users, repository/repositories: scope the candidate set.
• stars, forks, created, pushed, size, license, visibility, archived, forkMode: prune low-value candidates early.
• customQualifiers: add raw GitHub repository-search qualifiers not yet modeled by the tool.
• sort, order, page, limit, includeTextMatches: map to GitHub Search API request parameters.

Inspect builtQuery from a dry run. Only remove dryRun after the query is specific enough to justify a GitHub request.

Limits

• GitHub repository search is still rate-limited by GitHub.
• limit maps to GitHub per_page and is capped at 100.
• Discovery is repository-level metadata search, not code search.
• corpus_acquire accepts candidate IDs returned by corpus_discover, and also accepts github:owner/repo IDs as a pragmatic direct acquisition path.
• code_search returns stable hit IDs with repository, commit, path, line span, snippet, and local path. Use evidence_get to retrieve context for a hit ID.
• harmony_find_patches is a pragmatic C# text analyzer. It handles common attribute and manual patch forms, but classifications should still be audited from returned evidence snippets.
• Tool schema changes usually require restarting Codex. Implementation changes behind an existing schema can be redeployed, but a running stdio child may keep old code until the client respawns it.

Maintenance

Use scripts/deploy-codex-mcp.sh after code or skill changes. It formats Go code, runs tests and vet, builds and installs the MCP binary, installs this skill to ${CODEX_HOME:-~/.codex}/skills/github-code-search, updates Codex MCP config, smoke-tests the installed server, and prints only OK on success.