Claude Code Subagent

Add a deep-explore subagent to Claude Code that explores your code with grepai search, trace and refs instead of plain text search.

grepai can install a Claude Code subagent named deep-explore. It explores code with grepai search, grepai trace and grepai refs, and falls back to Grep and Glob for exact text.

Installation

Run this at the root of your project:

grepai agent-setup --with-subagent

This creates .claude/agents/deep-explore.md. If the file already defines name: deep-explore, grepai leaves it unchanged.

The same command also appends grepai usage instructions to any agent files that already exist in the project (.cursor/rules, .cursorrules, .windsurfrules, CLAUDE.md, .claude/settings.md, GEMINI.md, AGENTS.md). It does not create those files. See the agent-setup reference.

Restart Claude Code so it loads the new subagent.

Why a Subagent?

Claude Code delegates exploration work to subagents. Each subagent runs in its own context, with its own instructions and tool list. A generic exploration subagent knows nothing about grepai, so it searches with plain text tools.

deep-explore comes with grepai instructions built in, so exploration tasks use semantic search and call tracing.

What It Does

Capability	Command	Use it for
Semantic search	`grepai search`	Find code by intent, not exact text
Call graph	`grepai trace callers`, `callees`, `graph`	See who calls a function and what it calls
Property usage	`grepai refs readers`, `writers`	Find where a property or state key is read or written
Standard tools	`Read`, `Grep`, `Glob`	Read files, match exact strings and path patterns

The subagent runs grepai through the Bash tool. Its tool list is Read, Grep, Glob, Bash, and it inherits the model of the main session (model: inherit).

Usage

Claude Code picks a subagent from its description. The deep-explore description covers:

Understanding code architecture
Finding implementations by intent
Analyzing function relationships
Exploring unfamiliar code areas

You can also ask for it by name:

“Use the deep-explore agent to understand the authentication flow”

Subagent vs MCP

	Subagent	MCP
Setup	`grepai agent-setup --with-subagent`	`claude mcp add grepai -- grepai mcp-serve`
How grepai is called	CLI commands through `Bash`	Native MCP tools (`grepai_search`, …)
Who uses it	The `deep-explore` subagent	Any session or agent that has the MCP tools
Agents supported	Claude Code	Any MCP client

You can use both. MCP gives the main session native tools. The subagent makes sure delegated exploration also goes through grepai.

Manual Setup

To write the file yourself, create .claude/agents/deep-explore.md. This is the content agent-setup writes:

---
name: deep-explore
description: Deep codebase exploration using grepai semantic search and call graph tracing. Use this agent for understanding code architecture, finding implementations by intent, analyzing function relationships, and exploring unfamiliar code areas.
tools: Read, Grep, Glob, Bash
model: inherit
---

## Instructions

You are a specialized code exploration agent with access to grepai semantic search and call graph tracing.

### Primary Tools

#### 1. Semantic Search: `grepai search`

Use this to find code by intent and meaning:

```bash
# Use English queries for best results (--compact saves ~80% tokens)
grepai search "authentication flow" --json --compact
grepai search "error handling middleware" --json --compact
grepai search "database connection management" --json --compact
```

#### 2. Call Graph Tracing: `grepai trace`

Use this to understand function relationships and code flow:

```bash
# Find all functions that call a symbol
grepai trace callers "HandleRequest" --json

# Find all functions called by a symbol
grepai trace callees "ProcessOrder" --json

# Build complete call graph
grepai trace graph "ValidateToken" --depth 3 --json
```

#### 3. Property/Data Usage Tracing: `grepai refs`

Use this when the target is a property/state key rather than a function call:

```bash
# Find readers of a property
grepai refs readers "uid" --json

# Find writers of a property
grepai refs writers "uid" --json
```

Use `grepai trace` when you need to:
- Find all callers of a function
- Understand the call hierarchy
- Analyze the impact of changes to a function
- Map dependencies between components

### When to use standard tools

Only fall back to Grep/Glob when:
- You need exact text matching (variable names, imports)
- grepai is not available or returns errors
- You need file path patterns

### Workflow

1. Start with `grepai search` to find relevant code semantically
2. Use `grepai trace` to understand function relationships and call graphs
3. Use `grepai refs` for property/state readers and writers
4. Use `Read` to examine promising files in detail
5. Use Grep only for exact string searches if needed
6. Synthesize findings into a clear summary

Note: grepai search, grepai trace and grepai refs also accept --toon, a more compact output format than --json. You can swap it in if you want to save tokens.

Troubleshooting

Subagent not appearing

Check that the file exists: cat .claude/agents/deep-explore.md.
Check that the YAML frontmatter at the top of the file is valid.
Restart Claude Code.

grepai commands failing in subagent

Check that grepai is on your PATH: which grepai.
Check the index: grepai status.
Run grepai watch to build or update the index. grepai trace and grepai refs also need the symbol index it builds.