Importing an existing project

Import brings an existing repository under Vibeless, and its core flow needs no LLM. The app scans the folder on your machine, shows you what it found, and adds only the items you accept to the project's spec map, the set of context nodes that agents read.

Where to find it

There are 3 ways in:

• Open the New Project dialog (New Project on the Projects tab of the Account panel, New Project... in the project menu in the header, or Ctrl+N). Choose Import Existing Project, enter or Browse to the Repository Path, check the Project Name (filled in from the folder name), and select Import & Scan.
• For a project that already exists, select Import from Repository on the Get Started card of the Dashboard. That card shows while the project has no context nodes. A context node is one entry in the spec map, such as a spec section or a reference document.
• Select Manage Import (or Connect Repository, if no folder is connected yet) on the Repository card in Dashboard → Settings.

All three open the Project Import panel. Creating a project counts against your plan's project limit. When you are at the limit, Import Existing Project is disabled and its note says the project limit is reached.

Import or Vibe Coder

The Vibe Coder's Existing Project path is an LLM chat that uploads a redacted selection of your code and drafts a spec with you, and it needs a paid plan. Import needs no LLM for its core flow and works on the free plan. See Vibe Coder.

What the scan finds

The scan runs locally. Nothing is uploaded at this stage. It walks the repository and records each finding as an item in one of these categories:

A doc is labeled architecture when its path contains "architecture" or "design" as a whole word. It is labeled a specification when its path contains "spec", "specs", "specification", "requirement", or "requirements", also as a whole word. Everything else is documentation.

What the scan skips

• Build output and caches such as node_modules, dist, target, and .next, plus folders listed in your .gitignore.
• Nested git repositories under folders such as vendor/ or third_party/.
• Agent-artifact paths: agent scaffolding such as .claude/tasks/, .claude/reports/, .claude/commands/, .codex/, .superpowers/, docs/superpowers/plans/, and .worktrees/, plus any extras you add in Dashboard → Agents → Agent-artifact paths. .claude/CLAUDE.md is always kept.
• Real environment files. Only the 3 template names above are read. An entry point whose path looks like a secret file, such as a .pem key or a .env file, is recorded by path only, without its contents.

How to use it

1. Start the import from any entry point above. The panel shows "Scanning repository..." and then a count of items found.
2. On Deep Analysis Gaps, select gaps to fill with an LLM, or select Skip Deep Analysis. If the scan found no gaps, select Continue to Review.
3. Choose Developer Review or Guided Review.
4. Accept or reject items, then apply them to the spec map.

Fill gaps with deep analysis

A gap is something the scan looked for and did not find: no architecture documentation, no specification, no docs at all, no database schema, or no environment template. Each gap card shows its category, a description, an estimated token count, and a cost in credits.

Deep analysis (also called Pass 2) is the only step before apply that uses an LLM. It needs a paid plan and uses credits from your budget. On the free plan, selecting a gap shows a message that Pass-2 analysis requires a paid plan, and Analyze Selected stays disabled. On a paid plan, the footer shows the estimate against your remaining credits, and Analyze Selected stays disabled if the estimate is larger.

1. Select one or more gap cards.
2. Select Analyze Selected.
3. Read the Confirm Deep Analysis dialog, which repeats the estimate and your remaining credits, and select Proceed.

For each gap, Vibeless reads the suggested source files and sends a bounded excerpt: the first 50 to 500 lines per file, depending on the gap. Paths are sent repo-relative. Secret files are never read, and the content passes through the same redaction rules as Vibe Coder uploads before it leaves your machine. A gap with nothing left to send after this is not sent and not billed.

The results come back as new review items: architecture components, module specs, doc summaries, and module relationships. They join the spec map only if you accept them. A finished gap is not run again on a retry.

Developer Review

Developer Review lists every pending item as a card with its category, title, source path, and scope.

• Select Accept or Reject on each card.
• Select the pencil icon to change the scope. Scope is project, domain, or feature, with an optional name. Select Save scope to keep it.
• Select Accept All Remaining to accept every pending item at once.
• A yellow warning icon marks an item the scanner is less sure of.

The counter shows how many items you have reviewed. Apply to Knowledge Graph (the button applies to the spec map) turns on when no pending items remain.

