Quick start

This page gets you from a fresh clone to a working Claude Desktop connection. Each step names the exact command and what you should see. For the reasoning behind each step, see Installation.

Requirements

Python 3.13 and uv. Any way to create a .venv at the repository root also works, but make setup looks for uv or python3.13.
Node.js 22 or newer and npm.
An Algolia application ID and Admin API key. Without them the backend still starts, but adding a repository returns 503 and /health reports degraded.
A GitHub token (optional but recommended). Without one, GitHub’s low unauthenticated rate limit applies and private repositories can’t be read.
Claude Desktop, for step 5.
curl (used by make start and make health) and jq (used by make health).

You also need a clone of the repository:

git clone https://github.com/ntanwir10/codesage-algolia-challenge.git
cd codesage-algolia-challenge

The five steps

Install.
Terminal window
```
make setup
```
This copies .env.example to backend/.env if it is missing, creates .venv and installs the backend dependencies into it, runs npm ci in frontend/ and generates your CodeSage API key. It stops with Python 3.13 (or uv) is required or Node.js 22 or newer is required if a prerequisite is missing. When it finishes it prints what to edit next, ending with Next: 'make start', then 'make install-claude' for Claude Desktop.

On a first run you also see:
```
Generated a CodeSage API key in backend/.env
Copied it to frontend/.env (restart Vite to pick it up)
Run 'make install-claude' and restart Claude Desktop so Claude uses it.
```
Configure. Open backend/.env and fill in these three values:
backend/.env
```
ALGOLIA_APP_ID=...
ALGOLIA_ADMIN_API_KEY=...
GITHUB_TOKEN=...
```
Leave CODESAGE_API_KEY alone. make setup, make start and make install-claude generate it and keep frontend/.env in sync. Get the Algolia values from your Algolia dashboard under Settings, then API Keys. Create the GitHub token at https://github.com/settings/tokens. See Installation for details.
Run.
Terminal window
```
make start
```
This starts the backend on http://127.0.0.1:8001, waits up to 15 seconds for /health to answer, then starts the dashboard on http://localhost:5173. Keep this terminal open. The backend logs JSON lines; look for Database schema up to date and, if your Algolia values are set, Algolia credentials configured - MCP server ready. Vite then prints its Local URL.

If a backend already answers on port 8001, make start stops with A backend is already running on port 8001. Stop it with 'make stop', or run 'make start-frontend' to use it. If port 5173 is taken, Vite exits instead of choosing another port.
Index a repository. Open http://localhost:5173. In the field with the fixed github.com/ prefix, type owner/repo (for example pmndrs/zustand) or paste a GitHub URL, then press Add Repository. You land on the repository page, which shows progress live. When the badge turns Completed, the repository is searchable. If GitHub or Algolia refuses the repository, the form shows the reason under the field and stays on the Home page. All the messages are in the dashboard guide.

Connect Claude Desktop.

make install-claude                 # add CodeSage to the Claude Desktop config
make install-claude ARGS=--dry-run  # preview first; the key is masked

Expected output of the real run (the backup line appears only if a config file already existed):

backup: /Users/<you>/Library/Application Support/Claude/claude_desktop_config.json.bak-20261026-101500-4242
updated /Users/<you>/Library/Application Support/Claude/claude_desktop_config.json: mcpServers.codesage -> /path/to/codesage-algolia-challenge/mcp_launcher.sh
Restart Claude Desktop to pick it up.

Fully quit and reopen Claude Desktop, and keep the backend running. Then ask Claude something like “Search the zustand repository for where the store is created.”

Verify it works

Check the backend

make health

make health calls /health, then prints the MCP tool names. It needs jq; without it, the target prints Backend not responding even when the backend is up. A healthy answer looks like this:

{
  "status": "healthy",
  "timestamp": "2026-10-26T10:15:00.123456+00:00",
  "version": "1.0.0",
  "components": {
    "database": { "status": "healthy" },
    "algolia": { "status": "healthy" }
  }
}

Then the seven tool names:

[
  "list_repositories",
  "search_code",
  "get_file",
  "list_definitions",
  "analyze_repository",
  "find_patterns",
  "add_repository"
]

`status`	HTTP	Meaning
`healthy`	200	Database and Algolia both answer
`degraded`	200	Algolia is unreachable (`"message": "Algolia is unreachable"`) or not configured (`"status": "not_configured"`)
`unhealthy`	503	The database check failed

The Algolia result is cached for 30 seconds, so a fix may take that long to show.

Open the API docs

Visit http://127.0.0.1:8001/docs for the interactive OpenAPI page. It is hidden when ENVIRONMENT=production.

Ask Claude a first question

In Claude Desktop, ask:

List the repositories in CodeSage.

Claude should call list_repositories and show the repository you added, with status: completed. Then try a search, such as “Search the zustand repository for where the store is created.” If Claude reports an error instead, the message says what to fix; the common ones are in Troubleshooting.

Next steps

Installation in depthCredentials, what make setup does, ports, upgrades and the files CodeSage creates.

Web dashboard guideEvery page, status color and message in the dashboard.

Claude Desktop guideInstaller options, bridge settings, example prompts and error messages.