Install the SDK

Installation

npm install @hitheo/sdk

yarn add @hitheo/sdk

pnpm add @hitheo/sdk

Requirements: Node.js 18+ with native fetch support.

Initialize the Client

import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
  // Optional:
  // baseUrl: "https://www.hitheo.ai",   // default (canonical `www` host)
  // timeoutMs: 30_000,                  // default
  // maxRetries: 2,                      // default — retries on 429/5xx
});

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	required	Your `theo_sk_...` API key
`baseUrl`	`string`	`https://www.hitheo.ai`	API base URL (always target `www` — the apex redirects and some HTTP clients strip the `Authorization` header on 3xx)
`timeoutMs`	`number`	`30000`	Request timeout in milliseconds
`maxRetries`	`number`	`2`	Max retry attempts on 429/5xx errors

Retry Behavior

The SDK automatically retries on:

429 Too Many Requests — respects the Retry-After header
5xx Server Errors — exponential backoff (1s, 2s, 4s, max 8s)

Client errors (400, 401, 403, 404) are not retried.

Also Available

CLI

The SDK includes a CLI for terminal usage:

npm install -g @hitheo/sdk
theo init        # Set up Theo in a project
theo status      # Check connection + health (probes both apex and www)
theo verify      # Machine-readable JSON diagnostic (CI-friendly)
theo complete "What is quantum computing?"

See the CLI Reference for all commands.

MCP Server — IDE Integration

Use Theo inside Cursor, Claude Code, Warp, Windsurf, and VS Code via MCP: First, set your API key as an environment variable:

export THEO_API_KEY=theo_sk_...

Then pick your IDE:

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide cursor

Run this in your terminal:

claude mcp add theo npx -y @hitheo/mcp

Or run:

theo mcp install --ide claude-code

Add to .warp/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide warp

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide windsurf

Add to .vscode/mcp.json in your project root:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}

Or run:

theo mcp install --ide vscode

Auto-detect and configure all installed IDEs at once:

npm install -g @hitheo/sdk
theo init

This detects Cursor, Claude Code, Warp, Windsurf, and VS Code, writes the correct config for each, and creates a theo.config.json for project-level settings.

Restart your IDE after adding the config.

First Completion

Hello World

Getting Started

Quickstart

Core Concepts

Troubleshooting

Skills

Guides

MCP Server

Playground

Dashboard

Security & Compliance

Changelog

Installation

Initialize the Client

Configuration Options

Retry Behavior

Also Available

CLI

MCP Server — IDE Integration

​Installation

​Initialize the Client

​Configuration Options

​Retry Behavior

​Also Available

​CLI

​MCP Server — IDE Integration

Installation

Initialize the Client

Configuration Options

Retry Behavior

Also Available

CLI

MCP Server — IDE Integration