CLAUDE.md — Gajesh2007/open-deep-research

Open Deep Research with AI SDK

6/19/2026 · 15 viewsCLAUDE.md

← Browse

Open Deep Research - TypeScript

Project Description

Open Deep Research is a configurable, fully open-source deep research agent built with TypeScript, Bun, and AI SDK v6. It works across multiple model providers via Vercel AI Gateway, uses Exa AI for search, and supports MCP (Model Context Protocol) servers for extended capabilities.

Repository Structure

Root Directory

  • package.json - Bun workspace root configuration
  • tsconfig.base.json - Shared TypeScript configuration
  • biome.json - Biome linter/formatter configuration
  • bunfig.toml - Bun configuration
  • .env.example - Environment variables template

Packages (packages/)

Core (packages/core/)

Main research agent implementation:

  • src/agents/ - Agent implementations (deep-researcher, supervisor, researcher)
  • src/tools/ - Tool definitions (exa-search, think-tool, conduct-research)
  • src/prompts/ - All prompt templates
  • src/state/ - TypeScript interfaces for agent state
  • src/config/ - Zod schemas and configuration
  • src/mcp/ - MCP client integration with AI SDK
  • src/utils/ - Token limits, message helpers

Shared (packages/shared/)

Shared types and constants:

  • src/types/ - TypeScript interfaces
  • src/constants/ - Default models, limits, tool names

Eval (packages/eval/)

Evaluation framework:

  • src/evaluators/ - 6 evaluators using generateObject
  • src/prompts/ - Evaluation prompts
  • src/runner.ts - Evaluation runner

Apps (apps/)

CLI (apps/cli/)

Command-line interface for running research

API (apps/api/)

HTTP API server (Hono)

Examples (examples/)

Research output examples (arxiv, pubmed, inference-market)

Key Technologies

  • Runtime: Bun
  • AI Framework: AI SDK v6 (beta) with generateText, generateObject, tool()
  • Model Routing: Vercel AI Gateway (format: provider/model-name)
  • Default Model: openai/gpt-5.2
  • Search: Exa AI
  • Validation: Zod schemas
  • MCP: @ai-sdk/mcp for Model Context Protocol integration

Development Commands

bun install          # Install dependencies
bun run dev          # Start development
bun run build        # Build all packages
bun run typecheck    # Type check all packages
bun run lint         # Lint with Biome
bun run lint:fix     # Fix lint issues

Running the CLI

bun run apps/cli/src/index.ts "Your research question"

Configuration

All settings configurable via:

  • Environment variables (.env file)
  • ResearchConfig object passed to runDeepResearcher()

Key environment variables:

  • AI_GATEWAY_URL - Vercel AI Gateway URL
  • EXA_API_KEY - Exa AI API key for search

Architecture

Hierarchical agent pattern:

  1. Deep Researcher - Main orchestrator (clarification, brief, final report)
  2. Supervisor - Delegates research topics to researchers in parallel
  3. Researcher - Executes searches and compresses findings

The supervisor uses stepCountIs(1) to intercept ConductResearch calls and spawn researcher subgraphs. Researchers execute multiple tool calls per API call for efficiency.

Source: Gajesh2007/open-deep-research · 3★ Repo: Open Deep Research with AI SDK