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

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, 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. 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: Core agent settings including default models and behavior flags
• providers.json: Provider-specific defaults for AI services
• 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:

{
  "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:

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, passed options take precedence over all other sources:

./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:

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, 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 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 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
• 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 also automatically expands ~ to the user's home directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}