Lumoswitch Docs
Agent setup

Aider setup

Aider is an open-source pair-programming agent that runs in a terminal. It can read a Git repository, edit code, create commits, and send model requests through an OpenAI-compatible provider such as Lumoswitch.

The API configuration must enable OpenAI-compatible output, and the target model should have reliable code-editing ability. Before continuing, confirm that aider --version returns a version number.

Choose a setup method

MethodBest forLocal writesStill active after exit?
One-time launchTesting a URL, Key, or modelTemporary model settingsNo
Persistent useEveryday terminal useNative configuration + optional launcher and modelsYes
Browser UIOperating the same local Aider process in a browserReuses the launch methodDepends on the launch method
IDEUsing an integrated terminal or file-watch workflowReuses the launch methodDepends on the launch method

Aider has no official standalone desktop app and no official IDE plugin. Its browser UI, IDE terminal workflow, and file-watch mode all run the same Aider process, so they do not need a second Lumoswitch provider configuration.

Prepare the connection values

PlaceholderValue
{{api_base_url}}The OpenAI-compatible request URL shown by the API configuration; it should end in /v1
{{access_key}}The API configuration's Access Key
{{model}}The client-facing model name shown by the API configuration
{{aider_model_settings_yaml}}Aider model settings generated from effective reasoning capabilities
{{aider_reasoning_effort}}Safe default effort for the selected model; empty when it must not be sent

Commands copied from the console already contain real values. Generated model settings declare accepts_settings: reasoning_effort only for models whose effective capabilities support it; when the default effort is empty, the native configuration sends no reasoning parameter.

One-time launch

Run this command in the project that Aider should edit. It creates a temporary model settings file and passes the connection variables only to the new Aider process. The file is deleted on exit, the variables do not pollute the current shell, and existing Aider configuration is unchanged.

(
  set -e
  LUMOSWITCH_AIDER_MODELS="$(mktemp "${TMPDIR:-/tmp}/lumoswitch-aider-models.XXXXXX")"
  trap 'rm -f "$LUMOSWITCH_AIDER_MODELS"' EXIT
  cat > "$LUMOSWITCH_AIDER_MODELS" <<'LUMOSWITCH_AIDER_MODELS_EOF'
{{aider_model_settings_yaml}}LUMOSWITCH_AIDER_MODELS_EOF
  chmod 600 "$LUMOSWITCH_AIDER_MODELS"
  LUMOSWITCH_AIDER_REASONING_EFFORT="{{aider_reasoning_effort}}"
  set --
  if [ -n "$LUMOSWITCH_AIDER_REASONING_EFFORT" ]; then
    set -- --reasoning-effort "$LUMOSWITCH_AIDER_REASONING_EFFORT"
  fi
  env \
    OPENAI_API_KEY="{{access_key}}" \
    OPENAI_API_BASE="{{api_base_url}}" \
    aider --model-settings-file "$LUMOSWITCH_AIDER_MODELS" --model "openai/{{model}}" "$@"
)

The openai/ prefix tells Aider to use an OpenAI-compatible provider. It is not sent to Lumoswitch as part of the client-facing model name.

Persistent use

Run the complete command during initial setup and whenever the Lumoswitch URL, Access Key, or model changes. It writes Aider-supported persistent configuration and model settings without overwriting .aider.conf.yml, then saves an optional Lumoswitch maintenance launcher.

Persistent import stores the Access Key in an owner-only managed environment or Agent configuration file. Use it only on a trusted personal device.

set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/aider"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-aider"
mkdir -p "$LUMOSWITCH_ROOT" "$(dirname "$LUMOSWITCH_LAUNCHER")"
umask 077

if [ -f "$LUMOSWITCH_LAUNCHER" ]; then
  LUMOSWITCH_BACKUP="$LUMOSWITCH_LAUNCHER.backup.$(date +%Y%m%d-%H%M%S)-$$"
  cp "$LUMOSWITCH_LAUNCHER" "$LUMOSWITCH_BACKUP"
  chmod 600 "$LUMOSWITCH_BACKUP"