Guided Review

Guided Review steps through 10 categories in order: Tech Stack, Configuration, Database Schema, Documentation, Architecture, Specifications, Project Structure, Routes & Endpoints, Environment & Services, and Entry Points. Each step shows how many items it found and lists the first 5.

• Looks good, continue accepts every pending item in the category and moves on.
• Reject all in category rejects them and moves on.
• On the last step, the button reads Apply and applies your choices.

CI items, module relationships from deep analysis, and orphaned items from a rescan are not in those categories, so Guided Review leaves them unapplied. Use Developer Review for them.

What each item becomes

When you apply, accepted items are written as follows:

• Tech stack items merge into the project's tech stack.
• Specification items become spec nodes.
• Every other category, including architecture docs, becomes a reference node (type standard).
• Relationship items become links between nodes.
• Each node created from a file gets a file mapping to that path.

Anything under a superpowers/ path is always imported as documentation, so it can only become a reference node, never a spec node.

Before writing a node, Vibeless checks its content for prompt-injection text. If the check blocks it, the item is still imported, as a placeholder node with the content withheld. The result message says how many items were "imported as placeholders (content withheld)" and lists the first reasons.

What apply changes

Apply reports the nodes created, updated, and removed, and the file mappings created. It also does the following without an LLM:

• Imports rows from a decisions table in your architecture or decisions docs as decisions.
• Fills the project description, goal, constraints, and non-goals from your README and architecture or spec docs, but only where they still hold the import defaults. Values you have edited are never overwritten.
• Reads Claude Code hooks from .claude/settings.local.json, or from .claude/settings.json when there is no local file, and adds them to the project.
• Records the applied state as the drift baseline.
• Rebuilds the session-start summary that installed agents read.

After that, Vibeless starts a background enforcement derivation, which does use an LLM. It suggests machine-checkable patterns for your constraints, non-goals, phases, decisions, and spec documents, and the suggestions wait on Dashboard → Enforcement for you to accept or reject. Like other LLM features, it needs a paid plan and uses credits. If it fails, the import is not affected. See Dashboard.

How it connects to the rest of Vibeless

The import connects the folder to the project. While the project is open, the file watcher and git monitor watch that folder and record file changes and commits as change events in the Drift Log. Drift is a gap between what the project record says and what the code does. See Logs.

Those change events never add anything to the spec map by themselves. Neither does a scan. The spec map that agents read is curated by people in the app, and an item only becomes a context node when someone accepts it here or adds it in the Spec Editor or the Context Editor.

Rescan

Run a rescan when the spec map should catch up with the repository, such as after new docs, renamed files, or deleted modules. Open the panel with Manage Import and select Re-scan.

On a rescan, each item carries a badge:

• New: no existing node matches it.
• Updated: a node exists for this path but its content differs. Accepting updates that node in place and keeps its links.
• Unchanged: the node already matches.
• Orphaned: a mapped file no longer appears in the scan.

Accepting an orphan removes its file mapping. The node is deleted only if it has no other mappings left. Rejecting an orphan keeps both. Only file mappings with a literal path can become orphans. Wildcard mappings, such as **/Cargo.toml, are never reported as orphaned. Path matching ignores letter case, so Docs/x.md and docs/x.md count as the same file.

Rules and limits

• Creating a project through import counts against your plan's project limit.
• The scan and review need no plan and send nothing off your machine.
• Deep analysis and the post-apply enforcement derivation are LLM features. They need a paid plan and use credits.
• Nothing is added to the spec map without your acceptance, and nothing found later by the file watcher or a rescan is added automatically.

If something looks wrong

• "No code detected": the folder had nothing the scanner recognized. Check that you picked the project root and try again.
• A gap says the import root looks one level too high: you picked the folder above the repository. Import again from the subfolder it names.
• CI items or orphans were not applied after Guided Review: Guided Review does not cover them. Re-open the panel and use Developer Review.
• An item imported as a placeholder: its content failed the prompt-injection check. Look in the source file for text written as instructions to an AI model.
• Analyze Selected is disabled: the estimate exceeds your remaining credits, or you are on the free plan. Deselect gaps, or select Skip Deep Analysis.