Skip to main content
xists

xists

Find what exists. Decide what's next.

xists is a local semantic search engine for selected lists of GitHub repositories. Find existing projects you can use, deploy, adapt, or learn from—then decide what to do next.

English · 简体中文


Why xists?

Global GitHub search is often noisy, and traditional keyword matching lacks semantic understanding. xists solves this by narrowing the search space: you provide a curated repository list, and xists builds a local index for semantic search.

  • Before you decide: check if a similar project or existing solution already exists.
  • Tech decisions: compare candidates from a curated set using semantic search.
  • Fast lookups: quickly find what you need without manually opening dozens of READMEs.

How it works

flowchart LR
    A[Repo List] --> B[Ingest Metadata]
    B --> C[Generate LLM Summaries]
    C --> D[Build Local Index]
    D --> E[Search]
    D -. optional .-> F[Evaluate Ranking]
    F -.-> G[Inspect Misses]
  1. Ingest: Provide a list of GitHub repos. xists fetches their metadata and READMEs.
  2. Profile: It uses an LLM to generate compact, search-optimized summaries for better matching.
  3. Index: It builds a local JSON embedding index.
  4. Search: You query the index using semantic search.

Local-first index, explicit model endpoints

xists keeps everything transparent and local:

  • records.json: Raw metadata, structure signals, and LLM-generated profiles.
  • index.json: The embedding index.
  • eval-report.json: Search quality test results.

You need a GitHub token for the initial data fetch, plus model endpoints for summaries and embeddings. The records, index, ranking, and evaluation report stay on your machine. An embedding endpoint calculates vectors; xists stores them in local JSON and compares them locally.

Requires Python 3.11+. Install the published package:

python -m pip install xists

For development from a checked-out source tree, install the editable package with test dependencies:

python -m pip install -e ".[dev]"

Then initialize the default local workspace, add repositories you control to ~/.xists/repos.txt, and configure its .env file:

xists init
# Edit ~/.xists/.env and add owner/repo lines to ~/.xists/repos.txt.

xists ingest github
xists index build
xists search "open source firebase alternative"

See the demo walkthrough for endpoint checks, concurrency, evaluation, and troubleshooting. No current-schema demo records/index download is published yet; the first Release asset will be created only after it passes records validate and index verify.


MCP and agent integration

Install the optional MCP integration after a workspace has an index and an embedding configuration:

python -m pip install "xists[mcp]"
xists mcp

xists mcp uses stdio and reads the same active workspace as the CLI. It loads the index when the server starts; rebuild the index and restart the MCP server when data changes. It exposes search_projects, inspect_project, and index_stats. Search results include the same ranking and abstention behavior as the CLI, so diagnose an agent request with:

xists search "browser automation for agents" --format json

For Claude Code, Cursor, or Cline, add a stdio server entry using this shape in that client's MCP configuration:

{
  "mcpServers": {
    "xists": {
      "command": "xists",
      "args": ["mcp"]
    }
  }
}

The server follows the normal configuration precedence: shell environment, current-directory .env, then ~/.xists/.env. A remote embedding endpoint receives each search query to calculate its vector; the index and similarity search remain local. An abstained: true response means the current index did not contain a sufficiently credible match and should be treated as that state, not as a hidden failure.

Optional Codex skill

The repository also includes the xists-project-search Skill. It tells Codex when to use a configured xists MCP server, limits unnecessary tool calls, and preserves honest no-result behavior. Install it from GitHub with the bundled Codex installer:

python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo UsonTong/xists --path skills/xists-project-search

After starting a new Codex turn, requests to find or compare existing open-source projects can use the Skill and your configured xists MCP server. The Skill contains no index, endpoint, or credential configuration; configure the MCP server separately.


Quickstart

Requires Python 3.11+.

# Install
python -m pip install -e ".[dev]"

# Set up the default workspace configuration
xists init
# Edit ~/.xists/.env with your GitHub token, LLM model, and embedding model

Run the pipeline:

# 1. Fetch data & generate summaries
xists ingest github \
  --repos repos.txt \
  --output demo-records.json \
  --report demo-report.json \
  --github-api graphql

# 2. Build the local index
xists index build \
  --records demo-records.json \
  --output demo-index.json

# 3. Search!
xists search "open source firebase alternative" --index demo-index.json
xists search "open source firebase alternative" --index demo-index.json --format json

The commands above generate local files and may call the endpoints configured in .env; use records.json / index.json instead if you do not want files named as demo artifacts.


Python API

Use the stable API when another Python program needs the same search behavior as the CLI. Configuration is always explicit; importing xists.api does not read .env or send network requests.

from xists.api import load_index, search
from xists.search.embed import EmbeddingConfig

index = load_index("index.json")
config = EmbeddingConfig(
    api_key="your-key",
    base_url="https://your-embedding-endpoint/v1",
    model="your-embedding-model",
)
result = search("open source firebase alternative", index, embedding_config=config, top_k=5)

