# RagGo User Guide

## What is RagGo?

RagGo lets AI assistants like Claude search through your documents, code, and API documentation. You add your files, and the AI can instantly find and reference the information it needs.

Everything runs on your own computer — your data stays private and never leaves your machine.

## Before You Start

You need **Python 3.10 or newer** installed on your computer.

- **Windows**: Download from [python.org](https://www.python.org/downloads/). During installation, make sure to check **"Add Python to PATH"**.
- **macOS**: Open Terminal and run: `brew install python@3.11`
- **Linux (Ubuntu/Debian)**: Open Terminal and run: `sudo apt install python3 python3-venv python3-pip`

You also need an internet connection for the first launch (RagGo will download some components automatically).

## Starting RagGo

### Windows
Double-click **raggo-launcher.exe**. That's it.

If something goes wrong, open a command prompt and run **raggo-launcher.exe** from there to see error output.

### macOS
Double-click **RagGo.app**.

The first time you open it, macOS may show a security warning. If so:
1. Right-click on RagGo.app
2. Click "Open"
3. Click "Open" again in the dialog

### Linux
Double-click **raggo.desktop**, or open a terminal in the RagGo folder and run:
```
./start-raggo.sh
```

### First Launch

The very first time you start RagGo, it needs a few minutes to set itself up. This is normal — it's installing the components it needs to work. You only have to wait for this once.

## Using RagGo

Once RagGo is running, open your web browser and go to:

**http://localhost:3235/ui/**

This opens the RagGo dashboard where you can manage everything.

### Dashboard
Your home screen. Shows an overview of your collections, system health, and quick links to common actions.

### Search
Search through your documents and code. You can filter results by language, source, or relevance score.

### Ingestion (Adding Your Files)
This is where you add files for the AI to search through. You can:
- **Upload individual files** — drag and drop or browse for files
- **Add entire folders** — point RagGo at a folder and it will process everything inside

A progress bar shows you how the processing is going. Large files or folders may take a few minutes.

### MCP Connection
Shows you how to connect RagGo to your AI assistant (Claude Desktop, VS Code, etc.). Includes one-click setup buttons that configure the connection for you automatically.

### Metrics
Shows performance statistics — how many searches have been done, response times, and system resource usage.

### Sources
Browse all your ingested sources (logical groupings) with aggregate statistics. Click **Files** on any source to jump to the Documents page filtered to that source, **Search** to search within it, or **Delete** to remove all its vectors.

### Documents
Browse and manage every individual ingested file. Filter by name, source, or type (documents vs code). Sort by name, source, chunk count, or type. Delete individual files you no longer need — all their chunks are removed from the vector database.

### Status
Monitor the health of RagGo's services. If something isn't working, this page will show you what's wrong. You can also view live logs and restart services from here.

## Where Your Files Go

RagGo organises files into folders inside the `data/` directory:

| Folder | What goes here |
|---|---|
| `data/documents/` | Documents you want the AI to search (PDFs, Word docs, text files, etc.) |
| `data/code/` | Source code files |
| `data/resources/` | Reference files the AI can read directly |

You can add files through the web interface or by placing them directly into these folders.

## Connecting to Your AI Assistant

RagGo works with any AI tool that supports MCP (Model Context Protocol). The most common setups are:

### Claude Desktop
1. Open RagGo's web interface
2. Go to the **MCP** page
3. Click the **"Apply to Claude Desktop"** button
4. Restart Claude Desktop

### VS Code (with Claude extension)
1. Open RagGo's web interface
2. Go to the **MCP** page
3. Click the **"Apply to VS Code"** button
4. Reload VS Code

Once connected, your AI assistant can automatically search your documents and code when answering questions.

## Stopping RagGo

- **Windows**: Run `scripts\stop-raggo.ps1`, or open Task Manager and end `raggo.exe`
- **macOS / Linux**: Press `Ctrl+C` in the terminal, or run `scripts/stop-raggo.sh`
- **Any platform**: Open the **Status** page in the web interface and click **Stop All**

## Common Issues

### "Python not found"
Python isn't installed or isn't in your system PATH. See the "Before You Start" section above for installation instructions.

### RagGo won't start
- Make sure no other copy of RagGo is already running
- Try running `raggo-launcher.exe` from a command prompt to see error messages

### Can't open the web interface
- Make sure RagGo has finished starting up (wait for the setup to complete on first run)
- Check that your browser is going to `http://localhost:3235/ui/` (not https)
- If another program is using port 3235, open the `.env` file in a text editor and change `MCP_SERVER_PORT` to a different number

### Search returns no results
- Make sure you've added files first (see "Ingestion" above)
- Check that the files finished processing (look for a green checkmark on the Ingestion page)

### Setup seems stuck
- Check your internet connection (needed for first run)
- Try deleting the `.venv` folder inside the RagGo directory and starting again

### Something else isn't working
Open the **Status** page (`http://localhost:3235/ui/status`) in your browser. It shows the health of each service and live logs that can help identify the problem.

You can also find log files in the `logs/` folder inside the RagGo directory.
