> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracer

> Autonomous agent for searching GitHub repositories without indexing

<Info>
  **Builder Feature** - Tracer is included with Builder, Team, and Business plans. Free plan users can also use Tracer with purchased credits (15 credits per job).
</Info>

## Overview

Tracer is an autonomous agent that searches code on GitHub without requiring you to index repositories first. It delegates tasks to specialized sub-agents — each handling search, reading, or analysis in parallel — to deliver faster, more thorough results than a single-agent approach.

Tracer supports two modes: **Fast** (powered by Claude Haiku for quick lookups) and **Deep** (powered by Claude Opus with 1M context window for thorough investigations).

Use Tracer when you need to quickly search unfamiliar code, find implementation examples, or understand how libraries work internally.

<Frame>
  <iframe src="https://www.youtube.com/embed/FMYq_-alEMY" title="Tracer Demo" className="w-full aspect-video rounded-xl" allowFullScreen />
</Frame>

## Modes

| Mode     | API Value     | Model                    | Best For                                                        |
| -------- | ------------- | ------------------------ | --------------------------------------------------------------- |
| **Fast** | `tracer-fast` | Claude Haiku             | Quick lookups, simple questions, rapid iteration                |
| **Deep** | `tracer-deep` | Claude Opus (1M context) | Thorough investigations, complex codebases, multi-file analysis |

## How It Works

You provide a question, repositories to search, and optionally a mode. Tracer delegates work to specialized sub-agents that operate in parallel:

<Steps>
  <Step title="Plan">
    The coordinator analyzes your query and breaks it into sub-tasks
  </Step>

  <Step title="Explore">
    Sub-agents browse repository structures to understand layouts
  </Step>

  <Step title="Search & Read">
    Sub-agents search and read files concurrently using GitHub's Code Search API
  </Step>

  <Step title="Iterate">
    Follow code paths as results reveal new areas, with sub-agents working in parallel
  </Step>

  <Step title="Synthesize">
    Generate a comprehensive report with file paths and line citations
  </Step>
</Steps>

## Available Tools

Tracer autonomously uses four GitHub tools:

| Tool            | Purpose                                            |
| --------------- | -------------------------------------------------- |
| `github_search` | Code search with qualifiers (`language:`, `path:`) |
| `github_list`   | Browse file tree structure                         |
| `github_read`   | Read file contents with optional line ranges       |
| `github_glob`   | Find files matching glob patterns                  |

## API Usage

### Create a Tracer Job

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/github/tracer \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does the streaming response work in generateText?",
    "repositories": ["vercel/ai"],
    "context": "Focus on the core streaming implementation, not the React hooks.",
    "mode": "tracer-deep"
  }'
```

**Parameters:**

| Parameter      | Type      | Required | Description                                                                                    |
| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------- |
| `query`        | string    | Yes      | Your research question                                                                         |
| `repositories` | string\[] | No       | Repositories to search (owner/repo format)                                                     |
| `context`      | string    | No       | Additional context to guide the agent's focus                                                  |
| `mode`         | string    | No       | `"tracer-fast"` (Haiku) or `"tracer-deep"` (Opus with 1M context). Defaults to `"tracer-deep"` |

**Response:**

```json theme={null}
{
  "job_id": "abc123",
  "session_id": "def456",
  "status": "queued"
}
```

### Stream Results

Subscribe to real-time updates as Tracer works:

```bash theme={null}
curl -N https://apigcp.trynia.ai/v2/github/tracer/{job_id}/stream \
  -H "Authorization: Bearer $NIA_API_KEY"
```

**Event Types:**

| Event           | Description                             |
| --------------- | --------------------------------------- |
| `started`       | Job started with query and repositories |
| `tool_start`    | Tool execution beginning                |
| `tool_complete` | Tool finished with success/failure      |
| `complete`      | Final report ready                      |
| `error`         | Error occurred                          |

### Get Job Status

```bash theme={null}
curl https://apigcp.trynia.ai/v2/github/tracer/{job_id} \
  -H "Authorization: Bearer $NIA_API_KEY"
```

### List Jobs

```bash theme={null}
curl https://apigcp.trynia.ai/v2/github/tracer \
  -H "Authorization: Bearer $NIA_API_KEY"
```

## MCP Integration

Tracer is available as an MCP tool. Once configured, use it in Claude Code, Cursor, or any MCP-compatible agent:

```
"Use Tracer to search the vercel/ai repository and explain how streaming works."
```

## Example Use Cases

<Accordion title="Understanding Library Internals">
  **Query:** "Explain why we're getting this error from Zod and show me the validation logic causing it."

  Tracer searches the Zod repo for error messages, finds the validation functions, reads the implementation, and explains exactly what triggers the error.
</Accordion>

<Accordion title="Finding Implementation Examples">
  **Query:** "Find examples of how to implement cursor-based pagination in GraphQL resolvers."

  Tracer searches multiple repositories, finds pagination implementations, compares approaches, and synthesizes findings.
</Accordion>

<Accordion title="Learning Framework Patterns">
  **Query:** "How does React's useEffect cleanup function work?"

  Tracer navigates the React codebase, finds the hooks implementation, reads the relevant code, and explains the cleanup mechanism.
</Accordion>

## Tracer vs Index-Based Search

| Aspect       | Tracer                                    | Nia Search                        |
| ------------ | ----------------------------------------- | --------------------------------- |
| **Speed**    | Fast mode is quick; Deep mode is thorough | Fastest (pre-indexed)             |
| **Setup**    | None                                      | Requires indexing                 |
| **Coverage** | All public GitHub                         | Only indexed sources              |
| **Best for** | Exploration, one-off queries              | Repeated searches, production use |

**Use Tracer when:**

* Exploring unfamiliar code
* Searching repos you haven't indexed
* Researching across multiple repositories

**Use Nia Search when:**

* Working with familiar codebases
* Need fast, repeated searches
* Want precise control over search scope