fi

LUMOSWITCH_AIDER_MODELS="$LUMOSWITCH_ROOT/models.yml"
LUMOSWITCH_AIDER_CONFIG="$LUMOSWITCH_ROOT/aider.conf.yml"
cat > "$LUMOSWITCH_AIDER_MODELS" <<'LUMOSWITCH_MODELS_EOF'
{{aider_model_settings_yaml}}LUMOSWITCH_MODELS_EOF
cat > "$LUMOSWITCH_AIDER_CONFIG" <<LUMOSWITCH_CONFIG_EOF
model: "openai/{{model}}"
model-settings-file: "$LUMOSWITCH_AIDER_MODELS"
reasoning-effort: "{{aider_reasoning_effort}}"
openai-api-base: "{{api_base_url}}"
openai-api-key: "{{access_key}}"
LUMOSWITCH_CONFIG_EOF

cat > "$LUMOSWITCH_ENV" <<'LUMOSWITCH_ENV_EOF'
export AIDER_CONFIG="$HOME/.config/lumoswitch/agents/aider/aider.conf.yml"
LUMOSWITCH_ENV_EOF

case "$SHELL" in
  */zsh) LUMOSWITCH_PROFILE="$HOME/.zshrc" ;;
  */bash) LUMOSWITCH_PROFILE="$HOME/.bashrc" ;;
  *) LUMOSWITCH_PROFILE="$HOME/.profile" ;;
esac
touch "$LUMOSWITCH_PROFILE"
LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: aider'
LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/aider/env.sh" ] && . "$HOME/.config/lumoswitch/agents/aider/env.sh"'
if ! grep -Fqx "$LUMOSWITCH_SOURCE_LINE" "$LUMOSWITCH_PROFILE"; then
  printf '\n%s\n%s\n' "$LUMOSWITCH_PROFILE_MARKER" "$LUMOSWITCH_SOURCE_LINE" >> "$LUMOSWITCH_PROFILE"
fi
printf '%s\n' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_ROOT/profile-path"

cat > "$LUMOSWITCH_LAUNCHER" <<'LUMOSWITCH_LAUNCHER_EOF'
#!/usr/bin/env bash
set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/aider"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-aider"

if [ "$1" = "--lumoswitch-clean" ]; then
  if [ -f "$LUMOSWITCH_ROOT/profile-path" ]; then
    LUMOSWITCH_PROFILE="$(cat "$LUMOSWITCH_ROOT/profile-path")"
    if [ -f "$LUMOSWITCH_PROFILE" ]; then
      LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: aider'
      LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/aider/env.sh" ] && . "$HOME/.config/lumoswitch/agents/aider/env.sh"'
      LUMOSWITCH_PROFILE_TMP="$LUMOSWITCH_PROFILE.lumoswitch.$$"
      awk -v marker="$LUMOSWITCH_PROFILE_MARKER" -v source="$LUMOSWITCH_SOURCE_LINE" '$0 != marker && $0 != source' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_PROFILE_TMP"
      mv "$LUMOSWITCH_PROFILE_TMP" "$LUMOSWITCH_PROFILE"
    fi
  fi
  if [ -d "$LUMOSWITCH_ROOT" ]; then
    find "$LUMOSWITCH_ROOT" -depth \( -type f -o -type l \) -delete
    find "$LUMOSWITCH_ROOT" -depth -type d -exec rmdir {} \; 2>/dev/null || true
  fi
  find "$(dirname "$LUMOSWITCH_LAUNCHER")" -maxdepth 1 -type f -name 'lumoswitch-aider.backup.*' -delete
  rm -f "$LUMOSWITCH_LAUNCHER"
  printf '%s\n' 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
fi

if [ -f "$LUMOSWITCH_ENV" ]; then . "$LUMOSWITCH_ENV"; fi
exec aider "$@"
LUMOSWITCH_LAUNCHER_EOF

