# IDE Integrations

*Inline semantic state in VS Code, JetBrains, Vim, Emacs, and Zed.*

## Overview

Aura runs as a background process. Without an IDE extension, the signal surfaces in the terminal or in PR comments. With an extension, it surfaces where you actually code — next to the function that was just modified, on the line that broke an intent, in the gutter next to a claimed team zone.

Aura ships first-party extensions for five editor families:

| Editor | Extension | Distribution |
|--------|-----------|--------------|
| VS Code | `aura-vcs.aura` | VS Code Marketplace, OpenVSX |
| JetBrains (IntelliJ, GoLand, PyCharm, WebStorm, Rider) | `Aura Semantic VCS` | JetBrains Marketplace |
| Vim / Neovim | `aura-vim` | GitHub, package managers |
| Emacs | `aura.el` | MELPA, GitHub |
| Zed | `aura` | Zed extensions panel |

All five talk to the same underlying Aura daemon (`aura daemon`) over a local socket. If you have multiple editors open on the same repo, they share state.

## Feature Matrix

| Feature | VS Code | JetBrains | Vim/Neovim | Emacs | Zed |
|---------|---------|-----------|------------|-------|-----|
| Inline intent preview | yes | yes | yes | yes | yes |
| Gutter markers for changed nodes | yes | yes | yes | partial | yes |
| Snapshot before edit | auto | auto | manual | manual | auto |
| Team zone warnings | yes | yes | yes | yes | yes |
| Live sync notifications | yes | yes | yes | yes | yes |
| Rewind from palette | yes | yes | yes | yes | yes |
| Semantic diff view | yes | yes | no | no | yes |
| Impact alert popups | yes | yes | yes | yes | yes |
| Sentinel inbox panel | yes | yes | no | yes | no |
| MCP server autoconfig | yes | yes | no | no | yes |

"Partial" in Emacs for gutter markers means overlays instead of true fringe support.

## Setup

### VS Code

Install from the Marketplace:

```
code --install-extension aura-vcs.aura
```

Or search "Aura" in the Extensions panel. On first launch in an Aura-initialized repo, the extension prompts to start the daemon. Status appears in the lower status bar as `Aura ● <branch>`.

Settings in `.vscode/settings.json`:

```json
{
  "aura.daemon.autoStart": true,
  "aura.snapshot.beforeSave": true,
  "aura.diff.semanticOnly": false,
  "aura.team.zoneWarnings": "blocking",
  "aura.team.syncBanner": true,
  "aura.mcp.autoConfigureClaude": true
}
```

