The guide

Four things. Nothing needs admin rights, and the app checks each one as you go — if something is missing it will say which, not "not connected".

What you need

You do not need to be an administrator on your machine. Everything installs into your own user folder, so a locked-down work laptop is fine.

Step 1 — Install the Revit bridge

Scope3D Desktop does not talk to Revit directly. It goes through rvt-mcp, a bridge made by BIMwright that runs inside Revit and lets other programs read and change the model.

1. Open Scope3D Desktop. The setup panel is the first thing you see.
2. Click Get the bridge installer.
3. Run the installer it downloads and accept the defaults.
4. Come back to Scope3D Desktop — it notices on its own and ticks the step.

Where it goes. C:\Users\<you>\AppData\Local\RvtMcp\ — inside your own profile, which is why there is no admin prompt.

Step 2 — Let Revit see it

The bridge installer adds itself to Revit automatically. The app confirms it found the add-in for your Revit version.

If Revit was open while you installed

Close Revit completely and open it again. Revit only looks for add-ins when it starts, so an add-in installed while Revit is running will not appear until the next launch.

This is the single most common reason people think the install failed. It did not — Revit simply has not looked yet.

Step 3 — Start the panel in Revit

1. Open Revit and load the model you want to work on.
2. Find the BIMwright tab on the ribbon, along the top.
3. Click Start MCP.

Scope3D Desktop flips to Revit connected within a second or two. You do not need to click anything in Scope3D — it is watching.

Do this every time you start Revit. The panel stops when Revit closes.

If it does not connect

Step 4 — Connect an AI provider

Scope3D Desktop uses your own account with an AI company. You are billed by them directly — Scope3D never sees the money, and never sees the key.

1. Choose a provider. Any one is enough; you do not need all three.
2. Click Open the key page and sign in.
3. Create a key and copy it.
4. Paste it into Scope3D Desktop and click Connect.

The key is checked against the provider before it is stored, so a typo fails here with a clear message rather than three screens later. It is then kept in Windows Credential Manager — the same place Windows keeps your saved passwords. The app window never has access to it; requests are signed outside the window.

The one that catches people out

A brand-new key is valid but has no credit behind it. It will pass the check here and then every run will fail with a quota error that does not mention billing.

Add a payment method on the provider's site before your first trace. Most people spend a few dollars a month; a single floor plan trace is typically well under a dollar.

Set a budget

In Spend, set a budget per provider. Scope3D Desktop counts what it spends down against it and warns you in the last tenth.

This measures what this app spends, not your account balance — no provider will tell an ordinary API key what the balance is, so anything claiming to show one would be guessing. The panel links through to your provider's own console for the authoritative figure.

You are done

Drop a floor plan onto the window, or just describe what you want in your own words.

Where the intelligence comes from, what it costs, and how to plug it in.

The short version

Scope3D Desktop has no AI of its own. It drives your account with an AI company, so:

• You are billed directly by them, at their published rates. Scope3D never takes a cut, never resells tokens, and never sees the money.
• Your key never leaves your machine except to that company. It is stored in Windows Credential Manager and attached to requests outside the app window. There is no read-back — not even Scope3D can display it once saved.
• Your drawings and your model go to that company, because that is what makes the tracing work. Nothing goes to Scope3D.

Any one provider is enough. A second one is not a nice-to-have upsell — it is what lets a run carry on when the first is overloaded instead of stopping halfway through a floor plan.

Anthropic (recommended)

The default, and the one the prompts are tuned against.

1. Go to platform.claude.com/settings/keys.
2. Sign in, or create an account.
3. Add billing. New accounts start with no credit; a key without it authenticates and then fails on the first real request. This is the single most common false start.
4. Create Key, give it a name like Scope3D, and copy it. It starts sk-ant-.
5. In Scope3D: Setup → Connect an AI provider → Anthropic → paste → Connect.