chmod 600 "$LUMOSWITCH_ENV"
find "$LUMOSWITCH_ROOT" -type f -exec chmod 600 {} \;
chmod 700 "$LUMOSWITCH_LAUNCHER"
. "$LUMOSWITCH_ENV"
printf '%s\n' 'Native Lumoswitch setup saved. Future command: aider'
printf '%s\n' 'Optional maintenance launcher: ~/.local/bin/lumoswitch-aider'
aider

For later sessions, run:

aider

You can append normal Aider arguments. Before an update, the installer keeps a timestamped copy of the old launcher with 0600 permissions.

Native Windows PowerShell import

These commands run natively in Windows PowerShell without WSL and use the same connection values as the macOS/Linux templates on this page.

One-time use on Windows

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchConfig = Join-Path ([IO.Path]::GetTempPath()) ('lumoswitch-' + [Guid]::NewGuid().ToString('N') + '.yml')
  $lumoswitchConfigContent = @'
{{aider_model_settings_yaml}}
'@
  [IO.File]::WriteAllText($lumoswitchConfig, $lumoswitchConfigContent, [Text.UTF8Encoding]::new($false))
  $lumoswitchEnvironmentNames = @('OPENAI_API_BASE', 'OPENAI_API_KEY')
  $lumoswitchPreviousEnvironment = @{}
  foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
    $lumoswitchPreviousEnvironment[$lumoswitchName] = [Environment]::GetEnvironmentVariable($lumoswitchName, 'Process')
  }
  $lumoswitchExitCode = 0
  try {
    [Environment]::SetEnvironmentVariable('OPENAI_API_BASE', '{{api_base_url}}', 'Process')
    [Environment]::SetEnvironmentVariable('OPENAI_API_KEY', '{{access_key}}', 'Process')
    $lumoswitchArguments = @('--model-settings-file', $lumoswitchConfig, '--model', 'openai/{{model}}')
    if ('{{aider_reasoning_effort}}') { $lumoswitchArguments += @('--reasoning-effort', '{{aider_reasoning_effort}}') }
    $lumoswitchExecutable = Get-Command 'aider.cmd' -CommandType Application -ErrorAction SilentlyContinue
    if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'aider' -CommandType Application -ErrorAction Stop }
    & $lumoswitchExecutable.Path @lumoswitchArguments
    if ($null -ne $LASTEXITCODE) { $lumoswitchExitCode = $LASTEXITCODE }
  } finally {
    foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
      [Environment]::SetEnvironmentVariable($lumoswitchName, $lumoswitchPreviousEnvironment[$lumoswitchName], 'Process')
    }
    Remove-Item -LiteralPath $lumoswitchConfig -Force -ErrorAction SilentlyContinue
  }
  if ($lumoswitchExitCode -ne 0) { throw 'aider exited with code ' + $lumoswitchExitCode }
}

Persistent use on Windows

