Monitoring Indexing

After you add a repository, Superpositional starts indexing it immediately. This page explains what happens during indexing and how to monitor progress.

Pipeline stages

Each indexing run goes through two main stages:

Extraction

Superpositional clones your repository and analyses the code. It identifies entities (functions, classes, files, modules), maps the relationships between them (calls, imports, dependencies), and prepares the data for indexing. Non-code files like READMEs and configuration files are also processed.

Indexing

The extracted entities, relationships, and content are written to Superpositional's internal datastore. This includes generating the data needed for semantic search — so you can later query your codebase by meaning, not just exact keywords. Once this stage completes, the repository is fully indexed and ready to query.

For push-triggered flows (code pushed to the default branch), a third stage may follow:

Reasoning (conditional)

If the push triggers downstream actions — such as checking whether existing documents are now stale — a reasoning stage runs after indexing. This is automatic and doesn't require any action from you.

Tracking progress

You can monitor indexing in two places:

Repo cards (Repos page)

Each repository card on the Repos page shows a status badge:

• Pending — queued for indexing, not yet started.
• Indexing — actively being indexed. A progress bar and status message show the current stage and how far along it is.
• Ready — indexing complete. The repository is fully indexed and queryable.
• Error — indexing failed. The card shows what went wrong.

During indexing, the card updates in real time with progress messages and a percentage indicator.

Flows page

The Flows page shows all pipeline runs across your organisation. Each flow shows:

• What triggered it (push, PR, issue, etc.)
• Which repository it's for
• The current stage and status
• Timestamps and duration

You can use the Flows page to see the full history of indexing runs, not just the current one.

What to expect

Indexing time depends on repository size. Small repositories typically finish in under a minute. Larger repositories take longer — the extraction stage scales with the number of files, and the indexing stage scales with the amount of content.

After the initial full index, subsequent push-triggered re-indexing is incremental. Only the changes from the push are processed, so re-indexing is significantly faster than the initial run.

If indexing fails

If a repository fails to index, the repo card shows an Error status. Common causes:

• Access issues. The GitHub App may have lost access to the repository (permissions changed, app uninstalled). Superpositional shows a prompt to reconnect.
• Transient errors. Network issues or temporary service problems. Try re-indexing from the repo card menu (three-dot icon → Re-index).

The Flows page provides more detail on what stage failed and the error message.

You don't need to wait

Indexing runs in the background. You can add more repositories, explore the rest of the product, or close the browser entirely. Indexing completes whether you're watching or not. When it finishes, the repo card updates to Ready.