Scout Agent

Parallel AI file search across large codebases—organized results in <5 minutes.

When to Use

  • Feature work: Find all files spanning multiple directories before implementation
  • Debugging: Locate integration points across unfamiliar codebase areas
  • Onboarding: Map project structure for authentication, payments, or any feature domain
  • Refactoring: Identify affected files before widespread changes

Key Capabilities

CapabilityDescription
Parallel SearchSpawns 1-10 agents (Gemini + OpenCode) to search simultaneously
Smart DivisionSplits codebase into logical sections per agent
Organized OutputGroups results by purpose (Core, API, Tests, Config, Docs)
Timeout Handling3-min limit per agent, uses partial results if needed
DeduplicationRemoves duplicate paths, highlights cross-category files

Common Use Cases

1. Developer starting feature

/scout "locate all authentication-related files" 5

Gets organized list: auth services, middleware, routes, tests, config—ready to start.

2. DevOps debugging production issue

/scout "find Stripe payment webhook and error handling" 4

Finds: payment service, webhook routes, error middleware, logging, integration tests.

3. Junior dev onboarding

/scout "locate database models and migration files" 3

Maps data layer: models, migrations, seeds, schema validation, ORM config.

4. Tech lead planning refactor

/scout "find all API rate limiting and middleware" 6

Discovers: rate limit middleware, Redis integration, route guards, tests, docs.

5. Consultant auditing codebase

/scout "locate security-related files (auth, CORS, validation)" 8

Comprehensive scan: auth guards, input validation, CORS config, security tests.

Pro Tips

Scale Guidelines:

  • 1-3 agents: Small projects (<100 files) or targeted searches → Gemini only
  • 4-6 agents: Medium projects (100-500 files) → Gemini + OpenCode mix
  • 7-10 agents: Large codebases (500+ files) or monorepos → Full parallelization

Search Query Tips:

  • ✅ Specific: "authentication middleware and JWT validation"
  • ❌ Vague: "auth stuff"
  • Include file types: "TypeScript service files for payment"
  • Add constraints: "only in src/api directory"

Reading Results:

  • Don’t skip “Configuration” or “Tests” sections—critical context
  • Files in multiple categories = key integration points
  • Review file counts: 50+ files = query too broad, narrow it down

Performance:

  • Small project (scale=3): 1-2 min, 95% coverage
  • Medium (scale=5): 2-4 min, 90% coverage
  • Large (scale=8): 3-5 min, 85% coverage
  • Monorepo (scale=10): 4-5 min, 75-80% coverage (speed/coverage trade-off)

Troubleshooting:

  • Too many files (100+): Be more specific or reduce scale
  • Missing expected files: Increase scale or check .gitignore exclusions
  • Agent timeout: Partial results still useful, other agents likely found relevant files

Key Takeaway

Scout parallelizes file discovery across multiple AI agents (Gemini + OpenCode), delivering organized, actionable file lists in under 5 minutes—even for massive codebases. No guessing where authentication lives or which files handle payments. Scout maps it, you build it.