Connect Claude Desktop to Virgil

One click in Virgil, one in Claude Desktop, nothing else to install.

Claude can read the maps you build in Virgil and help organise them. Connecting the two takes one click in Virgil and one in Claude Desktop. There is nothing else to install.

Before you start

You need Virgil 3.40 or later and the Claude Desktop app, both installed on this Mac. Open both.

Step 1 — Switch on external agents in Virgil

In Virgil, open Settings → AI Features → Agents and switch on Connect External Agents. This starts a small server that only listens on your own Mac; nothing outside your computer can reach it.

Step 2 — Install the extension in Claude Desktop

Below the switch, click Install in Claude Desktop. Virgil hands its Claude Desktop extension to Claude Desktop and brings Claude Desktop forward, where an install sheet appears.

If you do not see the sheet, it is probably behind one of your other windows. Bring Claude Desktop to the front and look again.

Step 3 — Read the warning, then click Install

The sheet says the extension isn't verified by Anthropic. That notice appears for every extension that does not come from Anthropic's own listing, and Virgil's is not listed there yet. What the extension does is simple: it passes Claude's requests to Virgil on this Mac and passes the answers back. It does not connect to anything else, and it sends nothing off your computer.

Click Install.

Step 4 — Try it

In Claude Desktop, ask something like "What topics do I have open in Virgil?" Claude uses the extension to look. Back in Virgil, the Claude Desktop row under Settings → AI Features → Agents changes to Working once Claude Desktop has talked to Virgil.

What Claude can do, and what it asks first

Reading is free once external agents are on: Claude can list your maps, topics and pages, read page content, and search your research. For changes, Claude Desktop asks you before using a tool, and Virgil adds its own question before anything that deletes or merges a topic. A reorganisation proposal is always shown to you as a before/after preview to approve or reject. If you want Virgil to ask before every change, raise Ask Before Agents Edit Your Maps in the same settings section, which also shows an audit log of what each agent has done.

If something is not working

Claude says Virgil is not running, or external agents are switched off

Open Virgil and check that Connect External Agents is on. Claude Desktop reconnects by itself the next time it asks Virgil something.

The install sheet never appeared

Look behind your other windows first. If it is not there, open Claude Desktop's Settings → Extensions: if Virgil is listed, the extension is already installed. If not, click Install in Claude Desktop in Virgil again.

I regenerated the token in Virgil

Nothing to do. The extension picks up a new token by itself.

I use Cursor, Zed or another MCP client

Those connect with a pasted configuration rather than an extension. Click Copy config snippet in the same settings section and merge the virgil entry into that app's MCP servers configuration.

Removing the connection

In Claude Desktop, open Settings → Extensions and remove Virgil. In Virgil, switch off Connect External Agents to stop the server. If you connected Claude Desktop with an earlier version of Virgil, the Agents section may offer to remove that older entry from Claude Desktop's configuration file too.

Privacy

Your maps, pages and history stay on your Mac. The extension only talks to Virgil on the same computer. What Claude Desktop then sends to its AI provider is governed by that provider's terms. The full policy is on the privacy page.