This command backs up existing Lumoswitch-owned files and restricts access to the configuration and launcher for the current user.

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\aider'
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-aider.ps1'
  $lumoswitchBackupSuffix = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + $PID

  function Protect-LumoswitchFile([string] $Path) {
    $lumoswitchSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    & icacls.exe $Path '/inheritance:r' '/grant:r' ('*' + $lumoswitchSid + ':(F)') '*S-1-5-18:(F)' '*S-1-5-32-544:(F)' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Could not restrict access to $Path" }
  }

  function Install-LumoswitchFile([string] $Path, [string] $Content) {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    if (Test-Path -LiteralPath $Path) {
      $lumoswitchItem = Get-Item -LiteralPath $Path -Force
      if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
        throw "Lumoswitch refused to replace a directory or link: $Path"
      }
      $lumoswitchBackup = $Path + '.backup.' + $lumoswitchBackupSuffix
      Copy-Item -LiteralPath $Path -Destination $lumoswitchBackup
      Protect-LumoswitchFile $lumoswitchBackup
    }
    $lumoswitchTemporary = $Path + '.' + [Guid]::NewGuid().ToString('N') + '.tmp'
    try {
      [IO.File]::WriteAllText($lumoswitchTemporary, $Content, [Text.UTF8Encoding]::new($false))
      Move-Item -LiteralPath $lumoswitchTemporary -Destination $Path -Force
      Protect-LumoswitchFile $Path
    } finally {
      Remove-Item -LiteralPath $lumoswitchTemporary -Force -ErrorAction SilentlyContinue
    }
  }

  [IO.Directory]::CreateDirectory($lumoswitchRoot) | Out-Null
  $lumoswitchAiderModels = Join-Path $lumoswitchRoot 'models.yml'
  $lumoswitchAiderConfig = Join-Path $lumoswitchRoot 'aider.conf.yml'
  $lumoswitchModelsContent = @'
{{aider_model_settings_yaml}}
'@
  Install-LumoswitchFile $lumoswitchAiderModels $lumoswitchModelsContent
  $lumoswitchAiderConfigPath = $lumoswitchAiderModels.Replace('\', '/')
  $lumoswitchConfigContent = @'
model: "openai/{{model}}"
model-settings-file: "__LUMOSWITCH_MODELS__"
reasoning-effort: "{{aider_reasoning_effort}}"
openai-api-base: "{{api_base_url}}"
openai-api-key: "{{access_key}}"
'@.Replace('__LUMOSWITCH_MODELS__', $lumoswitchAiderConfigPath)
  Install-LumoswitchFile $lumoswitchAiderConfig $lumoswitchConfigContent

  $lumoswitchEnvironment = [ordered]@{}
  $lumoswitchEnvironment['AIDER_CONFIG'] = (Join-Path $lumoswitchRoot 'aider.conf.yml')
  foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
  }

  $lumoswitchLauncherContent = @'
param([Parameter(ValueFromRemainingArguments = $true)][string[]] $AgentArgs)
$ErrorActionPreference = 'Stop'
$lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\aider'
$lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-aider.ps1'

function Remove-LumoswitchFile([string] $Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return }
  $lumoswitchItem = Get-Item -LiteralPath $Path -Force
  if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
    throw "Lumoswitch refused to remove a directory or link: $Path"
  }
  Remove-Item -LiteralPath $Path -Force
}

if ($AgentArgs.Count -gt 0 -and $AgentArgs[0] -eq '--lumoswitch-clean') {
  foreach ($lumoswitchName in @('AIDER_CONFIG')) {
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'Process')
  }
  if (Test-Path -LiteralPath $lumoswitchRoot -PathType Container) {
    $lumoswitchRootItem = Get-Item -LiteralPath $lumoswitchRoot -Force
    if ($lumoswitchRootItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Lumoswitch refused to clean through a linked directory.' }
    foreach ($lumoswitchFile in @(Get-ChildItem -LiteralPath $lumoswitchRoot -File -Recurse -Force)) { Remove-LumoswitchFile $lumoswitchFile.FullName }
    foreach ($lumoswitchDirectory in @(Get-ChildItem -LiteralPath $lumoswitchRoot -Directory -Recurse -Force | Sort-Object FullName -Descending)) {
      if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchDirectory.FullName -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchDirectory.FullName -Force }
    }
    if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchRoot -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchRoot -Force }
  }
  $lumoswitchBin = Split-Path -Parent $lumoswitchLauncher
  if (Test-Path -LiteralPath $lumoswitchBin -PathType Container) {
    foreach ($lumoswitchBackup in @(Get-ChildItem -LiteralPath $lumoswitchBin -Filter 'lumoswitch-aider.ps1.backup.*' -File -Force)) { Remove-LumoswitchFile $lumoswitchBackup.FullName }
  }
  Remove-LumoswitchFile $lumoswitchLauncher
  Write-Host 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
}

