Install the VS Code extension

The Imaginne extension brings the agent into your editor: chat, proposed edits with a diff, code review, and more. It doesn't run the agent on its own — it uses the local imaginne CLI under the hood.

Prerequisite: the imaginne CLI

The extension starts the imaginne serve process under the hood, so the imaginne binary must be installed on your machine. Install the CLI first (see Install the TUI):

curl -fsSL https://ai.nnumbers.com.br/downloads/install.sh | bash

You also need VS Code ^1.85 (or newer) and an account in your organization. See Identity & login.

1. Install the extension

1. In VS Code, open the Extensions tab (Ctrl/Cmd+Shift+X).
2. Search for Imaginne (ID nnumbers.imaginne).
3. Click Install.

The extension activates once the editor finishes starting up (onStartupFinished).

DEV channel

For the validation environment, install the nnumbers.imaginne-dev extension and point it at the matching DEV CLI. See channels.

2. Open a project folder

The extension needs an open workspace — a project folder. Use File → Open Folder… before continuing. Without a folder open, the chat and context actions are unavailable.

3. Log in

Authenticate one of two ways:

• Through the command: open the palette (Ctrl/Cmd+Shift+P) and run Imaginne: Login.
• Through the chat: run /login in the message field.

The browser opens your organization's login page; when you're done, the editor receives the session token and hands it off to the local Engine. To sign out, use Imaginne: Logout; to check your identity, Imaginne: Whoami.

"cloud API key is required for model nnumbers"

If you see this error, the login token hasn't reached the Engine yet. Run Imaginne: Login (or /login) again. More cases in Troubleshooting.

4. Useful settings

Open Settings (Ctrl/Cmd+,) and search for imaginne. The most important ones at install time:

Setting	What for
imaginne.binaryPath	Path to the imaginne CLI, in case it isn't on the VS Code PATH.
imaginne.platformUrl	Platform URL, for specific environments.

CLI not found?

If the extension can't locate imaginne, set imaginne.binaryPath to the full path of the binary (by default, something like ~/.imaginne/bin/imaginne). The extension also offers the Imaginne: Configure Binary Path command for this. If you hit "Engine disconnected," run Imaginne: Run Health Check.

The extension has dozens of other settings (smart context, autonomy, command allowlist). The full reference is in VS Code commands.

5. Open the chat

Open the chat panel with Ctrl/Cmd+Shift+I. To put focus directly in the message field, use Ctrl/Cmd+Shift+L.

Type a request — for example, "explain this file" — or select a snippet and use Imaginne: Fix Selection. The edits proposed by the agent land in the Proposed Changes panel, where you review them with a diff before applying. See it all in Use it in VS Code.

See also

🧩Use it in VS Code

Chat, context, Proposed Changes, review, and autonomy modes.

Open →📋VS Code commands

Commands, shortcuts, and settings.

Open →✅Code review

Review changes, fix them, and generate the commit message.

Open →