`aura.mcp.autoConfigureClaude` writes the MCP server config into `.vscode/mcp.json` so Claude Code (run from VS Code's terminal) picks it up automatically.

### JetBrains

Install from **Settings → Plugins → Marketplace → "Aura Semantic VCS"**. The plugin adds:

- An **Aura** tool window (left rail) with tabs for Status, Intent Log, Team, Impacts, Sentinel.
- Line-marker gutter icons for nodes changed since the last intent.
- A **Rewind Function** action on right-click of any method.
- A semantic diff viewer that overlays the standard JetBrains diff view.

Configuration lives under **Settings → Tools → Aura**. For Rust/Kotlin/TS projects, the plugin auto-enables appropriate AST parsers.

### Vim / Neovim

For Neovim with `lazy.nvim`:

```lua
{
  "naridon-inc/aura.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    require("aura").setup({
      daemon = { auto_start = true },
      signs = { changed = "▍", zone_blocked = "✖" },
      keymaps = {
        snapshot   = "<leader>as",
        intent     = "<leader>ai",
        prove      = "<leader>ap",
        rewind     = "<leader>ar",
        team_inbox = "<leader>at",
      },
    })
  end,
}
```

For classic Vim with `vim-plug`:

```vim
Plug 'naridon-inc/aura-vim'
```

The plugin uses `vim.lsp` (Neovim) or a hidden buffer-command bridge (Vim) to talk to the daemon. Telescope and fzf integrations ship out of the box; the `:Aura` command exposes every daemon operation.

### Emacs

From MELPA:

```elisp
(use-package aura
  :ensure t
  :hook (prog-mode . aura-mode)
  :custom
  (aura-auto-snapshot t)
  (aura-show-team-banner t)
  :bind (:map aura-mode-map
              ("C-c a s" . aura-snapshot)
              ("C-c a i" . aura-log-intent)
              ("C-c a p" . aura-prove)
              ("C-c a r" . aura-rewind)))
```

`aura-mode` adds overlays on changed AST nodes and a mode-line indicator showing pending pulls. The Sentinel inbox surfaces in a dedicated `*aura:sentinel*` buffer.

### Zed

In Zed, open the extensions panel (`cmd-shift-x`) and search **Aura**. Install. The extension registers:

- A status-bar item showing branch and sync state.
- Slash commands `/aura-intent`, `/aura-prove`, `/aura-rewind` in the Assistant panel.
- An auto-configured MCP server pointing at `aura mcp serve`, so Zed's AI features get the full tool list.

Config in `~/.config/zed/settings.json`:

```json
{
  "aura": {
    "daemon": { "auto_start": true },
    "snapshot": { "on_save": true },
    "mcp": { "auto_configure": true }
  }
}
```

## Configuration

Every IDE extension reads from a shared config layer:

1. `.aura/config.toml` in the repo.
2. `~/.config/aura/ide.toml` per-user.
3. IDE-specific settings (VS Code's `settings.json`, JetBrains' `Tools → Aura`, etc.).

IDE settings override repo settings override user settings. A minimal `~/.config/aura/ide.toml`:

```toml
[ide]
theme = "dark"
show_zone_warnings = true
auto_snapshot = true
banner_position = "bottom"

[ide.diff]
default_view = "semantic"       # "semantic" | "text" | "split"
highlight_moved_nodes = true
```

## Examples

### Snapshot on save

Most users enable auto-snapshot. When on, every file save first calls `aura_snapshot` via the daemon. If the file is in a `BLOCKED` team zone, the save is rejected and the editor shows a banner pointing to the owner. If `WARNING`, the save proceeds but a toast notifies the owner through the team messaging system.

### Inline intent preview

Hover over a function; a popover shows:

- Last intent that touched this node.
- Author, timestamp, commit SHA.
- Nearest related Prove goal.
- Any open impact alerts for this node.

This is the single most-used feature across all IDEs. It is the semantic equivalent of `git blame` but at the AST-node level.

### Rewind from the palette

`Cmd+Shift+P → "Aura: Rewind Function"` (VS Code / Zed), or `<leader>ar` (Neovim). Pick a function from the fuzzy list, pick a snapshot, confirm. The function body is restored at the AST level — surrounding code untouched, no merge conflicts.

### MCP autoconfiguration

When `aura.mcp.autoConfigureClaude` is on, the extension writes (and keeps in sync) the `mcp.json` file used by Claude Code. This means a new team member installing the extension gets working AI integration with zero manual steps. See [MCP server](/mcp-server) for the underlying protocol.

## Troubleshooting

**Extension shows "Daemon not running".** Launch manually: `aura daemon start`. If it dies immediately, check `~/.aura/logs/daemon.log`. Common cause: the socket path conflicts with a previous crashed daemon — run `aura doctor` to clean up.

**Gutter markers stale.** The AST index is behind the filesystem. Save the file, or force a reindex with `aura index --repo`.

**JetBrains freezes on large repos.** The plugin's default parser limit is 500 KB per file. Raise it in **Settings → Tools → Aura → Parser → Max file size**, or add the file to `.aurarignore`.

**Neovim plugin doesn't load in Vim.** `aura.nvim` is Neovim-only. For classic Vim, use `aura-vim`.

**MCP auto-config overwrites my `mcp.json`.** The extension is additive — it only manages the `aura-vcs` entry. If you see clobbering, file a bug; in the meantime set `aura.mcp.autoConfigureClaude: false` and write the entry manually.

## The Daemon Architecture

Every IDE extension talks to a long-lived `aura daemon` process. The daemon owns the AST index, the session DB, the team sync connection, and the MCP server. Extensions are thin — they render UI and forward user actions to the daemon. This has three consequences worth knowing:

1. **Consistency across editors.** Open the repo in VS Code and Neovim simultaneously; both show the same intent log, the same zone state, the same pending pulls. There is one source of truth.
2. **Restart resilience.** Kill the IDE; the daemon keeps running. Reopen the IDE; state is already there. No re-indexing, no re-authenticating to the mothership.
3. **Low CPU on edit.** The expensive work (AST diff, semantic matching) runs once in the daemon, not per-editor. Opening five editors costs the same as one.

The daemon exposes both a Unix-socket IPC (for same-machine extensions) and optionally an HTTP API (for remote/Codespaces scenarios). See [Aura HTTP API](/aura-api-reference) for the HTTP surface.

## Remote Development

For VS Code Remote, JetBrains Gateway, and similar remote-development setups, install Aura on the **remote** host, not your laptop. The extensions automatically detect the remote daemon. If the remote host has no network access to your mothership, configure a tunnel:

```bash
aura tunnel start --remote team-main --local 127.0.0.1:7420
```

The tunnel is an authenticated SSH-over-HTTPS connection that multiplexes Aura traffic.

## GitHub Codespaces and Gitpod

Both work out of the box if your Codespace/Gitpod image includes `aura`. For Gitpod, add to `.gitpod.yml`:

```yaml
tasks:
  - init: curl -fsSL https://aura.build/install.sh | sh
    command: aura daemon start
```

For Codespaces, add to `.devcontainer/devcontainer.json`:

```json
"postCreateCommand": "curl -fsSL https://aura.build/install.sh | sh",
"postStartCommand": "aura daemon start"
```

The VS Code extension in the Codespace picks up the daemon automatically.

## See Also

- [MCP server](/mcp-server) — the protocol every IDE extension ultimately drives.
- [CLAUDE.md integration](/claude-md-integration) — for IDE-hosted AI agents.
- [Semantic diff](/semantic-diff) — what the diff viewer renders.
- [Mothership overview](/mothership-overview) — team features surfaced in the IDE.