Code Search docs

Get started

Quickstart

You can run your first search in about a minute. There is nothing to install.

1. Sign in with GitHub. Click Sign in with GitHub and approve Code Search on GitHub's page. It asks for no permissions beyond public data.
2. Describe the project. You land on the dashboard's search page. Type what you need, for example self-hosted kanban board with markdown support, and press Search.
3. Open a result. Results are ranked by stars. Click a row for the description, topics, licence and links to GitHub and the project's website.
4. Optional: connect an agent. Create an API key under API keys and paste the snippet for your agent from Agent setup.

Typed a search on the home page before signing in? Code Search keeps it and runs it as soon as you land on the dashboard.

Search in the dashboard

The dashboard at /app/ is the no-setup way to use Code Search. It calls the same search as the API, with your own GitHub quota.

Below the box, Code Search says how many projects matched, which rule matched them, which words it treated as key terms, and how many GitHub searches you have left this minute.

Writing good queries

Describe the project, not yourself. Words like I need, open source or that I can are dropped anyway.

• Name the job. “convert pdf tables to excel” beats “pdf tool”.
• Add a language or style as a descriptive word. “terminal file manager in rust” keeps Rust as a tie-breaker instead of a hard filter. Use the Language filter for a hard filter.
• Use qualifiers when you know them. license:mit, topic:cli, user:NAME and pushed:>2025-01-01 pass straight to GitHub.
• Raise the star floor for crowded topics. “machine learning time series forecasting” with 1,000+ stars returns established libraries only.

stars:, sort: and in: qualifiers are ignored, because Code Search sets them itself.

Reading the results

Each result shows the repository, stars, main language, licence and an activity label based on the last push.

The match rule tells you how strict the search had to be. See Response for the four rules.

Agents

API keys

Agents and scripts authenticate with an API key. Create keys in the dashboard under API keys.

• Give each agent or script its own key, so you can revoke one without touching the rest.
• A key is shown once, when you create it. Code Search stores only its SHA-256 hash and cannot show it again.
• Every key searches on your GitHub quota of 30 searches a minute.
• Revoked keys stop working within a minute.

Send the key on every request as Authorization: Bearer <key>.

MCP server

One Streamable HTTP endpoint for every MCP client:

https://codesearch.amplfyd.com/mcp

It speaks MCP 2026-07-28 (stateless, server/discover) and the earlier 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 revisions with the initialize handshake, so current and older clients both work. The endpoint accepts API keys only, not browser cookies.

Both tools are read-only. Results come back as compact text for the model plus structuredContent with the full JSON. Errors such as a rate limit come back with isError: true and say how long to wait. Suggested use: search first, then read the README of the best two or three results before recommending one.

Agent setup

Pick your agent. Replace the placeholder with a key from the dashboard; the dashboard's Connect page fills it in for you.

Example prompts

Once connected, ask in plain words and mention the tool so the agent uses it:

• “Use code-search to find a well-maintained Rust crate for parsing TOML, read the READMEs of the top three and recommend one.”
• “Before you write a date picker, check with code-search whether a popular React component already does it.”
• “Find self-hosted alternatives to Notion with at least 1,000 stars and compare their licences.”
• “Search GitHub for an MIT-licensed Python package that turns PDF tables into Excel and show how to install it.”

API reference

REST API

Every endpoint takes Authorization: Bearer <key>, answers JSON and allows cross-origin calls. Each response carries an X-Request-Id; include it when reporting a problem.

curl -s -H "Authorization: Bearer $CODE_SEARCH_KEY" \
  "https://codesearch.amplfyd.com/v1/search?q=terminal+file+manager+in+rust&min_stars=500"

Search parameters

Response

matchLevel says how the results matched. Code Search first requires every word. Only when fewer than ten projects match does it loosen, stopping at the strictest rule that still finds five.

