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

# Aider integration guide

[Aider](https://aider.chat/) is an open-source, terminal-based AI pair-programming tool with a large and active community. It edits your codebase directly from natural-language instructions, with full git integration.

## Prerequisites

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=aider\&utm_medium=external\&utm_campaign=cloud_signup) account and [API key](https://cloud.sambanova.ai/apis?utm_source=aider\&utm_medium=external\&utm_campaign=cloud_signup)
* Python 3.9 or later (3.10 to 3.12 if you install with `pip`)
* A git repository to work in (Aider uses git for every edit)

## Setup

**1. Install Aider**

Aider's documented installation method:

```bash theme={}
python -m pip install aider-install
aider-install
```

This installs Aider into its own isolated environment and puts the `aider` command on your `PATH`, independent of whatever Python environment your project uses.

> [!TIP]
>
> A plain `pip install aider-chat` into your own virtual environment also works, but it requires Python 3.10 to 3.12. On an unsupported version, `pip` quietly installs an older Aider release instead of reporting an error. `aider-install` is Aider's own recommended path and avoids dependency conflicts with your project's packages.

**2. Change into your project directory**

```bash theme={}
cd /path/to/your/project
```

Aider uses git for every edit, so this should be a git repository (or run `git init` first).

**3. Export your SambaCloud API key**

Aider routes custom OpenAI-compatible endpoints through the `OPENAI_API_BASE` and `OPENAI_API_KEY` environment variables:

```bash theme={}
export OPENAI_API_BASE="https://api.sambanova.ai/v1"
export OPENAI_API_KEY="your-sambanova-api-key"
```

> [!TIP]
>
> These exports replace any OpenAI credentials already set in that shell. To keep them separate, pass `--openai-api-base` and `--openai-api-key` on the command line, or put both variables in a file and load it with `--env-file`.

**4. Run Aider with a SambaNova model**

Prefix the model name with `openai/`:

```bash theme={}
aider --model openai/MiniMax-M3
```

This opens Aider's interactive chat in your current git repository.

## Usage

Name the files you want Aider to edit on the command line — this "adds them to the chat" so Aider can see and modify their contents:

```bash theme={}
aider --model openai/MiniMax-M3 calculator.py
```

```text theme={}
Aider v0.86.2
Model: openai/MiniMax-M3 with whole edit format
Git repo: .git with 1 files
Repo-map: using 1024 tokens, auto refresh
Added calculator.py to the chat.

calculator.py>
```

At the prompt, describe the change you want in plain language:

```text theme={}
calculator.py> Add a function that computes a factorial
```

Only add the files that actually need editing — Aider pulls in relevant context from the rest of the repository automatically, and adding too many files wastes tokens and can confuse the model. You can also run Aider with no files named and let it figure out what to edit from your request, or add files mid-session with the in-chat `/add` command.

Every change Aider makes is committed to git automatically, so changes are easy to review and undo. If a change isn't what you wanted, use the in-chat `/undo` command to revert it.

## Example: a non-interactive edit

Run non-interactively against a specific file with `--message`, useful for scripting:

```bash theme={}
aider --model openai/MiniMax-M3 --message "Add a subtract(a, b) function to calculator.py that returns a - b" calculator.py
```

```diff Output (abridged) theme={}
calculator.py

 def add(a, b):
     return a + b
+
+def subtract(a, b):
+    return a - b

Tokens: 746 sent, 30 received.
Applied edit to calculator.py
```

The edit is written to disk immediately and committed to git.

## Register the model's real context window

Without extra configuration, Aider doesn't recognize `MiniMax-M3` and prints:

```text theme={}
Warning for openai/MiniMax-M3: Unknown context window size and costs, using sane defaults.
```

Fix this by creating `.aider.model.metadata.json` in your repo root (or home directory):

```json .aider.model.metadata.json theme={}
{
  "openai/MiniMax-M3": {
    "max_tokens": 1048576,
    "max_input_tokens": 1048576,
    "max_output_tokens": 1048576
  }
}
```

> [!NOTE]
>
> With this file in place, the warning disappears and Aider's repo map grows from the default 1024 tokens to 4096. `MiniMax-M3` has a single 1048576-token budget shared between input and output, which is why both values match. See [SambaCloud models](/docs/en/models/sambacloud-models.md) for other models' context windows.

## Troubleshooting

> **Warning: Unknown context window size and costs, using sane defaults**
>
> Aider has no built-in metadata for SambaNova models. Add a `.aider.model.metadata.json` file as shown above — see [Register the model's real context window](#register-the-models-real-context-window).

> **Model responds, but edits aren't applied**
>
> Confirm you passed the target file(s) as arguments (or added them inside the interactive chat) — Aider only edits files that are in the chat's file list.

> **command not found: aider, or ModuleNotFoundError**
>
> If you used `aider-install`, confirm the installer finished and its install location is on your `PATH`. If you installed with `pip install aider-chat` directly, confirm `pip install aider` wasn't used instead — that's a different, unrelated package — and that your virtual environment is active.

> **Authentication error or 401**
>
> Confirm both `OPENAI_API_BASE` and `OPENAI_API_KEY` are exported in the same shell session Aider runs in: `echo $OPENAI_API_BASE` and `echo $OPENAI_API_KEY`.

## Additional resources

* [Aider documentation](https://aider.chat/docs/)
* [Using Aider with OpenAI models](https://aider.chat/docs/llms/openai.html)
* [Aider OpenAI-compatible API guide](https://aider.chat/docs/llms/openai-compat.html)
* [Advanced model settings](https://aider.chat/docs/config/adv-model-settings.html)
* [Supported SambaCloud models](/docs/en/models/sambacloud-models.md)