Stop Drowning in GitHub Issues! Simili-Bot Is the AI Rescue Team You Need

What if your open-source project could triage itself while you sleep?

Picture this: It's 2 AM. A user in Tokyo files an issue. Three hours later, someone in Berlin reports the same bug with completely different words. By morning, your backlog has swollen with semantic clones your keyword-searching brain—and your keyword-matching tools—never caught. Your maintainers are burned out. Your contributors are confused. And that critical security issue? Buried under a pile of "similar but not quite" duplicates.

Sound familiar? You're not alone. The average popular GitHub repository receives 50-200 issues per week, and studies suggest 15-30% are duplicates that waste hundreds of hours annually. Traditional bots? They grep for keywords. They miss intent. They route based on labels slapped on by exhausted humans.

Enter Simili-Bot—the open-source AI-powered GitHub issue intelligence platform that's making manual triage feel as outdated as Subversion. Built by the Simili team and gaining rapid traction in the developer community, Simili-Bot doesn't just find duplicates. It understands them. It doesn't just search issues. It reasons across repositories. And it doesn't just label—it routes, assesses, and acts with the precision of a senior maintainer who never sleeps.

Ready to reclaim your sanity? Let's dissect why top open-source projects are quietly adopting this tool—and how you can deploy it before your next issue storm hits.

What Is Simili-Bot?

Simili-Bot is an AI-powered GitHub issue intelligence system that transforms how development teams handle issue management through three core superpowers: semantic duplicate detection, cross-repository search, and intelligent issue routing.

Created by the Simili team (similigh), this open-source project (Apache 2.0 licensed) represents a fundamental shift from rule-based issue bots to embedding-driven, LLM-augmented intelligence. While traditional tools like GitHub's native search or basic keyword matchers operate at the lexical level—hunting for word overlaps—Simili-Bot leverages vector embeddings to capture semantic meaning, intent, and conceptual similarity.

The project is trending now for several converging reasons:

• The AI tooling explosion: Post-2023, developers expect LLM-powered assistance in every workflow gap. Issue management was a glaring omission.
• Maintainer burnout crisis: Open-source sustainability research consistently identifies issue triage as a top contributor to maintainer exhaustion.
• Multi-repo complexity: Organizations managing dozens of repositories need centralized intelligence, not per-repo silos.
• Embedding economics: Models like Google's gemini-embedding-001 and OpenAI's text-embedding-3-small have made high-quality semantic search cost-effective at scale.

Simili-Bot's architecture reflects modern platform engineering principles. Its "Lego with Blueprints" design separates concerns into reusable pipeline steps ("Lego blocks") that compose into pre-defined workflows ("Blueprints"). A Git-based state management system using orphan branches eliminates the fragility of comment-scanning approaches that break when users edit or delete bot comments.

The project supports dual AI provider flexibility (Gemini and OpenAI), zero-dependency deployment options via GitHub's native search API, and a powerful CLI for local development and batch operations. With its modular design, you can run anything from a lightweight similarity checker to a full autonomous triage pipeline.

Key Features That Separate Simili-Bot from the Herd