The key is checked against the API before it is stored, so a truncated paste fails immediately with a clear message rather than three screens later as an unexplained run failure.

Already have ANTHROPIC_API_KEY on this machine? Scope3D offers a one-click Use the key already on this machine button, and there is nothing to copy.

OpenAI

1. Go to platform.openai.com/api-keys.
2. Sign in, then add billing under Settings → Billing. Same trap as above.
3. Create new secret key, copy it. It starts sk-.
4. In Scope3D: Setup → Connect an AI provider → OpenAI → paste → Connect.

Environment variable, if you already have one: OPENAI_API_KEY.

Google Gemini

1. Go to aistudio.google.com/apikey.
2. Sign in with a Google account and Create API key.
3. Copy it. New keys start AQ — Google calls these authentication keys. Older ones start AIza (traffic keys) and still work; AI Studio no longer issues them.
4. In Scope3D: Setup → Connect an AI provider → Google Gemini → paste → Connect.

Environment variable, if you already have one: GEMINI_API_KEY.

Gemini's Pro tier is currently preview only. Preview models are fine for production use, but Google may retire one at two weeks' notice — which is why Scope3D marks them (preview) in the picker. A model that disappears is a scheduled retirement, not the app breaking.

Pasting the wrong key in the wrong box

Each provider's key has a recognisable shape, and Scope3D checks it before spending a round trip:

You get "that looks like an Anthropic key" rather than a 401 whose body says invalid x-api-key and nothing about which of three keys went into which box.

Removing a key

Setup → the provider → Remove this key. It is deleted from Credential Manager. Revoke it at the provider too if it may have been exposed — removing it here stops this app using it, nothing more.

What it actually costs

Rates are per million tokens and are shown next to every model on the setup screen. But the number that matters is not the rate — it is how much of a long trace is cached.

A trace re-sends the whole conversation on every step. Scope3D marks cache breakpoints so the unchanged prefix is billed at roughly a tenth of the input rate, and on a long run that is most of the prompt. A 480,000-token request at 94% cached costs a fraction of what the headline rate implies.

The chip in the top bar shows this conversation's spend and the lifetime total, measured from the token counts the provider itself returned. It is not a balance — see below.

Why the app cannot show your remaining credit

None of the three providers expose an account balance through their API. Any figure shown here would be a guess. What Scope3D can measure honestly is what it spent, so that is what it shows — and each provider's own billing page is one click away from the spend panel.

Troubleshooting

"The API rejected this key." Almost always billing, not the key. Check the provider's billing page has a payment method and credit.

"Could not reach the API to check just now." The key is stored and will be used. This is a network result, not a verdict — a corporate proxy or VPN is the usual cause.

A run stops saying the provider is overloaded. Scope3D retries on its own with increasing waits. If you have a second provider connected, it moves across and carries on, and says so in the feed. That is the practical reason to add a second key.

Rate limits on a new account. New accounts start on low tiers. A long trace can hit them. Provider dashboards show your tier and what raises it — usually just spend over time.

Next: Choosing a model — which tier to trace with, and which to ask questions with.

Which tier to trace with, and which to ask questions with.

The one rule

Trace with the top tier. Ask questions with anything.

Tracing a floor plan is long, multi-step work: read the drawing, reconcile the printed dimensions, decide every coordinate, write C#, run it, read the model back, correct what is wrong, repeat. Each step compounds on the last, so a model that is 5% worse at step one is considerably worse by step twenty.

Asking "how many doors are on L2" is a single lookup. Any model does that, and the cheap ones do it faster.

You change model from Setup → Choose a model, or from the picker in the top bar. Changing it mid-conversation is fine — the transcript carries across.

Anthropic

OpenAI

Google Gemini

Both Pro entries are marked (preview). See Connecting an AI provider for what that means in practice.

Reading the price

Every model shows two numbers — dollars per million tokens in and out. Two things make them less alarming than they look:

• Output is a small fraction of a trace. Most tokens are the conversation being re-sent, not written.
• Most of the input is cached, at roughly a tenth of the rate.

So compare models on the input rate first, and treat the output rate as the tie-breaker.

When to switch mid-job

• A trace keeps misreading dimensions → try Gemini Pro for that turn. Its drawing-reading is the strongest of the three.
• A trace is going in circles → move up a tier rather than re-prompting a model that has already shown it cannot see the problem.
• You are asking about a model you already built → move down. It is the same answer for a fraction of the cost.

What happens when a provider goes down

If you have a second provider connected, a run that fails on availability grounds — overloaded, a dead connection, a 5xx — moves across and carries on, and announces the switch in the feed.

It deliberately does not fail over on a 400, or on a refusal: those are a bug or a decision, and switching providers would hide them behind a different error message.

Reasoning state cannot cross providers — it is signed by whoever produced it — so the switch happens at a turn boundary and the previous model's private reasoning is stripped. Everything said out loud survives.

Next: Trace a floor plan.

The job the product exists for: a PDF or an image of a plan, and a Revit model at the end of it.

What you do

1. Open your model in Revit and start the BIMwright panel.
2. Drag the drawing onto Scope3D Desktop. A PDF, a PNG, a photo of a printed sheet — all fine. A multi-page PDF comes in as every page, so a whole drawing set arrives at once.
3. Say what you want, or just press Send. Dropped drawings with no words are read as trace this.
4. Watch. You will see it read the model, work out coordinates, write C#, run it, and check what changed — every step, as it happens.

That is the whole interaction. There is no wall-drawing tool and no settings to tune.

What it actually does, and why that matters

Most of the work happens before a single wall is created.

It reads the printed numbers, not the pixels. Room labels carry dimension strings — 19'-0" by 9'-9" — and the sheet usually prints its own total area. Those are the specification. Pixels are only used to work out which room adjoins which and where the doors are. Measuring lengths off pixels is what puts a trace several inches out per room, and those errors accumulate along an axis rather than cancelling out.

It decides every coordinate before creating anything. Walls that share a corner must use the same number, not two that differ in the fourth decimal — that difference is exactly what Revit reports as overlapping walls, and no amount of tidying afterwards fixes it cleanly.

It checks itself after every change. Every write is followed by a read: how many elements exist now, whether Revit raised new warnings, whether the walls actually enclose rooms. That report goes straight back to the model, so mistakes get corrected inside the run instead of surviving into your project.

It finishes with the drawing's own acceptance test. Once the rooms close, it totals their areas and compares against the figure printed on the sheet. Within about 1% means the geometry agrees with the drawing. Further out means a dimension is wrong — and it goes and finds which one rather than stretching a wall until the number matches.

What a good result looks like

A trace of a 1,393.4 sf upper floor produced:

34 walls · 10 doors · 12 windows · 1 stair
16 of 16 rooms enclosed
0 Revit warnings
1,396.9 sf against 1,393.4 printed  (+0.25%)

Those are the numbers to ask for. "Done" is not a result; 16 of 16 rooms and 0 warnings is.

Working from a drawing set

Real jobs are not one sheet. Attach the floor plan, the elevation and the door schedule together — Scope3D Desktop reads all of them before it builds anything.

• Drawings (images, PDF pages) are looked at.
• Documents (.txt, .csv, .md, .json, schedules) are read as text, not as pictures of text. A room schedule read as characters is exact; the same schedule read off a raster is a transcription exercise that can go wrong.

You can drop a whole folder, paste an image straight from the clipboard, or pick several files at once in the file browser.

Tips that make a real difference

• Say which level. "on L1" removes the most common ambiguity in the whole job.
• Give it the printed area if the sheet does not show one. It is the only end-to-end check there is.
• Let it finish. A full plan is meant to take several minutes — it is reading, building, checking and correcting. The step counter and elapsed clock show it is working.
• Look at the Changes rail. Every write is listed with the exact code that ran, so nothing has to be taken on trust.

