Overview

contox_scan walks a local codebase directory and extracts structured information about the project, then pushes approximately 15-20 hierarchical sub-contexts to the project brain via the populate API. This gives the AI an instant understanding of the project structure without reading every source file.

The scan extracts:

• API routes and endpoints — HTTP methods and paths
• Pages — Frontend page routes
• Components — React/UI components
• Libraries — Utility modules and their exports
• Hooks — Custom React hooks
• Stores — State management modules
• Dependencies — Package dependencies from package.json
• Key documentation files — README, CHANGELOG, and other important docs

Parameters

Return value

Returns a formatted summary including:

• File and directory counts
• API endpoint and page counts
• Component, library, hook, and store counts
• Exported function/type counts
• Key documentation file counts
• Sub-context count and token estimates
• Populate results (created, updated, unchanged, errors) unless dryRun is true

Usage examples

Scanning the current project

User: Scan my codebase

Claude calls: contox_scan()

Response:
Scan completed for: /Users/dev/my-project
- Files: 234, Directories: 42
- API endpoints: 15, Pages: 8
- Components: 45, Libraries: 12, Hooks: 7, Stores: 3
- Exported functions/types: 156
- Key documentation files: 4
- Sub-contexts generated: 18 (~6200 tokens)

Populate results:
- Created: 18
- Updated: 0
- Unchanged: 0

Dry run to preview

Claude calls: contox_scan({ dryRun: true })

Response:
Scan completed for: /Users/dev/my-project
...
Sub-contexts (dry run — not pushed):
  - API Routes [root/scan/api-routes] (~450 tokens)
  - Pages [root/scan/pages] (~320 tokens)
  - Components [root/scan/components] (~1100 tokens)
  ...

Scanning a different directory

Claude calls: contox_scan({ directory: "/Users/dev/other-project" })

Notes

• The directory must contain either a .git directory or a package.json file. This is a security check to prevent scanning arbitrary directories.
• The scan respects .gitignore-like exclusions: node_modules, .next, dist, build, and similar directories are skipped.
• Files larger than 32KB are skipped to keep the scan fast.
• Sub-contexts are pushed via the populate API with contextType: "reference" and tier: 2 by default.
• Sub-contexts are created in draft state. Use contox_approve to make them visible in the brain.
• Results use content-hash deduplication — re-scanning a project will only update contexts whose content has actually changed.
• Sub-contexts are pushed in batches of 50, sorted depth-first to ensure parent contexts are created before their children.