Semantic Duplicate Detection (Not Your Father's Keyword Search)

Traditional duplicate detection hunts for word overlap. "App crashes on login" and "Authentication failure prevents access" are invisible to keyword matchers. Simili-Bot's embedding-based similarity search maps issues into high-dimensional vector space where semantic proximity reveals hidden relationships.

The system uses 3072-dimensional embeddings (Gemini) or 1536-dimensional (OpenAI small) to capture nuanced meaning. A configurable similarity threshold (default 0.65) lets you tune precision versus recall for your domain. Critical bugs with urgent language cluster together. Vague feature requests surface their cousins.

Cross-Repository Search

Issues don't respect repository boundaries. A Flutter plugin bug might belong in the framework repo. A documentation gap spans three packages. Simili-Bot's cross-repository search indexes issues organization-wide, enabling maintainers to find relevant precedents, existing fixes, and proper routing targets across the entire GitHub organization.

Intelligent Routing

Beyond detection lies action. Simili-Bot's LLM-powered analysis determines the correct repository destination for misfiled issues and can automatically transfer them. This isn't keyword-based routing—it's contextual reasoning about code ownership, issue content, and repository purpose.

Smart Triage with AI-Powered Labeling

The Triage Analysis step assesses issue quality, suggests labels, identifies missing information, and flags potential duplicates. The system generates structured feedback that helps reporters improve their submissions while guiding maintainers to priority items.

Modular Pipeline Architecture

The four-stage pipeline—Gatekeeper → Similarity Search → Triage Analysis → Action Executor—lets you customize workflows without forking code. Need similarity-only mode for a "Find Similar Issues" button? Swap the Blueprint. Want to add custom validation? Insert a Lego block.

Multi-Backend Search Flexibility

Not ready for vector database infrastructure? Simili-Bot offers three search backends:

• Qdrant (default): Full semantic search with vector database
• GitHub Native: Zero-dependency hybrid search using GitHub's API
• BM25: Local keyword search for air-gapped or minimal setups

This flexibility means you can start simple and scale to semantic intelligence without architecture changes.

Real-World Use Cases Where Simili-Bot Shines

Use Case 1: The Burnt-Out Open-Source Maintainer

You're sole-maintaining a library with 50K stars. Issues pour in faster than you can read titles. Simili-Bot's auto-triage workflow runs on every new issue: checks for duplicates, assesses quality, applies labels, and posts structured feedback. The auto-close feature handles stale potential-duplicate labels after a configurable grace period with human-activity safeguards. You focus on code, not clerical work.

Use Case 2: The Multi-Repo Enterprise Platform Team

Your organization maintains 40 microservices across as many repositories. Issues land in wrong repos constantly. Users can't find existing solutions. Simili-Bot's organization-wide setup with centralized configuration and per-repo overrides creates a unified issue intelligence layer. Cross-repo search surfaces solutions from Service A that solve Service B's problem. Intelligent routing moves issues to correct destinations automatically.

Use Case 3: The Community Manager Building Self-Service

You want contributors to find answers before filing duplicates. Simili-Bot's similarity-only workflow powers a "Related Issues" feature in your issue template. Reporters see semantically similar closed issues with resolutions—reducing duplicate influx by 40-60% before maintainers ever see them.

Use Case 4: The Data-Driven Quality Initiative

Your team needs to analyze historical issue patterns without spamming live repositories. Simili-Bot's batch mode processes issue archives in dry-run (no GitHub writes), outputting CSV reports showing similarity clusters, quality scores, and routing recommendations. Identify systemic documentation gaps, recurring confusion points, and repository boundary problems with empirical evidence.

Use Case 5: The CI/CD Integration for Zero-Touch Triage

Embed Simili-Bot in GitHub Actions workflows triggered on issue creation, comment updates, or scheduled runs. The reusable workflow pattern lets organizations deploy consistent triage logic across hundreds of repositories with single-point configuration updates.

Step-by-Step Installation & Setup Guide

Prerequisites

• A GitHub repository or organization
• Go 1.21+ (for CLI usage) or GitHub Actions (for automated workflows)
• API keys for Gemini and/or OpenAI
• Qdrant instance (for semantic search backend; optional if using github_native or bm25)

Step 1: Clone and Build (Local Development)

# Clone the repository
git clone https://github.com/similigh/simili-bot.git
cd simili-bot

# Build the project
go build ./...

# Verify installation
./simili --help

Step 2: Configure AI Provider Credentials

Set at least one API key as environment variables:

export GEMINI_API_KEY="your-gemini-key-here"
# OR
export OPENAI_API_KEY="your-openai-key-here"
# OR both (Gemini takes precedence if both set)

Default model assignments when using environment variables:

• LLM: gemini-2.0-flash-lite (Gemini) or gpt-5.2 (OpenAI)
• Embeddings: gemini-embedding-001 (Gemini) or text-embedding-3-small (OpenAI)

Step 3: Create Repository Configuration

Create .github/simili.yaml in your target repository:

qdrant:
  url: "${QDRANT_URL}"
  api_key: "${QDRANT_API_KEY}"
  collection: "my-issues"

embedding:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"
  model: "gemini-embedding-001"
  dimensions: 3072  # Must match model: 3072 for gemini-embedding-001

llm:
  provider: "gemini"
  api_key: "${GEMINI_API_KEY}"
  model: "gemini-2.5-flash"
  # temperature: 0.3  # Optional: control creativity vs determinism

defaults:
  similarity_threshold: 0.65
  max_similar_to_show: 5

# Optional: Configure auto-close behavior
auto_close:
  grace_period_hours: 48   # Default: 72 hours
  dry_run: false

Critical configuration notes:

• llm.model defaults to gemini-2.5-flash when omitted
• llm.api_key can be omitted if GEMINI_API_KEY environment variable is set
• Override at runtime with LLM_MODEL environment variable
• Keep embedding.dimensions synchronized with your chosen model

Step 4: Index Existing Issues

Populate your vector database with historical issues:

# Index with 10 concurrent workers, limiting to first 100 issues for testing
simili index --repo your-org/your-repo --workers 10 --limit 100

# Full index of a large repository
simili index --repo ballerina-platform/ballerina-library --workers 10

Step 5: Deploy GitHub Actions Workflow

For single-repository setup, copy the standard workflow from DOCS/examples/single-repo/. For organization-wide deployment, use the reusable workflow pattern from DOCS/examples/multi-repo/ with centralized configuration.

Step 6: Verify and Monitor

# Test processing on a single issue (dry-run, no side effects)
simili process --issue test-issue.json --workflow issue-triage --dry-run

REAL Code Examples from Simili-Bot

Let's examine actual usage patterns from the Simili-Bot repository, with detailed explanations of what each command accomplishes and when to deploy it.

Example 1: Bulk Indexing with Controlled Concurrency

simili index --repo owner/repo --workers 5 --limit 100

Before you run this: Indexing is the foundation of Simili-Bot's semantic intelligence. Without indexed issues, similarity search returns nothing. This command populates your Qdrant vector database with embedding vectors representing each issue's semantic content.

Flag breakdown:

• --repo owner/repo: Required. Specifies target repository in owner/name format. The tool fetches all accessible issues via GitHub API.
• --workers 5: Controls concurrent API requests. Higher values speed indexing but consume more rate limit. Start with 5, increase to 10-20 for large repos with generous GitHub API quotas.
• --limit 100: Caps indexing for testing or partial updates. Omit for full historical index.
• --since: (Not shown) Resume from specific issue number or timestamp—critical for incremental updates.
• --dry-run: (Not shown) Simulate without database writes—essential for validating configuration before production indexing.

Error handling insight: If any worker panics or hits an unrecoverable error, Simili-Bot exits non-zero immediately and cancels all in-flight workers cleanly. This prevents the hanging processes that plague many CI-integrated tools. Your GitHub Actions won't timeout mysteriously.

When to use: Initial setup, weekly re-indexing schedules, or after significant configuration changes.

Example 2: Single Issue Processing with Dry-Run Safety

simili process --issue issue.json --workflow issue-triage --dry-run

Before you run this: The process command is your debugging and validation workhorse. It runs a single issue through your configured pipeline without requiring live GitHub webhook events.

Flag breakdown:

• --issue issue.json: Path to JSON file containing issue data. Format matches GitHub's issue API response.
• --workflow issue-triage: Selects the full pipeline preset. Alternatives: similarity-only, index-only.
• --dry-run: Critical safety flag. Executes all analysis without posting comments, applying labels, or transferring issues. Perfect for testing configuration changes.
• --repo, --org, --number: Override fields from the JSON file—useful for testing hypothetical scenarios.

Practical pattern: Create a test-issues/ directory with representative issues (bug reports, feature requests, duplicates, low-quality submissions). Run simili process --dry-run against each after any configuration change to verify behavior before live deployment.

Example 3: Batch Analysis for Historical Insights

simili batch --file issues.json --format csv --out-file results.csv --workers 5

Before you run this: Batch mode is Simili-Bot's secret weapon for data-driven issue management. Unlike process, which handles single issues, batch analyzes collections—and critically, always runs in dry-run mode to prevent accidental GitHub modifications during analysis.

Flag breakdown:

• --file issues.json: Required. JSON array of issue objects (format detailed below).
• --format csv: Output format. json provides full pipeline results; csv flattens for spreadsheet analysis.
• --out-file results.csv: Destination file. Omit for stdout (useful for piping to other tools).
• --workers 5: Concurrent processing. Tune based on API rate limits and desired throughput.
• --threshold, --duplicate-threshold, --top-k: Override configuration defaults for this run without modifying simili.yaml.

Input format requirement:

[
  {
    "org": "owner",
    "repo": "repo-name",
    "number": 123,
    "title": "Issue title",
    "body": "Issue description...",
    "state": "open",
    "labels": ["bug", "high-priority"],
    "author": "username",
    "created_at": "2026-02-10T10:00:00Z"
  }
]

Output insights: The CSV includes similarity scores, duplicate confidence, recommended labels, quality assessments, and transfer recommendations. Import to your analytics tool to identify patterns invisible in GitHub's native interface.

Error handling guarantee: Failed workers cancel in-flight operations and report errors explicitly in output. No silent failures. No CI hangs.

Complete workflow example:

# 1. Index repository issues for semantic search capability
simili index --repo ballerina-platform/ballerina-library --workers 10

# 2. Prepare test issues in batch.json (export from GitHub API or construct manually)

# 3. Run batch analysis with CSV output for spreadsheet review
simili batch --file batch.json --format csv --out-file analysis.csv --workers 5

# 4. Review results—look for clustering patterns, misrouted issues, quality trends
cat analysis.csv

Example 4: Auto-Close with Grace Period Intelligence

simili auto-close --repo owner/repo --grace-period-minutes 60

Before you run this: The auto-close command solves the "stale duplicate" problem—issues labeled potential-duplicate where no human ever confirmed or denied. Manual cleanup is tedious; automated cleanup without safeguards is dangerous.

Flag breakdown:

• --repo owner/repo: Required. Target repository. Falls back to GITHUB_REPOSITORY environment variable for CI usage.
• --grace-period-minutes 60: Override default 72-hour grace period. Useful for urgent cleanup or testing.
• --dry-run: Preview what would close without action.
• --config: Explicit configuration path (auto-discovered if omitted).

Grace period precedence (highest to lowest):

1. CLI --grace-period-minutes flag
2. auto_close.grace_period_hours in simili.yaml
3. Built-in default: 72 hours

Human activity safeguards—auto-close blocked if ANY occur:

1. 👎 or 😕 reaction on bot's triage comment by non-bot user
2. Human reopened issue after potential-duplicate label applied
3. Non-bot comment posted after label applied

GitHub Actions integration:

# Trigger manually with optional overrides
gh workflow run auto-close.yml -f grace_period_minutes=60 -f dry_run=false

The workflow runs daily at 10:00 UTC via schedule, or on-demand via workflow_dispatch.

Advanced Usage & Best Practices

Optimize Your Embedding Model Choice

Gemini gemini-embedding-001 (3072 dimensions) offers superior multilingual performance and Google's long-context understanding. OpenAI text-embedding-3-small (1536 dimensions) provides cost efficiency at scale. For maximum accuracy with technical issues, text-embedding-3-large (3072 dimensions) captures nuanced domain vocabulary. Benchmark with simili batch on historical data before committing.

Tune Similarity Thresholds Empirically

The default similarity_threshold: 0.65 is a starting point. Your domain matters:

• High-precision needs (security issues, critical bugs): Raise to 0.75-0.80
• High-recall needs (community support, documentation): Lower to 0.55-0.60

Use batch analysis on labeled historical duplicates to find your optimal threshold.

Leverage State Branch for Auditability

Simili-Bot's Git-based state management (orphan branch) creates an immutable audit trail. Unlike comment-based state that breaks on edits, the state branch preserves complete decision history. Clone it for compliance reviews or debugging unexpected behavior.

Implement Progressive Rollout

Deploy similarity-only workflow first to build team trust. Add issue-triage after observing false positive rates. Enable auto-close only after triage accuracy satisfies your standards. This staged approach prevents the backlash that kills automation adoption.

Monitor Worker Concurrency

The --workers flag is your throughput lever. GitHub API rate limits (5000 requests/hour for authenticated requests) constrain maximum speed. For large repositories, implement exponential backoff in wrapper scripts or use GitHub Apps with higher rate limits.

Comparison with Alternatives

Why Simili-Bot wins: It combines commercial-grade AI with open-source flexibility and GitHub-native deployment. No vendor lock-in. No per-seat pricing. Full auditability. And unlike basic bots, it actually understands issue content, not just surface text.

Frequently Asked Questions

Is Simili-Bot free to use?

Yes. Simili-Bot is Apache 2.0 licensed open source. You pay only for API usage (Gemini or OpenAI) and infrastructure (Qdrant, if used). The github_native and bm25 backends eliminate infrastructure costs entirely.

Do I need a vector database to get started?

No. While Qdrant enables full semantic search, the github_native backend uses GitHub's API with no additional infrastructure. Start there, migrate to Qdrant when you need maximum accuracy.

Can Simili-Bot modify or delete my issues?

Only with explicit configuration. The issue-triage workflow posts comments and applies labels by default. Transfers and closures require explicit enablement. The --dry-run flag previews all actions safely.

What happens if the AI misidentifies a duplicate?

Human activity signals (reactions, comments, reopening) block auto-close. The potential-duplicate label (not immediate closure) provides review opportunity. Tune similarity_threshold higher for more conservative matching.

How does Simili-Bot handle rate limits?

The CLI implements clean worker cancellation on errors. For GitHub API limits, control concurrency with --workers and implement retry logic in CI wrappers. Consider GitHub Apps for 15,000 requests/hour limits.

Can I use Simili-Bot with GitHub Enterprise Server?

Yes, with API endpoint configuration. The CLI accepts custom GitHub API URLs. Ensure your GHES version supports required API features (issue transfers, labels, reactions).

Is my issue data sent to third-party AI providers?

Issue titles and bodies are sent to your configured provider (Gemini or OpenAI) for embedding and LLM analysis. No data reaches Simili's infrastructure. Review provider data policies for compliance requirements.

Conclusion: Reclaim Your Issue Tracker Before It Reclaims Your Sanity

Manual issue triage doesn't scale. Keyword-based duplicate detection misses intent. And maintainer burnout is killing the open-source projects we depend on.

Simili-Bot offers a technically sophisticated, architecturally flexible, and genuinely intelligent alternative. Its embedding-driven semantic search, LLM-powered triage, and modular pipeline design transform issue management from reactive drudgery into proactive intelligence. The "Lego with Blueprints" architecture grows with your needs. The multi-backend support lets you start today without infrastructure commitments. And the comprehensive CLI empowers data-driven optimization.

I've evaluated dozens of issue management tools. Most automate bureaucracy; Simili-Bot automates understanding. That's the difference between a bot that spams labels and one that genuinely assists maintainers.

Your next step: Star the Simili-Bot repository, deploy the github_native backend on a test repository this afternoon, and experience what issue intelligence actually feels like. Your future self—sleeping through the night while Simili-Bot handles the 2 AM Tokyo duplicate—will thank you.

Found this breakdown valuable? Give Simili-Bot a star on GitHub and share your deployment experience in the discussions. The maintainers are actively iterating, and real-world feedback shapes the roadmap.