---
title: "VS Code extension · Alran Code Docs"
url: https://alran.dev/en/docs/vscode
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Automate

# VS Code extension

The same agent in VS Code, Cursor, Windsurf and VSCodium. The extension drives the real CLI, so everything works the same.

On this page

[How do I install the VS Code extension?](#install) [Sign in](#signin) [What it adds](#features) [Plugins and Skills](#store) [Models, credit and errors](#models) [Slash commands](#commands) [Remote development and other editors](#remote) [Settings](#settings) [Shortcuts](#shortcuts) [When something does not work](#troubleshooting) [Common questions](#faq)

## How do I install the VS Code extension? {#install}

1. Install the CLI: npm install -g alran or curl -fsSL https://alran.dev/install.sh | bash (see Install). The extension needs Alran Code **0.9.0 or newer** and does not work without it.
2. Install the extension in VS Code 1.90 or newer: search for **Alran Code** in the Extensions view. Cursor, Windsurf and VSCodium get it from Open VSX.
3. Open the chat with Ctrl+Alt+A.

The extension finds `alran` on your `PATH`, in your login shell's `PATH` or in the usual install folders. `alran.executablePath` points it at another build. When the CLI is missing, the extension says so right after startup and offers to install it.

## Sign in {#signin}

The browser opens the Ottili sign-in page; in a remote or web window you confirm a short code instead. New accounts get welcome credit for Ottili Werk. You can also paste an Ottili API key, or connect your own provider without any account ([Your own provider](https://alran.dev/en/docs/byok)). Your Ottili account appears in the editor's **Accounts** menu, and signing out there revokes the session. More in [Sign in and accounts](https://alran.dev/en/docs/auth).

## What it adds {#features}

- **Chat** with streaming answers, reasoning, tool calls with inline diffs and several sessions in tabs, also as an editor tab.
- **Context**: `@` adds files and plugins, Ctrl+Alt+L adds the selection, images can be pasted or dropped.
- **Decisions** as cards with a preview and an **Open diff** button. In the default mode Alran asks before it writes outside your project.
- **Changes view** with a real diff of everything a session changed, and per-file or full revert.
- **Plan Mode, permission mode, model and effort** in the composer and the status bar.
- **Account view** with company, project, default model, credit and this month's spending.
- **`@alran`** in the VS Code Chat view, an **Alran Code** terminal profile, Quick Fixes and *Add to chat* in the context menus.

## Plugins and Skills {#store}

The Plugin Store and the Skill Library are built in. Open them with **Alran: Browse Plugin Store…** or **Alran: Browse Skill Library…**, with the Plugins group of the Capabilities view, or from the chat with `/plugin` (also `/plugins` and `/store`) and `/skills library`.

- A list of Plugins, the Skill Library, what is installed and the stores. The title bar switches between them.
- Type to search. **Enter** installs, or updates when the store offers a newer version. Buttons show details, switch a Plugin on or off and remove it.
- A Plugin that runs commands or connects to services is never installed straight away: the extension lists every MCP server command, hook and connector and waits for your approval. A Plugin that only holds Skills installs at once.
- **Alran: Add Plugin Store…** adds another store. A store that cannot be read is reported in the list; the others still work.
- Skills and Plugins load when a chat starts, so the extension offers a **New Chat** after a change.

The same commands work in the terminal: [Plugins, skills and hooks](https://alran.dev/en/docs/plugins#store).

## Models, credit and errors {#models}

The model picker shows each model's price and whether you can use it now, and the star makes a model the default for new sessions. Welcome credit covers Ottili Werk; Claude runs on your own Anthropic key, which you add once on the Ottili AI Platform — the command **Alran: Add or Replace Your Anthropic Key** opens the page ([Models and credit](https://alran.dev/en/docs/models)).

When something goes wrong, a card says what happened and offers the next step: add your Anthropic key, switch to Ottili Werk, add credit, sign in again, try again after a rate limit, or compact a conversation that no longer fits. The original message stays under **Details**.

## Slash commands {#commands}

Type `/` in the chat, or run **Alran: Slash Commands…**, to see every command and Skill. Every slash command of the terminal UI works in the chat ([Slash commands](https://alran.dev/en/docs/commands)). Commands that only the terminal UI can perform, such as `/rewind` or `/theme`, open the current session in the real TUI in an integrated terminal and reattach when it closes.

## Remote development and other editors {#remote}

The extension runs where your code is: over Remote SSH, in WSL, in dev containers and in Codespaces. Install the CLI on that machine; sign-in then uses a code you confirm in your local browser. `@alran` needs an editor with the VS Code Chat view; everything else works the same in Cursor, Windsurf and VSCodium.

## Settings {#settings}

| Setting | Purpose |
| `alran.executablePath`, `alran.nodePath` | Which CLI and Node.js to run |
| `alran.env` | Extra environment for the agent, such as `ALRAN_DATA_DIR` or `ALRAN_STORE_URL` |
| `alran.systemPrompt`, `alran.appendSystemPrompt` (and `File` variants) | Prompt overrides for sessions opened from this editor |
| `alran.mcpServers` | MCP servers added to those sessions |
| `alran.chat.enterWhileRunning` | Whether Enter steers or queues during a task |
| `alran.context.includeActiveFile` | Share the current file by default |
| `alran.notifications.when`, `alran.notifications.events` | Notifications for finished turns and requests |
| `alran.confirmFullAccess` | Confirm before enabling Full Access |

Providers, permission rules and everything else stay in `config.yaml`, shared with the terminal ([Configuration and data](https://alran.dev/en/docs/config)).

## Shortcuts {#shortcuts}

| macOS | Linux | Windows | Action |
| Cmd+Alt+A | Ctrl+Alt+A | Ctrl+Shift+Alt+A | Open the chat |
| Cmd+Alt+N | Ctrl+Alt+N | Ctrl+Shift+Alt+N | New session |
| Cmd+Alt+L | Ctrl+Alt+L | Ctrl+Shift+Alt+L | Add the selection to the chat |
| Cmd+Alt+E | Ctrl+Alt+E | Ctrl+Shift+Alt+E | Explain the selection |
| Cmd+Alt+M | Ctrl+Alt+M | Ctrl+Shift+Alt+M | Choose a model |
| Cmd+Alt+P | Ctrl+Alt+P | Ctrl+Shift+Alt+P | Plan Mode on or off |

On Windows, Ctrl+Alt is the same key as AltGr, which types characters such as `@` and `€`; the Windows shortcuts add Shift so they never get in the way. In the composer: Enter steers a running task, Ctrl+Enter queues the next one, Esc stops, Shift+Tab toggles Plan Mode.

## When something does not work {#troubleshooting}

| Problem | What to do |
| *Alran CLI not found* | Run **Alran: Install or Locate the Alran CLI…**, or set `alran.executablePath`. |
| *Alran CLI is older than this extension needs* | `npm install -g alran`, or **Alran: Update Alran CLI**. 0.9.0 or newer is required. |
| *Alran needs a newer Node.js* | The CLI needs Node.js 22.19 or newer (22.x), 24.2+, 25 or 26. The install script brings its own. |
| Sign-in does not finish | Use **Alran: Sign In with a Code**; it needs no callback to this machine. |
| *Claude needs your Anthropic key* | Add the key with **Alran: Add or Replace Your Anthropic Key**, or switch to Ottili Werk. |
| The Plugin Store is empty and mentions a store that *could not be read* | The store's host is not reachable from this machine. Check the network, or add another store. |
| A Plugin or Skill is missing in a chat | They load when a chat starts. Open a **New Chat**. |
| Anything else | **Alran: Show Logs** has the details; **Alran: Reload Agent** restarts the agent. |

More: [Troubleshooting](https://alran.dev/en/docs/troubleshooting).

## Common questions {#faq}

What do I need to install the VS Code extension?

Install the CLI first with npm install -g alran, then the extension in VS Code 1.90 or newer by searching for Alran Code in the Extensions view. The extension needs Alran Code 0.9.0 or newer and does not work without the CLI. Cursor, Windsurf and VSCodium get the extension from Open VSX, and Ctrl+Alt+A opens the chat.

How do I sign in to the VS Code extension?

The browser opens the Ottili sign-in page, and in a remote or web window you confirm a short code instead. New accounts get welcome credit for Ottili Werk, and you can also paste an Ottili API key or connect your own provider without any account. Your Ottili account shows in the Accounts menu of the editor, and signing out there revokes the session.

How do I get the Plugin Store and Skills in VS Code?

The Plugin Store and the Skill Library are built into the extension. Open them with Alran: Browse Plugin Store… or Alran: Browse Skill Library…, with the Plugins group of the Capabilities view, or from the chat with /plugin (also /plugins and /store) and /skills library. A plugin that runs commands or connects to services is never installed straight away: the extension lists every MCP server command, hook and connector and waits for your approval.

[PreviousNode.js and ACP](https://alran.dev/en/docs/sdk) [NextModels and credit](https://alran.dev/en/docs/models)
