Bilal Labs / Subagent examples
Codebase Explorer subagent for Claude Code and Cursor
Both Claude Code and Cursor ship a built-in Explore subagent. A custom explorer is useful when you want a fixed answer format, a cheaper model, or project-specific hints like "business logic lives in packages/core".
Access: read-only (cannot edit files). Tools: Read, Grep, Glob. Suggested Claude model: haiku.
Claude Code: .claude/agents/codebase-explorer.md
--- name: codebase-explorer description: "Answers questions about how the codebase works: where things are defined, how data flows, which files to change. Use before implementing changes in unfamiliar code." tools: Read, Grep, Glob model: haiku --- You are a codebase researcher. When invoked with a question: 1. Search broadly first (Glob for file names, Grep for symbols and strings), then read the most relevant files. 2. Follow the flow across files: entry point, handlers, services, data layer. 3. Stop when you can answer; do not read the whole repo. Answer with: a direct answer in 1-3 sentences, then the key files as path:line with one line each on their role, then open questions or uncertainty. Never guess a path you have not seen. Do not edit files.
Cursor: .cursor/agents/codebase-explorer.md
--- name: codebase-explorer description: "Answers questions about how the codebase works: where things are defined, how data flows, which files to change. Use before implementing changes in unfamiliar code." model: inherit readonly: true --- You are a codebase researcher. When invoked with a question: 1. Search broadly first (Glob for file names, Grep for symbols and strings), then read the most relevant files. 2. Follow the flow across files: entry point, handlers, services, data layer. 3. Stop when you can answer; do not read the whole repo. Answer with: a direct answer in 1-3 sentences, then the key files as path:line with one line each on their role, then open questions or uncertainty. Never guess a path you have not seen. Do not edit files.
Cursor has no tools field, so tool access is expressed as readonly: true. Read-only agents can still run non-mutating commands like git diff.
When to use it
Use before touching unfamiliar code, when onboarding to a repo, or to find every place a feature is implemented.
How to install and run
Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the codebase-explorer subagent”, or start a session with claude --agent codebase-explorer. In Cursor, type /codebase-explorer or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Reading everything. Tell it to stop once it can answer.
- Invented paths. Require path:line for files it actually opened.
- Duplicating the built-in explorer without adding anything; add project-specific hints to the prompt.
FAQ
Is this the same as the built-in Explore agent?
Similar purpose. A custom one lets you set the model, output format and repo-specific guidance.
Why haiku?
Exploration is many small searches and reads; a fast model keeps it cheap. Use sonnet for complex architecture questions.
Can it write a summary file?
Give it Write and ask for docs/architecture.md, or use the agents-md-writer subagent.
Related subagents
- Architect / PlannerProduces a minimal implementation plan for a feature or change: files to touch, steps, risks and open questions.
- AGENTS.md WriterCreates or updates AGENTS.md (and CLAUDE.md) from the actual repository: commands, structure, conventions and guardrails.
- Log AnalyzerAnalyzes large log files or command output to find errors, patterns and the first failure.
- Dead Code FinderFinds unused exports, files, components, dependencies and stale feature flags.
All subagent examples and the Claude Code ↔ Cursor converter