GitHub Semantic Repo Finder (find-repo)

---

💡 Overview

Find-Repo is an autonomous Agent Skill and developer CLI tool designed to find GitHub repositories through natural semantic search, discover reference implementations & peer repositories, and inspect codebase health to accelerate app development.

The Problem it Solves

GitHub's native search uses strict token intersection matching. If you search for:

"I want to build a lightweight desktop chat app with local LLMs in Rust"

GitHub's search engine attempts to match every single word in exact sequence or ngram, frequently returning zero results.

The Solution

find-repo acts as an intelligent semantic bridge:

1. Decomposes natural intent into domain concepts, tech stack filters, and search vectors.
2. Executes multi-query fan-outs across keywords, GitHub topic tags, and description qualifiers.
3. Reranks candidates with a composite score balancing semantic text relevance, star adoption, and commit freshness.
4. Discovers peer repositories & cross-framework ports (e.g. Svelte or Vue equivalents of React components).
5. Inspects architecture & health before you clone.

---

🏗️ Architecture & Workflow

flowchart TD
    User(["Developer Prompt / Problem Statement"]) --> Agent["Antigravity / AI Agent"]
    Agent --> Decomposer["Intent Decomposition Engine\n(find_repo.py)"]
    
    subgraph FanOut ["Multi-Vector Query Fan-Out"]
        Decomposer --> Q1["Vector 1: Core Keywords + Language Qualifier"]
        Decomposer --> Q2["Vector 2: Topic-Clustered Query (topic:*)"]
        Decomposer --> Q3["Vector 3: Scope-Restricted (in:name,description)"]
        Decomposer --> Q4["Vector 4: Synonyms & Tech Associations"]
    end
    
    FanOut --> Executor["GitHub Search API / gh CLI\n(Parallel Execution & Deduplication)"]
    Executor --> RawCandidates["Candidate Pool"]
    
    subgraph Scoring ["Composite Reranking Engine"]
        RawCandidates --> TextMatch["Relevance Match (Title, Topics, Description)"]
        RawCandidates --> Freshness["Recency Bonus (< 30d, < 90d, Dormant Penalty)"]
        RawCandidates --> Trust["Log-Scaled Popularity & Stars"]
        RawCandidates --> Quality["License, Issues & Template Signals"]
        TextMatch & Freshness & Trust & Quality --> CompositeScore["Ranked & Filtered Results"]
    end
    
    CompositeScore --> Output["Actionable Developer Report\n(Ranked Repos, Stack Analysis, Code Structure, Direct Links)"]

Loading

---

🔄 Similarity & Peer Discovery

flowchart LR
    Source["Target Repository\n(e.g., shadcn-ui/ui)"] --> Extractor["Metadata & Topic Extractor"]
    Extractor --> Overlap["Topic Overlap Queries\n(topic:components topic:tailwind)"]
    Extractor --> Alts["Alternative / Clone Mentions\n('alternative to shadcn')"]
    Extractor --> CrossLang["Cross-Framework Equivalence\n(e.g., --language Svelte)"]
    
    Overlap & Alts & CrossLang --> Peers["Peer & Similar Repositories\n(e.g., bits-ui, shadcn-svelte)"]

Loading

---

🚀 Quick Start

1. Installation

Clone and link CLI:

git clone https://github.com/will702/find-repo.git
cd find-repo
chmod +x ./bin/find-repo

Install Globally as an Agent Skill:

./install.sh

This automatically installs the skill into ~/.gemini/config/skills/find-repo, making it globally available across all Antigravity agent sessions.

---

💻 CLI Usage

1. Semantic Search

Search for repositories using natural developer intent:

./bin/find-repo search "modern offline kanban board" -l Svelte -n 5

./bin/find-repo search "React flow chart diagram editor with drag and drop nodes" --min-stars 50 -n 3

2. Similarity & Alternative Discovery

Find similar repositories or cross-framework equivalents:

# Find Svelte equivalents to shadcn-ui
./bin/find-repo similar "shadcn-ui/ui" -l Svelte -n 5

# Find alternatives to Supabase or Pocketbase
./bin/find-repo similar "pocketbase/pocketbase" -n 5

3. Deep Architecture & Health Inspection

Inspect commit recency, health status, licensing, language breakdown, and directory layout:

./bin/find-repo inspect "sereneblue/nimbo"

Options Reference

Command	Flag	Description
search	-l, --language <Lang>	Restrict search to specific language
search	--min-stars <N>	Filter out repos below star threshold
search	-n, --limit <N>	Number of candidates to return (default: 10)
search	--template	Restrict to official GitHub template repositories
search	--sort <mode>	Sort mode (best-match, stars, updated)
search	--json	Output machine-readable JSON
similar	-l, --language <Lang>	Filter similar repos by target language
similar	-n, --limit <N>	Number of candidates to return
similar	--json	Output machine-readable JSON
inspect	--json	Output machine-readable JSON

---

🤖 AI Agent Integration

This repository conforms to standard agent skill specifications:

• Antigravity / Gemini CLI: .agents/skills/find-repo/SKILL.md
• Cursor / Cline / Copilot: AGENTS.md and .github/copilot-instructions.md

Example Prompts for Agents

• "Find me a starter boilerplate with Next.js 15, Supabase auth, and Tailwind CSS."
• "I need a lightweight embedded vector database in Go. Find the best reference repos."
• "Find open-source alternatives to Linear built with modern web tech."
• "Inspect the architecture of tauri-apps/tauri and tell me how it organizes IPC commands."

---

📂 Repository Layout

find-repo/
├── .agents/
│   └── skills/
│       └── find-repo/
│           ├── SKILL.md                 # Agent skill instructions
│           ├── scripts/
│           │   └── find_repo.py         # Search, similarity, and inspect engine
│           └── references/
│               ├── search_syntax_guide.md  # GitHub search qualifiers
│               └── evaluation_criteria.md  # Repo evaluation guide
├── assets/
│   └── banner.jpg               # Hero illustration banner
├── bin/
│   └── find-repo                # CLI entry point
├── tests/
│   └── test_find_repo.py        # Automated test suite
├── .github/
│   ├── copilot-instructions.md  # Copilot & agent workspace rules
│   └── workflows/
│       └── test.yml             # GitHub Actions CI matrix
├── AGENTS.md                    # Agent guidelines & discovery
├── GEMINI.md                    # Antigravity rule link
├── install.sh                   # Global installation script
├── LICENSE                      # MIT License
└── README.md                    # Documentation

---

🧪 Testing

Run the automated test suite:

python3 -m unittest discover -s tests

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more details.