contox scan
Scan your codebase and generate hierarchical sub-contexts that give AI assistants an instant understanding of your project structure. The scanner walks your filesystem, respecting .gitignore-like exclusions, and produces approximately 15-20 structured contexts.
Usage
bash
contox scan [options]
Options
| Flag | Description | Required | Default |
|---|---|---|---|
-d, --dir <directory> | Directory to scan | No | . (current directory) |
--dry-run | Show what would be generated without pushing to the platform | No | false |
-o, --output <file> | Write scan output to a file | No | -- |
--flat | Generate flat (non-hierarchical) output | No | false |
-p, --project <projectId> | Override the project ID | No | from config |
-t, --team <teamId> | Override the team ID | No | from config |
Examples
Scan the current project:
bash
contox scan
Preview what would be generated without pushing:
bash
contox scan --dry-run
Scan a specific directory:
bash
contox scan -d ./packages/api
Save scan output to a file:
bash
contox scan -o scan-results.md --dry-run
Scan with flat output (no hierarchy):
bash
contox scan --flat
What it generates
The scanner analyzes your project and produces sub-contexts covering:
- Project overview -- Stack, statistics, directory structure
- Routes and API endpoints -- Pages, API routes, middleware
- Components -- UI components inventory
- Libraries and utilities -- Shared code, helper functions
- Hooks and stores -- React hooks, state management
- Dependencies -- Package dependencies and their purposes
- Configuration -- Config files, environment setup
- Documentation -- README files, inline docs
Exclusions
The scanner automatically excludes common non-source directories and files:
node_modules,.next,dist,build- Binary files and images
- Files larger than 32KB
- Paths matching
.gitignorerules
Notes
- Run
contox scanafter significant structural changes to your project (new routes, new packages, major refactors) to keep the AI's understanding up to date. - The
--dry-runflag is useful for reviewing what will be generated before pushing to the platform. - Scan results are pushed via the populate API with content-hash deduplication, so running scan multiple times on unchanged code is safe and does not create duplicates.