> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings and local data

> Configure the Embedder VS Code extension, environment overrides, telemetry, application data locations, and diagnostic logs for troubleshooting.

VS Code settings control the extension UI and its local CLI process. Environment variables provide machine-level overrides for storage, diagnostics, headless authentication, and hardware tool discovery.

## VS Code settings

Open VS Code Settings and search for `Embedder`, or edit `settings.json`.

| Setting                                           | Type    | Default   | Behavior                                                                                             |
| ------------------------------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `embedder.cliPath`                                | string  | `""`      | Uses this absolute CLI binary path. An empty value enables automatic discovery.                      |
| `embedder.autoInstallCli`                         | boolean | `true`    | Prompts to install a compatible CLI when none is found.                                              |
| `embedder.showSerial`                             | boolean | `true`    | Shows the Embedder Monitor in the secondary side bar.                                                |
| `embedder.showReasoningSummaries`                 | boolean | `true`    | Shows live and completed reasoning summaries. When off, live turns use a generic thinking indicator. |
| `embedder.closeAgentChatOnActivation`             | boolean | `true`    | Closes VS Code's built-in agent chat the first time Embedder activates in a workspace.               |
| `embedder.moveChatToSecondarySidebarOnActivation` | boolean | `true`    | Reveals Embedder chat in the secondary side bar on first activation.                                 |
| `embedder.telemetry`                              | boolean | `true`    | Allows anonymized extension error reports and breadcrumbs unless another opt-out is active.          |
| `embedder.logLevel`                               | string  | `"debug"` | Sets extension file-log verbosity to `error`, `warn`, `info`, `debug`, or `trace`.                   |

For example:

```json theme={"system"}
{
  "embedder.cliPath": "/opt/embedder/bin/embedder",
  "embedder.autoInstallCli": false,
  "embedder.showSerial": true,
  "embedder.showReasoningSummaries": false,
  "embedder.telemetry": false,
  "embedder.logLevel": "info"
}
```

Changes to `embedder.showSerial` and `embedder.showReasoningSummaries` apply while the extension is running. The two activation settings affect only the first activation behavior for a workspace.

The extension resolves `embedder.logLevel` and initializes error reporting when its extension host starts. Reload the VS Code window after changing `embedder.logLevel` or `embedder.telemetry` if you need the new value to apply to the current process.

## Environment variables

Set environment variables before starting Embedder. In VS Code, the extension host and the CLI process must inherit them, so reload the window after changing the environment.

### Storage and diagnostics

| Variable                  | Behavior                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `EMBEDDER_APP_DIR`        | Replaces the default `~/.embedder` application-data directory.                          |
| `EMBEDDER_CACHE_DIR`      | Replaces the native library cache directory.                                            |
| `EMBEDDER_NO_TELEMETRY=1` | Disables telemetry regardless of the stored preference or VS Code setting.              |
| `EMBEDDER_LOG_LEVEL`      | Overrides `embedder.logLevel` for extension file logs.                                  |
| `LOG_LEVEL`               | Sets CLI file-log verbosity. The production CLI defaults to `info`.                     |
| `EMBEDDER_GIT_BASH_PATH`  | Selects a Git Bash executable on Windows when the normal shell selection is unsuitable. |

`EMBEDDER_LOG_LEVEL` and `LOG_LEVEL` control different processes. Use both when support asks for trace output from the extension and CLI:

```bash theme={"system"}
export EMBEDDER_LOG_LEVEL=trace
export LOG_LEVEL=trace
```

### Headless and daemon selection

| Variable               | Behavior                                                      |
| ---------------------- | ------------------------------------------------------------- |
| `EMBEDDER_API_KEY`     | Authenticates daemon mode.                                    |
| `EMBEDDER_BACKEND_URL` | Overrides the daemon backend URL.                             |
| `EMBEDDER_TEAM`        | Pins daemon work to a team when used with `EMBEDDER_PROJECT`. |
| `EMBEDDER_PROJECT`     | Pins daemon work to a project when used with `EMBEDDER_TEAM`. |