search() may call the endpoint in config to embed the query. It raises actionable Python exceptions for invalid indexes, incompatible embedding models, and endpoint failures instead of printing or terminating the process.


Data, security, and privacy

  • .env and token files are read only from your local machine; xists does not commit, print, telemetry-report, or upload their secret values.
  • ingest github sends your GitHub token only to GitHub. profile refresh and ingest-time profile generation send repository text to the configured LLM endpoint. index build sends embeddable repository text to the configured embedding endpoint; search and eval run send query text to that endpoint.
  • A local endpoint keeps those requests on your machine or network. A remote endpoint receives the corresponding text under that provider's terms; choose it only when you are permitted to send the material. xists does not host the endpoint, upload your index, or perform vector search remotely.
  • If you share records or indexes, you are responsible for checking repository licenses, source content, generated profiles, and any personal or sensitive information before distribution.

Search Result Example

When you run a search, xists returns a compact text view by default for terminal review. Add --format json for scripts and agent integrations. Search combines embedding similarity with bounded, explainable metadata signals. Exact owner/repo and exact name/alias lookups are pinned first; project names mentioned inside a broader natural-language request remain contextual evidence rather than an exact lookup.

Default text output looks like this:

query: hermes ai agent
intent: functional
abstained: False
results: 1
1. repo: NousResearch/hermes-agent
   url: https://github.com/NousResearch/hermes-agent
   confidence: high_confidence
   score: 0.680000
   summary: An agent-oriented project for Hermes models.
   why: matched metadata terms: agent

The JSON output keeps the same ranking evidence in a machine-readable shape:

{
  "query": "hermes ai agent",
  "results": [
    {
      "repo_id": "NousResearch/hermes-agent",
      "url": "https://github.com/NousResearch/hermes-agent",
      "score": 0.68,
      "semantic_score": 0.63,
      "metadata_score": 0.05,
      "confidence": "high_confidence",
      "why": ["matched metadata terms: agent"]
    }
  ]
}

score is the final ranking score; higher means a stronger match. Use --format json when another program or agent needs the structured payload.

Chinese and mixed-language requests are first-class query inputs. xists keeps ASCII technical identifiers such as Node.js, C++, C#, .NET, and owner/repo, while extracting a bounded set of CJK bigrams/trigrams for query intent, metadata overlap, and explanations. See the current retrieval baseline and run the committed offline contract fixture with python scripts/run_retrieval_regression.py.


Optional Evaluation

If you update the repository list, regenerate summaries, or change the search setup, xists lets you run fixed test cases to sanity-check whether results changed in a meaningful way.

pytest
xists eval run \
  --cases examples/eval-cases.json \
  --index demo-index.json \
  --output demo-eval-report.json

xists eval inspect --report demo-eval-report.json --status serious_mismatch

The report groups results into pragmatic categories:

  • Exact match: The specific target repo was #1.
  • Acceptable alternative: Not the exact target, but a valid substitute (e.g., returning Vue when you asked for a React-like framework).
  • Serious mismatch: The top result missed the core intent.
  • Insufficient evidence: The indexed data was too thin to judge.

Commands

  • xists doctor: Check config and file status; add --check-endpoints or --strict to probe the embedding service.
  • xists ingest github: Fetch repo metadata and generate summaries.
  • xists index build: Build or incrementally update the local index.
  • xists search "query": Query the local index with readable terminal output by default; add --format json for scripts and agents.
  • xists eval cases / xists eval run / xists eval inspect: Validate the dataset and run/review ranking tests.
  • xists records validate / xists records stats / xists records inspect: Check record quality without printing huge payloads to your terminal.
  • xists index stats / xists index verify: Summarize an index and confirm it is in sync with records.

Metadata

Release files for xists 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xists 0.9.0
File Size Uploaded Provenance Actions
xists-0.9.0.tar.gz 177.0 kB Without provenance Details for xists-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xists 0.9.0
File Interpreter ABI Platform Actions
xists-0.9.0-py3-none-any.whl Python 3 none any Details for xists-0.9.0-py3-none-any.whl

Total release size: 398.1 kB

Release files / xists-0.9.0.tar.gz

Download URL xists-0.9.0.tar.gz
Size 177.0 kB
Tags Source
SHA-256 checksum
How to use checksums
daf4c3cb4650b0e78f24fc093d2c2b06e4c6f934f2e004dc5802e6cc6449fdb5
BLAKE2b-256 checksum
How to use checksums
ff5f175620719c3e5cf009c61de6765334d1c8fef0f404fe13f1df5621031758
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Release files / xists-0.9.0-py3-none-any.whl

Download URL xists-0.9.0-py3-none-any.whl
Size 221.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
43f74029edbd16b3eb453910dbc9c15eca485730e80d54b2e6a7a3a1d6707b7d
BLAKE2b-256 checksum
How to use checksums
6c44d2cfa2909931bc952362a147ed4a4ba6460ed7d7b2a7cb86755acfe30e33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Security for xists 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page