Give spawned AI agents instant project context — eliminate the discovery tax.
╭─────────────────────────────────────────────────────────────╮
│ ░░▄▀█ █░░ █▀█ █▀▀ Context ▄▀█ █▀▄ █░█ █▀▀ █▀█ │
│ █▄▀░░ █▄▄ █▄▄ ██▄ Pilot █▀█ █▄▀ █▀▄ ██▄ █▀▀ │
│ │
│ ▄▀█ █░█ █▀▀ Spawn agents that already know the code │
│ █▀█ █▀▄ ██▄ No more wasting tokens on discovery │
╰─────────────────────────────────────────────────────────────╯
Every time you spawn an AI agent (code review, exploration, debugging), it starts with zero knowledge of your codebase. It must:
- List directories to discover structure
- Read every source file to understand what each module does
- Guess relationships between modules
- Figure out entry points, data flows, conventions
This "discovery phase" consumes 30-80% of the agent's token budget — tokens spent re-learning what you already know.
ContextPilot generates a structured context briefing — a single Markdown document that captures everything an agent needs to orient itself. Spawned agents read it once and go straight to work.
Without ContextPilot: With ContextPilot:
agent.spawn() agent.spawn(
→ list dirs briefing = read("context-brief.md")
→ read 15 files → reads target files directly
→ grep for imports → performs the actual task
→ guess architecture (skips discovery entirely)
→ finally starts work )
Token cost: ~80k Token cost: ~3k briefing + targeted reads
python3 -m pip install git+https://github.com/context-pilot/context-pilot.git
contextpilot scan /path/to/project --out context-brief.mdOr run the scanner directly:
python3 scripts/scan.py /path/to/project --out context-brief.mdOutput:
Scanned 15 source files (2,400 lines) + 8 tests
Language: python
Briefing written to context-brief.md (6,100 chars)
The generated context-brief.md contains:
- Module map — every file, its size, and what it does (from docstrings)
- Dependency graph — which modules import which (Mermaid diagram)
- Data flows — traced entry points through internal call chains
- Config & env vars — extracted from source
- Test coverage map — what's tested and how
When spawning any agent, prepend the briefing to its task prompt:
Read this project context first, then proceed with your task:
[contents of context-brief.md]
---
Your task: review the code for bugs and performance issues.
The agent arrives oriented — no discovery phase needed.
Scanning a computer vision project produces:
# Project Context Briefing
## Overview
- Language: python (15 source files, 2,400 lines)
- Entry points: pipeline.py (render_clip), m0.py (two_camera_clip)
## Module Map
| Path | Lines | Responsibility |
|------|-------|---------------|
| pipeline.py | 267 | Image → MoGe-2 depth → Gaussian splats → gsplat render
| multiview.py | 366 | Multi-view blending, camera arcs, compositing
## Dependency Graph
```mermaid
graph TD
m0 --> graphics, ground, hull, meshrender, multiview, people, pipeline, sync
multiview --> pipeline, trajectory
story --> graphics, ground, m0, pipeline- GPU compute: PyTorch CUDA + gsplat rasterisation
- Fallback: OpenGL (moderngl) for Mac GPU, CPU painter's algorithm
## How It Works
The scanner is **heuristic-driven, not model-dependent** — no LLM needed:
| Step | Technique | What It Produces |
|------|-----------|-----------------|
| File discovery | Extension + pattern matching | Source vs. test classification |
| Language detection | Manifest files (`pyproject.toml`, `package.json`) | Python, JS/TS, Go, Rust |
| Module descriptions | AST docstring extraction (Python) / comment blocks (other) | One-line responsibility per file |
| Dependency graph | AST import analysis, relative vs. absolute resolution | Internal module dependency DAG |
| CLI wrapper detection | Modules importing >50% of package | Excluded from graph (noise) |
| Config extraction | Regex for `os.environ`, `argparse` patterns | Environment variables & CLI flags |
| Data flow tracing | Entry point detection + internal call graph | Call chains between modules |
## Supported Languages
| Language | Status | Features |
|----------|--------|----------|
| Python | ✅ Full | AST analysis, imports, docstrings, config vars, call chains |
| JavaScript/TypeScript | 🚧 Partial | File discovery, line counts, docstrings |
| Go | 🚧 Partial | File discovery, line counts |
| Rust | 🔜 Planned | — |
## Token Savings
Measured across 50+ agent spawns on projects of varying size:
| Project Size | Discovery tokens (without) | Briefing read (with) | **Saved per spawn** |
|-------------|--------------------------|---------------------|--------------------|
| Small (5 files) | ~20k | ~2k | **~15k** |
| Medium (15 files) | ~60k | ~3k | **~45-55k** |
| Large (40+ files) | ~120k | ~5k | **~90-110k** |
At $15/M input tokens (GPT-4o), a medium project saves **~$0.75 per agent spawn**. At scale (10+ spawns/day), that's meaningful.
## As a Copilot Skill
Copy `skills/context-pilot.md` into your project's skills directory. The skill:
1. Auto-triggers when you ask for code reviews or spawn agents
2. Checks for an existing briefing, generates one if missing
3. Injects it into spawned agent prompts
## FAQ
**Q: Does the briefing replace reading source code?**
A: No. It replaces *discovery* reads. The agent still reads specific files for detailed review — but it knows exactly which ones and why.
**Q: How often should I re-scan?**
A: After significant changes (new modules, renamed files, architecture shifts). The scanner is fast (~1s for most projects) — run it before important agent tasks.
**Q: Can I customize what gets extracted?**
A: Yes. Edit `scan.py` to add language support, custom patterns, or additional analysis passes. The briefing format is Markdown — fully editable by hand too.
**Q: Does this work with any AI coding assistant?**
A: The `context-brief.md` is just a Markdown file. Any agent that can read it benefits. The skill definition is optimized for Copilot SDK agents.
## License
MIT — use it anywhere, modify freely. The scanner runs locally; your code never leaves your machine.