Quickstart

Get th0th running with semantic search in under 5 minutes

Overview

This guide will get you from zero to a working th0th instance with semantic search capabilities in under 5 minutes.

This quickstart uses Ollama for 100% offline operation with zero API costs.

Prerequisites

Before starting, ensure you have:

• Bun (v1.2.0 or higher) - Install Bun
• Node.js (v18 or higher)
• Git
• Curl (for verification)

Ollama will be automatically installed by the setup script if not already present.

Quick Start

Follow these steps to get th0th running:

1. Clone and Install

   Clone the repository and install dependencies:

   git clone <repo-url>
   cd th0th
   bun install
   

   This installs all packages in the monorepo workspace.

2. Run Setup Script

   The setup script configures th0th for 100% offline operation:

   ./scripts/setup-local-first.sh
   

   This script will:

   • Install/start Ollama (if not already running)
   • Pull the bge-m3 embedding model (1024 dimensions)
   • Create config file at ~/.config/th0th/config.json
   • Create .env file with default settings
   • Set up data directory at ~/.rlm

   The script is smart about existing installations. It detects Ollama on Windows hosts (WSL), remote instances, and local installations.

3. Build and Start

   Build the project and start the API server:

   bun run build
   bun run start:api
   

   The API will start on port 3333.

4. Verify Installation

   Check that th0th is running:

   curl http://localhost:3333/health
   

   You should see a health check response indicating the service is ready.

Your First Search

Now let’s index a project and perform a semantic search.

1. Index a Project

   Point th0th at a codebase to index:

   curl -X POST http://localhost:3333/api/v1/project/index \
     -H "Content-Type: application/json" \
     -d '{
       "projectPath": "/home/user/my-project",
       "projectId": "my-project"
     }'
   

   Indexing runs in the background. The response includes a jobId for tracking progress.

   Response:

   {
     "success": true,
     "jobId": "550e8400-e29b-41d4-a716-446655440000",
     "status": "indexing"
   }
   
2. Check Index Status

   Monitor the indexing progress:

   curl http://localhost:3333/api/v1/project/index/status/550e8400-e29b-41d4-a716-446655440000
   

   Wait until status is "completed".

3. Search Your Code

   Perform a semantic search using natural language:

   curl -X POST http://localhost:3333/api/v1/search/project \
     -H "Content-Type: application/json" \
     -d '{
       "query": "authentication middleware",
       "projectId": "my-project",
       "maxResults": 5
     }'
   

   Response:

   {
     "success": true,
     "results": [
       {
         "filePath": "src/middleware/auth.ts",
         "score": 0.89,
         "preview": "export const authenticateUser = ...",
         "lineStart": 15,
         "lineEnd": 42
       }
     ],
     "totalResults": 5,
     "searchTime": "127ms"
   }
   

Use with OpenCode

Integrate th0th with OpenCode for AI-assisted development.

Via MCP Package

{
  "mcpServers": {
    "th0th": {
      "type": "local",
      "command": ["bunx", "@th0th-ai/mcp-client"],
      "env": {
        "TH0TH_API_URL": "http://localhost:3333"
      },
      "enabled": true
    }
  }
}

Add this configuration to ~/.config/opencode/opencode.json

Try the MCP Tools

Once integrated with OpenCode, you have access to all th0th tools:

Index a Project

// Tool: th0th_index
{
  "projectPath": "/home/user/my-app",
  "projectId": "my-app",
  "forceReindex": false,
  "warmCache": true
}

Search Code

// Tool: th0th_search
{
  "query": "database connection pooling",
  "projectId": "my-app",
  "maxResults": 10,
  "responseMode": "summary"  // Saves 70% tokens
}

Compress Context

// Tool: th0th_compress
{
  "content": "<large file content>",
  "strategy": "code_structure",
  "targetRatio": 0.7  // 70% reduction
}

Store Memory

// Tool: th0th_remember
{
  "content": "User prefers React functional components with hooks",
  "type": "preference",
  "projectId": "my-app",
  "importance": 0.8
}

Recall Memory

// Tool: th0th_recall
{
  "query": "coding preferences",
  "projectId": "my-app",
  "types": ["preference", "pattern"],
  "limit": 5
}

Development Mode

For active development with hot reload:

API Server

bun run dev:api

Development mode includes verbose logging and may impact performance.

Verify Your Setup

Check that everything is working:

1. Check Ollama

   Verify Ollama is running and models are available:

   curl http://localhost:11434/api/tags
   

   You should see bge-m3 in the models list.

2. Check API Health

   Verify the API is responding:

   curl http://localhost:3333/health
   
3. Check Configuration

   View your current configuration:

   npx @th0th-ai/mcp-client --config-show
   

   Output:

   {
     "embedding": {
       "provider": "ollama",
       "model": "bge-m3",
       "baseURL": "http://localhost:11434",
       "dimensions": 768
     },
     "compression": {
       "enabled": true,
       "strategy": "code_structure"
     }
   }
   
4. View Swagger Docs

   Explore the API documentation:

   open http://localhost:3333/swagger
   

   The interactive API docs let you test all endpoints.

Common Commands

Here are the most frequently used commands:

Command	Description
bun run build	Build all packages
bun run dev:api	Start API with hot reload
bun run start:api	Start API (production)
bun run test	Run tests
bun run lint	Lint code
bun run type-check	Type checking

Configuration Paths

th0th stores configuration and data in standard locations:

• Config: ~/.config/th0th/config.json
• Data: ~/.rlm/
• Environment: <project-root>/.env

Use npx @th0th-ai/mcp-client --config-path to see your config file location.

Next Steps

Installation Guide

Detailed setup for Docker, WSL, and production environments

OpenCode Integration

Complete guide to using th0th with OpenCode

Configuration

Switch to Mistral or OpenAI embeddings

API Reference

Complete API documentation

Troubleshooting

If you encounter issues:

1. Ollama Not Running

   Start Ollama manually:

   ollama serve
   
2. Port Already in Use

   Change the API port in .env:

   TH0TH_API_PORT=3334
   
3. Indexing Fails

   Check that the project path exists and is readable:

   ls -la /path/to/project
   
4. Check Logs

   Enable debug logging in .env:

   LOG_LEVEL=debug
   

For more help, see Troubleshooting.