How work is organised, and how to get a drawing in.

A project is one conversation about one model

Everything lives in a project: the drawings you attached, every change written to Revit, the checkpoints taken before each run, and the transcript.

Start or reopen one from Start a project in the top bar, or the chats menu while you are working.

Each project also gets a folder on disk:

C:\Users\<you>\AppData\Local\Scope3D\chats\<project>\

In it:

• drawings\ — every drawing you attached, at full resolution.
• checkpoints\ — a copy of your model taken before each run.
• handover.md — a short note per turn: what was asked, who answered, what changed.

That last one is why switching model mid-project works. The transcript survives a switch, but the working knowledge would not, so the app writes it down rather than trusting a model to remember.

Which building a project belongs to

A project records the Revit document it was working on. Reopen it while Revit has a different project open, and Scope3D says so and asks you to open the right one first.

This is the one mistake nothing else can catch: a transcript reads identically whichever model is loaded, so carrying on would apply this conversation's work to the wrong building with nothing at all to reveal it until the damage was done.

Getting a drawing in

Four ways, all equivalent:

• Drag and drop onto the window — a file, several files, or a whole folder.
• Paste an image straight from the clipboard.
• The image button in the composer, which takes a multi-select.
• Type a path if the file is already somewhere sensible.

What it accepts

Drawings — looked at:

Documents — read as text, not as pictures of text:

The distinction matters more than it sounds. A room schedule read as characters is exact. The same schedule read off a raster is a transcription exercise, and transcription of a table of numbers is precisely where a mistake will not announce itself.

If you have the schedule as a file, attach the file.

Attaching a whole set

Real jobs are not one sheet. Attach the floor plan, the elevation and the door schedule together — all of them are read before anything is built.

The drawings appear above your message, all of them, each one clickable to open full size and downloadable. The transcript is often the only place a pasted screenshot still exists, so there is always a way back out to a file.

Where the drawings actually live

Two copies, deliberately:

• A small one in the transcript, so the conversation still shows what was sent after a restart.
• The full-resolution one on disk, in the project's drawings\ folder.

The transcript is capped at about 5 MB by the browser storage underneath it. A drawing at full size is megabytes on its own, so keeping them there would either blow the cap or force the app to start discarding things — which is exactly what used to happen.

Clicking a drawing opens the copy from disk, at full size. That is the one you can check a dimension against.

Tips that make a real difference

• Say which level. "on L1" removes the most common ambiguity in the whole job.
• Give it the printed total area if the sheet does not show one. It is the only end-to-end check that exists.
• Attach the schedule as a file, not a screenshot of one.
• Let it finish. A full plan is meant to take several minutes.

Next: Checking the work.

How to tell a correct model from a plausible one.

"needs attention" is not an error

After every change, Scope3D Desktop reads the model back and reports what it found. When that report flags something, the card says needs attention in amber.

This is the system working. The check ran, it found something, and the model has been told — it fixes it on the next step. The run has not stopped.

The card shows what was actually found:

• what was added and removed, by category
• how many rooms are enclosed
• new Revit warnings, named — "3× Highlighted walls overlap" is a thing to fix; "3 warnings" is just a number
• the full reading, folded away, if you want it

A red error is different: that is a call that failed. Those are rare, and they say why.

The warnings that matter

The pattern behind all of them: a room that will not close is a gap in the walls, not a missing Room element. Placing another room never fixes it.

The acceptance test

The sheet prints its own total area. That number is the only end-to-end check that exists, and it is the last thing a trace should do.

• Within ~1% — the geometry agrees with the drawing.
• 1–3% out — close enough to be one room rather than a systematic misreading. Find which room.
• More than 3% out — a dimension is wrong, or a whole space is missing or duplicated. The axes need reconciling before anything is changed.

Never let a wall be adjusted just to make the total match. That hides the error instead of fixing it, and it is the difference between a model that is correct and one that merely reports a correct number.