$lumoswitchEnvironment = [ordered]@{}
$lumoswitchEnvironment['AIDER_CONFIG'] = (Join-Path $lumoswitchRoot 'aider.conf.yml')
foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
  [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
}
$lumoswitchExecutable = Get-Command 'aider.cmd' -CommandType Application -ErrorAction SilentlyContinue
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'aider.exe' -CommandType Application -ErrorAction SilentlyContinue }
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'aider' -CommandType Application -ErrorAction Stop }
$lumoswitchArguments = @()
& $lumoswitchExecutable.Path @lumoswitchArguments @AgentArgs
if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
'@
  Install-LumoswitchFile $lumoswitchLauncher $lumoswitchLauncherContent
  Write-Host 'Native Lumoswitch setup saved. Future command: aider'
  Write-Host 'Optional maintenance launcher:' $lumoswitchLauncher
  $lumoswitchExecutable = Get-Command 'aider.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'aider.exe' -CommandType Application -ErrorAction SilentlyContinue }
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'aider' -CommandType Application -ErrorAction Stop }
  $lumoswitchArguments = @()
  & $lumoswitchExecutable.Path @lumoswitchArguments
  if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { throw 'aider exited with code ' + $LASTEXITCODE }
}

The import writes the Agent-supported persistent configuration and starts aider directly. The saved Lumoswitch maintenance script is not required to start the Agent; run it with --lumoswitch-clean when you need to restore or remove this setup.

Remove the setup

Windows PowerShell

Exit every Lumoswitch session for this Agent, then run the command below. The optional maintenance launcher removes the managed native configuration, restores any preserved shared file, clears Lumoswitch user environment values, and removes itself.

& {
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-aider.ps1'
  if (-not (Test-Path -LiteralPath $lumoswitchLauncher -PathType Leaf)) {
    throw 'The optional Lumoswitch maintenance launcher is missing. Run persistent import again before cleanup.'
  }
  & powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File $lumoswitchLauncher --lumoswitch-clean
}

macOS / Linux

This command removes the managed Aider configuration, environment hook, optional launcher, and backups. It does not remove Aider chat history, Git history, or user configuration.

"$HOME/.local/bin/lumoswitch-aider" --lumoswitch-clean

The one-time command scopes its variables to the Aider child process, so nothing remains after it exits.

Browser and IDE use

Browser UI

Aider's --browser option opens an experimental local web interface for the current Aider process; it is not a separate desktop client. Append --browser to the one-time command, or, after persistent setup, run:

aider --browser

It reuses the Lumoswitch URL, Key, and model from the same process, so there is no separate one-time, persistent, or removal configuration. Stop the Aider process to end the browser session; cleaning the managed native setup removes the persistent connection.

IDEs

The official workflow is to run Aider in an IDE's integrated terminal or use --watch-files with an editor. After persistent setup, you can run aider --watch-files. Aider currently has no official IDE plugin. Credential storage and removal for third-party plugins are controlled by their authors and are not modified by this page.

See the Aider browser UI, file watch mode, and optional dependencies.

Verify and troubleshoot

  • Ask Aider to explain a small file first, then test an edit. Confirm the model and Access Key in Lumoswitch request logs.
  • 404: check whether /v1 is missing or duplicated in the downstream URL.
  • Unknown model: keep Aider's openai/ prefix and use the API configuration's client-facing model name.
  • Poor editing behavior: some models are not suitable for repository edits; retest with a model known to have strong coding ability.

Reference: Aider OpenAI-compatible APIs and the configuration reference.

Maintainer publishing fields
  • Platform ID: aider
  • Display name: Aider CLI
  • Downstream protocol: openai-compatible
  • commandTemplate: copy the complete code block under "One-time launch"
  • Persistence strategy: native
  • persistentCommandTemplate: copy the complete setup command under "Persistent use"
  • futureCommand: aider
  • Display order: 70
  • Last verified: 2026-08-27

Qwen Code setup

Understand Qwen Code and choose one-time, persistent, or removal instructions for Lumoswitch

Zed Agent setup

Configure Zed's native coding Agent with Lumoswitch without overwriting shared editor settings

On this page

Aider setupChoose a setup methodPrepare the connection valuesOne-time launchPersistent useNative Windows PowerShell importOne-time use on WindowsPersistent use on WindowsRemove the setupWindows PowerShellmacOS / LinuxBrowser and IDE useBrowser UIIDEsVerify and troubleshoot