{
  "query": { "input": "terminal file manager in rust", "keyTerms": ["terminal", "file", "manager"],
             "descriptiveWords": ["rust"], "minStars": 500, "ignored": [], "notes": [] },
  "mode": "broad", "matchLevel": "key_terms_plus",
  "total": 3, "page": 1, "perPage": 20, "hasMore": false, "cached": false,
  "rateLimit": { "limit": 30, "remaining": 27, "reset": 1793766986 },
  "items": [
    { "name": "sxyazi/yazi", "url": "https://github.com/sxyazi/yazi", "stars": 43212,
      "language": "Rust", "license": "MIT", "topics": ["cli", "file-explorer"],
      "description": "Blazing fast terminal file manager written in Rust, based on async I/O.",
      "homepage": "https://yazi-rs.github.io", "archived": false, "forks": 1100,
      "openIssues": 50, "pushedAt": "2026-11-03T10:00:00Z" }
  ],
  "requestId": "8f2c…"
}

rateLimit mirrors GitHub's x-ratelimit-* headers for your token. It is null when the answer came from cache, because no GitHub call was made.

README endpoint

GET /v1/repos/sxyazi/yazi/readme?max_chars=6000

{ "repo": "sxyazi/yazi", "url": "https://github.com/sxyazi/yazi#readme",
  "text": "## Yazi …", "truncated": true, "totalChars": 14820, "requestId": "…" }

READMEs are cached for an hour. A missing README answers 404 with not_found. README reads use GitHub's general REST quota (5,000 an hour), not the search quota.

Errors

Errors are JSON: { "error": "…", "code": "…", "requestId": "…" }, with Retry-After when waiting helps.

Limits

GitHub rate limits

Code Search runs on GitHub's REST API, so GitHub's limits apply. These are GitHub's published numbers, checked on 4 November 2026.

How GitHub reports it

Every GitHub response carries x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset (UTC epoch seconds) and x-ratelimit-resource (for searches, search). Over a limit, GitHub answers 403 or 429. GitHub asks clients to wait until x-ratelimit-reset, or for retry-after seconds when that header is present, and warns that integrations which keep calling while limited can be banned.

What Code Search does about it

• Your own quota. Each user signs in with their own GitHub account, so searches use that user's 30 a minute. Users never share a limit.
• Few calls per search. A search costs one GitHub call when ten or more projects match every word, and at most four when it has to widen.
• Cache and coalescing. Identical searches within ten minutes are answered from cache without touching your quota, and identical searches arriving at the same moment share one GitHub call.
• Honest back-off. When GitHub says stop, Code Search answers 429 rate_limited with Retry-After set from GitHub's reset time. It never retries in a loop on your behalf.
• Graceful widening. If the strict pass found results but a widening call hits the limit, you get the strict results instead of an error.

In practice that means roughly 7 to 30 fresh searches a minute per user, depending on how many need widening, plus unlimited repeats from cache.

Sources: REST API endpoints for search, Rate limits for the REST API.

Code Search limits

• 120 requests a minute per account, across REST and MCP together. Over that you get 429 too_many_requests.
• Queries up to 500 characters; per_page up to 50.
• README text from 200 to 20,000 characters per call.
• Keyword-stuffed spam (descriptions over 1,000 characters) is removed from every result.

Caching

Searches are cached for ten minutes and READMEs for an hour, shared across users, first in the Worker's memory and then in Cloudflare's edge cache. Cached answers say "cached": true and cost no GitHub quota. Responses carry Server-Timing so you can see where time went.

Account

Usage analytics

The dashboard's Usage tab shows when and how many times your keys called Code Search, so you can see which agent is busy, spot failures and check how close you run to GitHub's limit.

Filter by key from the menu, or open a key's usage from its 7-day spark on the API keys tab. Counts are stored per key and hour and kept for 90 days. The text of your searches is never stored.

Security and privacy

• The GitHub app requests no scopes, so tokens can read public data only.
• GitHub tokens are stored encrypted with AES-256-GCM. Sessions and API keys are stored only as SHA-256 hashes.
• Sign-in is protected by an OAuth state check; cookies are HttpOnly, SameSite=Lax and __Host- prefixed.
• The MCP endpoint accepts API keys only and rejects foreign Origin headers.
• Pages run under a strict Content-Security-Policy and never render API data as HTML.

More in the privacy notice.

Delete your account

Open Account in the dashboard and choose Delete account. Code Search removes your keys, sessions and stored token and revokes its access to your GitHub account in the same step. Agents using your keys stop working at once.

To pause access without deleting anything, revoke Code Search in your GitHub settings under Applications.

For machines

/openapi.json describes the REST API in OpenAPI 3.1, and /llms.txt explains Code Search to a language model in plain text.