`EMBEDDER_TEAM` and `EMBEDDER_PROJECT` must be supplied together. Interactive editor sign-in normally uses stored credentials instead of `EMBEDDER_API_KEY`.

### Hardware tool overrides

| Variable                | Behavior                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `EMBEDDER_OPENOCD_PATH` | Uses the named OpenOCD executable or binary path before the managed OpenOCD installation. An invalid value falls back to managed discovery. |
| `OPENOCD_SCRIPTS`       | Uses this existing OpenOCD scripts directory for target and board configuration discovery.                                                  |
| `EMBEDDER_SCOPE_HOST`   | Skips oscilloscope network discovery and connects to the specified host.                                                                    |
| `EMBEDDER_XRUN_PATH`    | Selects the XMOS `xrun` executable.                                                                                                         |
| `EMBEDDER_XMOS_XE`      | Selects an XMOS `.xe` artifact relative to the project or by absolute path.                                                                 |

Prefer `EMBEDDER.md` for project-specific commands and artifact paths. Use an environment override for a machine-specific installation or discovery problem.

## Application data paths

The default application-data directory is:

```text theme={"system"}
~/.embedder
```

This directory can contain stored credentials, user preferences, telemetry preference, global approval rules, managed tools, and virtual project data. Common files include:

```text theme={"system"}
~/.embedder/approvals.json
~/.embedder/telemetry.json
~/.embedder/user-prefs.json
```

`EMBEDDER_APP_DIR` relocates these files. On Windows, the managed CLI binary directory defaults to `%LOCALAPPDATA%\embedder` when you have not set `EMBEDDER_APP_DIR`.

Project-local data uses `.embedder/` under the project root. Plans, hardware scripts, captures, traces, schematics, reports, and project configuration can live there. If Embedder cannot write the project directory, writable runtime data falls back to a hashed project directory under the application-data directory.

## Telemetry controls

Embedder uses telemetry for usage diagnostics, performance reports, error events, and breadcrumbs. Error reporting is configured without default personally identifiable information.

You have three control layers:

1. `EMBEDDER_NO_TELEMETRY=1` is the hard machine-process override.
2. `/telemetry on` or `/telemetry off` writes the machine preference to `telemetry.json`.
3. `embedder.telemetry: false` opts the VS Code extension host out.

The VS Code setting is an extension-host opt-out. The slash command controls the stored machine preference read by the CLI and extension. To ensure every Embedder process is off, set `EMBEDDER_NO_TELEMETRY=1`.

Run `/telemetry` without an argument to inspect the effective state:

```text theme={"system"}
/telemetry
/telemetry off
/telemetry on
```

When the environment variable is set, `/telemetry on` is rejected because the setting is pinned off. Restart Embedder after changing telemetry so crash reporting also picks up the new value.

<Note>
  Turning telemetry off does not disable local logs.
</Note>

## Log locations

The extension and CLI write separate timestamped files in the same platform log directory:

| Platform | Directory                                                                                         |
| -------- | ------------------------------------------------------------------------------------------------- |
| macOS    | `~/Library/Logs/Embedder/logs/`                                                                   |
| Linux    | `$XDG_DATA_HOME/Embedder/logs/`, or `~/.local/share/Embedder/logs/` when `XDG_DATA_HOME` is unset |
| Windows  | `%LOCALAPPDATA%\Embedder\logs\`                                                                   |

Extension files start with `vscode-`. CLI files start with `log-`. Each active file rotates at 10 MB, and old logs are pruned by age and count.

Use these surfaces to open diagnostics:

* `/logs` opens the CLI log directory;
* **Embedder: Open CLI Logs** lets you choose the current extension log, either log directory, or the **Embedder** output channel;
* **Embedder: Show CLI Process Output** opens raw CLI process output.

For a support capture, set the needed log level to `trace`, reload VS Code, reproduce the problem once, and restore the previous level afterward. Review logs before sharing them because local paths, command output, and environment details can appear in diagnostic records.