github-search

# GitHub Search Search GitHub repositories and code with two complementary workflows: 1. **Executable implementation evaluation** — Brave discovery, deterministic ranking, cloning, entry-point verification, local code evidence, and evaluation. 2. **Direct GitHub search** — repository, code, symbol, path, issue, and file lookup through `gh`. For requests to find a usable implementation, prefer the executable evaluation workflow rather than trusting stars or search snippets alone. ## Prerequisites - `gh` installed and authenticated: `gh auth login` - `git`, Python 3.11+, and either `uv` or `venv`/`pip` - `BRAVE_API_KEY` or `BRAVE_SEARCH_API_KEY` available to the sibling `brave-search` skill - Optional but recommended: `bwrap` for filesystem and network isolation during untrusted execution Check GitHub authentication: ```bash ./run.sh check ``` ## Executable Evaluation Workflow ```bash ./run.sh evaluate "Python OAuth device-code flow" \ --criteria "library, maintained, typed API" \ --min-stars 100 \ --language Python \ --updated-after 2025-01-01 \ --top 3 \ --json ``` The pipeline runs in this order: 1. Call `../brave-search/run.sh web` with a `site:github.com` query. 2. Normalize Brave result URLs to unique `owner/repo` candidates. 3. Enrich candidates with GitHub metadata through `gh repo view`. 4. Apply hard filters such as language, minimum stars, update date, license, archive/fork status, and repository size. 5. Rank survivors with a transparent weighted score: - requested-query and criteria relevance: 55% - logarithmic GitHub star score: 25% - Brave result position: 20% 6. Clone up to five top repositories beneath `/tmp/github-search-eval-*`. 7. Detect an entry point from standard manifests and files, then invoke its help path with a timeout and resource limits. 8. Only when the entry point exits with code 0, search the clean clone for the requested implementation and collect scored snippets. 9. Produce a heuristic assessment using discovery rank, code evidence breadth/strength, and repository signals such as tests, CI, license, README, and package manifests. The JSON result records rejected candidates and filter reasons, ranking components, clone paths, exact commands, exit status, sandbox mode, captured output, relevant files and snippets, score components, limitations, and the best successful candidate. ### Ranking and Filter Options | Option | Meaning | |---|---| | `--criteria TEXT` | Additional free-text relevance criteria | | `--min-stars N` | Minimum GitHub stars | | `--language NAME` | Required primary language | | `--updated-after YYYY-MM-DD` | Required latest update date | | `--license SPDX` | Required SPDX license identifier | | `--candidates N` | Brave results to inspect, 1–20 | | `--top N` | Repositories to clone and execute, 1–5 | | `--max-size-mb N` | Reject repositories above the metadata size limit | | `--include-archived` | Permit archived repositories | | `--include-forks` | Permit forks | ### Entry-Point Options Detection checks, in order: - `[project.scripts]` and Poetry scripts in `pyproject.toml` - Python package `__main__.py` - root `main.py`, `cli.py`, or `app.py` - `package.json` `bin` or `start`/`cli`/`demo` scripts - `Cargo.toml`, `go.mod`, root `run.sh`, and executable files in `bin/` Override detection without invoking a shell: ```bash ./run.sh evaluate "streaming parser" --entrypoint "python3 examples/demo.py --help" ``` The automatic check does not install dependencies. A failure caused by missing dependencies remains a failed candidate rather than silently executing package-install scripts. ### Untrusted Execution Controls Repository code is untrusted. The evaluator: - clones to a dedicated `/tmp` workspace; - runs a disposable copy, preserving a clean source clone for evidence search; - strips inherited credentials and uses a minimal environment and temporary home; - removes symlinks escaping the execution copy; - applies CPU, memory, process, file-size, file-descriptor, timeout, and output limits; - prefers Bubblewrap isolation, then network namespaces, then a clearly labeled host-limited fallback; - disables network where the selected sandbox supports it; - never runs through `shell=True`; - searches and scores code only after a zero exit status. Use strict Bubblewrap-only execution for higher assurance: ```bash ./run.sh evaluate "request router" --sandbox strict --json ``` Network access is off by default. Enable it only when explicitly needed and accepted: ```bash ./run.sh evaluate "client SDK example" --allow-network --json ``` `--allow-network` permits untrusted code to communicate externally; it still receives a scrubbed environment without Brave or GitHub credentials. Clones remain under `/tmp` by default. Use `--cleanup` to remove the workspace after producing the report. ## Direct GitHub Search ```bash # Search repositories ./run.sh search "AI agent memory systems" --limit 5 # Search with current activity/star filters ./run.sh search "satellite security" \ --updated ">=2026-07-20" \ --stars ">0" \ --sort updated \ --order desc \ --limit 10 \ --json # Existing deep GitHub metadata/code analysis ./run.sh search "langchain memory" --deep --json # Analyze a repository ./run.sh repo langchain-ai/langchain --json # Search a symbol definition ./run.sh code "BaseMemory" --repo langchain-ai/langchain --symbol BaseMemory # Search a path ./run.sh code "retrieval" --repo owner/repo --path src/ # Search issues ./run.sh issues "memory leak" --state open # Fetch a file ./run.sh file owner/repo src/main.py ``` ### Sparse Security Domain Workflow For niche domains such as satellite, rocket, avionics, embedded, ICS, RF, or space-hardware penetration testing, do not rely on one GitHub query. Fan out multiple `$brave-search` `site:github.com` questions first, normalize the result URLs to `owner/repo`, then validate candidates with this skill. Recommended sequence: ```bash ../brave-search/run.sh web "site:github.com satellite security testbed penetration testing" --count 10 ../brave-search/run.sh web "site:github.com spacecraft cybersecurity penetration testing satellite" --count 10 ../brave-search/run.sh web "site:github.com cubesat security attack defense testbed" --count 10 ./run.sh search "satellite security" \ --updated ">=2026-07-20" \ --stars ">0" \ --sort updated \ --order desc \ --limit 20 \ --json ./run.sh repo owner/repo --json ./run.sh file owner/repo README.md --json ./run.sh code "attack exploit testbed telemetry command" --repo owner/repo --json ``` Use GitHub filter flags such as `--updated`, `--stars`, `--sort`, and `--order` instead of embedding range qualifiers inside the query string. The GitHub CLI parses those flags more reliably than a single mixed query argument. Promotion criteria for security repositories: - Prefer non-archived, non-fork repositories with real stars, a recent `pushedAt` or `updatedAt`, clear license, README, testbed/lab framing, and relevant code paths or documentation. - Treat `updatedAt` as repository activity. Prefer `pushedAt` when the question requires code changed this week. - Down-rank generic curated lists unless the user asked for resources rather than a runnable repo. - Do not run untrusted penetration-testing, exploit, malware, red-team, or dual-use code on the host. Use the executable evaluation workflow with `--sandbox strict` where possible, or hand the selected repo to a disposable Docker/container harness. ## Evaluation Guidance Treat the automated assessment as triage, not proof. A successful `--help`-style entry point demonstrates that the detected surface loads and exits cleanly under the selected environment; it does not establish full functional correctness. Read the cited snippets, inspect tests and license terms, and explain any missing dependencies, reduced sandboxing, weak evidence, stale metadata, or ambiguous matches in the final recommendation. ## Optional Integrations Fetched code can still be passed to `/treesitter` for symbol extraction and `/taxonomy` for classification. The executable evaluation path performs local evidence search first so that post-run analysis is based on the exact cloned revision.