# How to Manage Configurations in PrimeAgent: Files, Environment Variables, and CLI Flags

> Master PrimeAgent configuration management. Learn to use files, environment variables, and CLI flags for optimal runtime settings with command-line options taking precedence.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-09-08

---

**PrimeAgent stores runtime settings in `~/.prime-agent` and merges configurations from JSON files, environment variables, and CLI flags, with command-line options taking the highest precedence.**

Managing runtime behavior in PrimeAgent relies on a flexible configuration system that balances persistence with flexibility. This guide walks through the three-tier configuration hierarchy implemented in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts), showing you how to customize agent behavior without modifying source code.

## Configuration Storage and Directory Structure

PrimeAgent uses a dedicated configuration directory to persist user settings. By default, this location is `~/.prime-agent`, though you can override it using the `PRIME_AGENT_DIR` environment variable.

The core configuration logic lives in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts). This module handles path resolution, automatically expands `~` to the home directory, and creates the configuration directory on first run if it does not exist.

The configuration directory typically contains these JSON files:

- **[`config.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/config.json)**: Core agent settings including default models and behavior flags
- **[`providers.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/providers.json)**: Provider-specific defaults for AI services
- **[`models.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/models.json)**: Custom model definitions and aliases

## The Three-Tier Configuration System

According to the PrimeIntellect-ai/prime-agent source code, the system merges settings from three distinct sources, allowing you to override behavior at different scopes.

### 1. Configuration Files (Persistent Defaults)

JSON files in the configuration directory provide persistent baseline settings. Edit `~/.prime-agent/config.json` to define default behavior:

```json
{
  "defaultModel": "gpt-4o-mini",
  "autoSave": true,
  "toolPrefix": "!"
}

```

### 2. Environment Variables (Session Overrides)

Environment variables override JSON file values for the current session. Use these to inject secrets or temporary changes without modifying files:

```bash
export PRIME_AGENT_DIR=/custom/config/path
export PRIME_AGENT_DEFAULT_MODEL=claude-3-opus-20240229
export OPENAI_API_KEY=sk-your-key-here
export AWS_ACCESS_KEY_ID=your-access-key

```

### 3. Command-Line Flags (Immediate Overrides)

When running the CLI via [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh), passed options take precedence over all other sources:

```bash
./prime-agent.sh --model=gpt-4o --auto-save=false

```

## Configuration Precedence and Merging Logic

The configuration loader applies a strict precedence order verified by the test suite in [`packages/coding-agent/test/config.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/config.test.ts):

1. **Command-line flags** (highest priority)
2. **Environment variables** (middle priority)
3. **JSON configuration files** (lowest priority)

When you call `loadConfig()` from [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts), the system reads the JSON base configuration, merges environment variable overrides, then applies CLI arguments. This ensures that a value supplied via a flag beats an env-var, which in turn beats the persisted JSON.

## Core Configuration API

The configuration module exposes typed helper functions that other parts of the codebase consume:

- **`getConfigPath()`**: Returns the absolute path to the main [`config.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/config.json) file
- **`loadConfig()`**: Reads the JSON, applies defaults and overrides, and returns a typed configuration object
- **`saveConfig()`**: Writes a modified configuration object back to disk

Other utilities depend on these helpers. For example, [`packages/coding-agent/src/utils/changelog.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/utils/changelog.ts) re-exports `getChangelogPath` from the config module to locate changelog files relative to the configuration directory.

## Summary

- PrimeAgent stores configurations in `~/.prime-agent` by default, managed by [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts)
- Settings merge from three sources: JSON files, environment variables, and CLI flags
- Precedence follows: CLI flags > Environment variables > JSON files
- Key functions include `getConfigPath()`, `loadConfig()`, and `saveConfig()` for programmatic access
- The system auto-creates config directories and expands `~` paths automatically

## Frequently Asked Questions

### Where does PrimeAgent store its configuration files?

By default, PrimeAgent stores configuration files in `~/.prime-agent`. You can override this location by setting the `PRIME_AGENT_DIR` environment variable before running the agent.

### How do I change the default model in PrimeAgent?

You can change the default model by editing `~/.prime-agent/config.json` and setting the `"defaultModel"` key, by exporting `PRIME_AGENT_DEFAULT_MODEL`, or by passing `--model` to the CLI. The CLI flag takes precedence if multiple methods are used simultaneously.

### What is the configuration precedence order in PrimeAgent?

PrimeAgent applies settings in the following order of priority: command-line flags (highest), environment variables (middle), and JSON configuration files (lowest). This hierarchy ensures that temporary CLI overrides never persist accidentally while allowing persistent defaults in files.

### How does PrimeAgent handle missing configuration directories?

On first run, if the configuration directory does not exist, PrimeAgent automatically creates it. The path normalization logic in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) also automatically expands `~` to the user's home directory.