ck:scout

Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.

Arguments

• Default: Scout using built-in Explore subagents in parallel (./references/internal-scouting.md)
• ext: Scout using external Gemini/OpenCode CLI tools in parallel (./references/external-scouting.md)

When to Use

• Beginning work on feature spanning multiple directories
• User mentions needing to "find", "locate", or "search for" files
• Starting debugging session requiring file relationships understanding
• User asks about project structure or where functionality lives
• Before changes that might affect multiple codebase parts

Quick Start

1. Analyze user prompt to identify search targets
2. Use a wide range of Grep and Glob patterns to find relevant files and estimate scale of the codebase
3. Spawn parallel agents with divided directories when available, or run parallel file reads/searches
4. Collect results into concise report

Configuration

Read from .codex/.ck.json:

• gemini.model - Gemini model (default: gemini-3-flash-preview)

Workflow

1. Analyze Task

• Parse user prompt for search targets
• Identify key directories, patterns, file types, lines of code
• Determine optimal SCALE value of subagents to spawn

2. Divide and Conquer

• Split codebase into logical segments per agent
• Assign each agent specific directories or patterns
• Ensure no overlap, maximize coverage

3. Register Scout Tasks

• Skip if: Agent count ≤ 2 (overhead exceeds benefit)
• If task tools exist, check existing scout tasks first
• If not found, create one tracked task per agent with scope metadata
• See references/task-management-scouting.md for patterns and examples

4. Spawn Parallel Agents

Load appropriate reference based on decision tree:

• Internal (Default): references/internal-scouting.md (Explore subagents)
• External: references/external-scouting.md (Gemini/OpenCode)

Notes:

• Mark each tracked task in_progress before spawning its agent when task tools exist
• Prompt detailed instructions for each subagent with exact directories or files it should read
• Remember that each subagent has less than 200K tokens of context window
• Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
• Each subagent must return a detailed summary report to a main agent

5. Collect Results

• Timeout: 3 minutes per agent (skip non-responders)
• Mark completed tracked tasks; log timed-out agents in report
• Aggregate findings into single report
• List unresolved questions at end

Report Format

# Scout Report

## Relevant Files
- `path/to/file.ts` - Brief description
- ...

## Unresolved Questions
- Any gaps in findings

References

• references/internal-scouting.md - Using Explore subagents
• references/external-scouting.md - Using Gemini/OpenCode CLI
• references/task-management-scouting.md - Task-tracking patterns for scout coordination