Your safety net

Every run takes a checkpoint first. Before it touches anything, Scope3D Desktop saves a copy of your model into that conversation's folder and names the file on the change record. If a run goes somewhere you did not want, open that copy in Revit.

There is deliberately no "undo the run" button. A genuine undo lives in Revit's own undo stack and cannot be driven reliably from outside — a file saved beforehand can be, and unlike an undo it survives Revit crashing.

Your model is saved after every run that changed it. Everything the app does lives in Revit's memory until something writes it to disk, and a crash takes whatever was never written.

If it says "Never saved — do Save As in Revit"

Do that once. A document that has never been written to disk has no file to save into, and that is exactly the case where a Revit crash loses an afternoon.

Reading what it spent

The chip beside the model picker shows this conversation's cost, then the lifetime total.

Most of a long trace is cache reads — the conversation so far, billed at a fraction of the normal rate. That is why a 480K-token prompt can cost very little, and why the panel shows the cache hit rate rather than just a number.

Written from the symptom, because that is what you would search for.

"No Revit" in the top bar

The bridge is not answering. In order of likelihood:

1. Revit is not running. Open it, with a model loaded.
2. The panel is not started. BIMwright tab → Start MCP. It stops when Revit closes, so this is needed every session.
3. Revit is showing a dialog. A modal window blocks Revit's API completely. Scope3D Desktop clears the safe ones itself in Auto mode, but if Revit is waiting on something only you can answer, go and answer it.
4. Something else is connected. The bridge serves one program at a time — often a second copy of Scope3D Desktop.

Click Setup in the top bar to re-run the four checks.

I installed the bridge and Revit shows no BIMwright tab

Close Revit completely and open it again. Revit reads add-in manifests only at startup, so an add-in installed while Revit was running does not appear until the next launch.

This is the most common false alarm in the whole setup.

The run stopped and said the connection went silent

The connection to the AI provider died without closing properly. Send again — the conversation is kept, and nothing already written to your model is lost.

If it keeps happening it is usually a corporate proxy or VPN sitting in the middle.

"Overloaded", or a run that stops partway

The AI provider is busy. Scope3D Desktop retries on its own with increasing waits.

If you have a second provider connected, it moves across and carries on — the switch is announced in the feed. That is the main practical reason to add a second key.

It ran for minutes and nothing appeared

Look at the status line. It names the actual phase rather than saying "working":

• Sending the conversation… — packaging a long transcript to send.
• Sent — waiting for the model… — the request is in and the model is thinking. On a long conversation this legitimately takes minutes.
• Thinking… · 480K prompt · 94% cached — working, and that cache figure is why a long conversation stays affordable.

If nothing arrives for 20 seconds it says so and keeps counting. Past 90 seconds it stops and tells you the connection is dead, rather than waiting forever.

It built something wrong

1. Say what is wrong, plainly. "The kitchen is 16 inches too shallow" is enough — it reads the model back and corrects it.
2. If a whole run went wrong, open the checkpoint file named on that change record.
3. Re-apply replays a recorded change set exactly as it ran. It refuses when the set refers to elements that no longer exist, rather than half-applying — so it is for repeating a self-contained change, not for resurrecting an old trace after the model has moved on.

"This chat was working on a different model"

You have reopened a conversation that belongs to another Revit project. Open that project first.

A transcript reads exactly the same whichever model is loaded, so carrying on here would apply this conversation's work to the wrong building with nothing at all to reveal it.

An older chat disappeared

Older versions could evict conversations when browser storage filled up. Current versions cap what a transcript stores and shed step-by-step history before ever discarding a conversation.

A chat missing from before you updated is not recoverable, but it will not happen again.

Sending a bug report

The app keeps its own log:

C:\Users\<you>\AppData\Local\Scope3D\run-log.jsonl

One line per step, with timings — Setup → Run log shows it in the app. Attaching that file says far more than a description of what you saw.