Overview
The Genesis page lets you run and manage AI-powered codebase scans directly from the Contox dashboard. Navigate to Genesis to start a scan, monitor progress, and explore results.
Genesis Scan connects to your GitHub repository, analyzes it across 7 layers using Gemini AI, and writes the findings into your project brain. For a conceptual overview of how Genesis Scan works, see Genesis Scan Concepts.
Starting a scan
Scan card
The Genesis page displays a scan card showing the current state:
- No previous scan -- The card shows a prompt to start your first scan
- Scan in progress -- The card shows the progress stepper and live counters
- Scan completed -- The card shows a summary of the last scan with an option to re-scan
Start dialog
Click Start Scan to open the scan configuration dialog. The dialog presents the following options:
| Option | Description | Default |
|---|---|---|
| Branch | The Git branch to analyze | main |
| File limit | Maximum number of files to include in the scan (slider) | 500 |
| Security audit | Enable OWASP-based vulnerability detection | Off |
| Selective scan | Only analyze files changed since the last scan | On (if a previous scan exists) |
For your first scan, leave selective scan off to get a complete analysis of the codebase. For subsequent scans, selective mode is faster and cheaper since it only processes changed files.
Adjust the file limit slider to control how many files are included. Lower limits reduce scan time and cost but may miss files in larger repositories. The slider shows an estimated time and credit cost as you adjust it.
Click Start to begin the scan. The dialog closes and the progress card appears.
Monitoring progress
Phase stepper
Once a scan starts, the progress card displays a horizontal phase stepper showing the 8 scan phases:
- Fetch tree -- Retrieving the repository structure from GitHub
- Fetch files -- Downloading file contents
- Build chunks -- Splitting files into processable chunks
- Analyze -- Running AI analysis across all 7 layers
- Synthesize -- Aggregating findings into project-level insights
- Security audit -- Running OWASP-based vulnerability checks (if enabled)
- Assemble -- Writing findings to the project brain
- Complete -- Scan finished
The current phase is highlighted. Completed phases show a checkmark. If a phase fails, it displays an error icon with a message.
Progress bar and counters
Below the stepper, live counters track the scan's progress:
| Counter | Description |
|---|---|
| Files | filesProcessed / filesTotal -- number of files downloaded and processed |
| Chunks | chunksProcessed / chunksTotal -- number of chunks analyzed |
| Findings | Running count of findings extracted so far |
| Elapsed time | Time since the scan started |
The progress bar fills based on the current phase's completion percentage. During the analyze phase (the longest), it tracks chunk-by-chunk progress.
Cost and time estimates
Before and during a scan, the dashboard provides estimates:
- Estimated time -- Based on file count and whether security audit is enabled
- Estimated credits -- Token cost based on file count and number of layers
These are estimates. Actual costs depend on file sizes, chunk counts, and AI response lengths.
Canceling a scan
Click Cancel Scan to stop a running scan. Cancellation is not instantaneous -- the current phase completes before the scan stops. Findings already extracted up to the cancellation point are preserved and available in the results.
Viewing results
After a scan completes, the results view replaces the progress card.
Layer tabs
Results are organized by the 7 analysis layers. Each tab shows findings for that layer:
- Product -- Business logic, user flows, feature boundaries
- Architecture -- Tech stack, patterns, structure
- Dependencies -- Packages, versions, usage
- Conventions -- Coding style, naming, organization
- Data Model -- Schemas, types, API contracts
- Entry Points -- Routes, pages, middleware
- Security -- Vulnerabilities and risks (only if security audit was enabled)
Click a tab to view its findings. Each tab shows a count badge with the number of findings in that layer.
Finding cards
Each finding is displayed as an expandable card:
| Element | Description |
|---|---|
| Type badge | The analysis layer (e.g., "Architecture", "Security") |
| Title | A concise summary of the finding |
| Importance | 1 to 5 stars indicating significance |
| File references | Source files that contributed to the finding |
| Content | Full finding details (visible when expanded) |
Click a finding card to expand it and see the full content. Important findings (4-5 stars) are highlighted visually.
Tech stack badges
The results header displays detected technologies as badges (e.g., "Next.js", "TypeScript", "Tailwind CSS", "Appwrite"). These are extracted during the architecture and dependencies analysis layers.
Diff summary for selective scans
When viewing results from a selective scan, a diff summary bar appears at the top:
| Indicator | Description |
|---|---|
| New | Findings that did not exist in the previous scan |
| Updated | Findings that changed compared to the previous scan |
| Removed | Findings from the previous scan that no longer apply |
This helps you understand what changed in your codebase since the last scan.
Re-scanning
Click Re-Scan to start a new scan. By default, the re-scan uses selective mode (only changed files). Toggle off selective mode in the start dialog to run a full re-scan.
Running a selective re-scan after each sprint or major feature branch merge keeps your brain current with minimal cost.
Exporting findings
Export scan findings for use outside Contox:
- Click the Export button in the results view
- Choose a format:
- Markdown -- Human-readable document organized by layer
- JSON -- Machine-readable array of findings with metadata
- The file downloads to your local machine
Exported findings include all metadata: layer, importance, file references, and tech stack tags.
Error handling
If a scan fails, the progress card displays the error message and the phase where the failure occurred. Common issues:
| Error | Cause | Resolution |
|---|---|---|
| GitHub access denied | Repository is private and the GitHub token is invalid or expired | Re-authenticate your GitHub connection in project settings |
| File limit exceeded | Repository contains more files than the configured limit | Increase the file limit slider or use selective scan |
| AI quota exceeded | Insufficient credits for the scan | Purchase additional credits from the billing page |
| Scan timeout | The scan took longer than the maximum allowed time | Reduce file limit or use selective mode |
Next steps
- Genesis Scan Concepts -- How Genesis Scan works under the hood
- V2 Genesis API -- API reference for programmatic access
- Codebase Scanner -- The lightweight CLI alternative