# PrimeAgent Configuration Options: Complete Guide to Environment Variables, JSON Files, and Extension Hooks

> Explore PrimeAgent configuration options including environment variables, JSON files, and extension hooks. Master runtime overrides, UI settings, and LLM providers for enhanced control.

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

---

**PrimeAgent configuration options span three layers: `PI_*` environment variables for runtime overrides, user-wide JSON/YAML files in `~/.prime/agent/`, and per-project configs in `.prime/agent/` that merge to control LLM providers, UI settings, and keybindings.**

PrimeAgent uses a hierarchical configuration system that lets you customize everything from terminal rendering behavior to complex multi-provider LLM pipelines. This guide examines every configuration surface based on the official source code in `PrimeIntellect-ai/prime-agent`, with practical examples for each layer.

---

## Understanding the Three Configuration Layers

PrimeAgent resolves settings through a strict precedence order. Later layers override earlier ones:

1. **Environment variables** (`PI_*` prefix) — immediate runtime overrides
2. **User configuration** (`~/.prime/agent/config.json` or `$PRIME_AGENT_CODING_AGENT_DIR`) — personal defaults across all projects
3. **Project configuration** (`<repo-root>/.prime/agent/config.json`) — team-specific settings committed to version control

The merging logic is implemented in [`packages/coding-agent/src/modes/interactive/components/configuration-menu.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/components/configuration-menu.ts). Missing fields fall back to hard-coded defaults (e.g., `effort: "low"` for model reasoning levels).

---

## Environment Variable Configuration Options

All PrimeAgent environment variables use the `PI_` prefix. The resolver in [`packages/coding-agent/src/core/resolve-config-value.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/resolve-config-value.ts) scans these at startup.

### Runtime Behavior Flags

| Variable | Value | Effect |
|----------|-------|--------|
| `PI_OFFLINE` | `1` or `true` | Disables all network calls; useful for CI or air-gapped environments |
| `PI_SKIP_VERSION_CHECK` | `1` or `true` | Prevents automatic update checks |
| `PI_FULLSCREEN` | `1` or `true` | Launches TUI in full-screen mode, hiding the shell UI |
| `PI_AGENT_DIR` | path | Overrides `~/.prime/agent` base directory |
| `PI_SESSION_DIR` | path | Overrides default session storage location |
| `PI_PACKAGE_DIR` | path | Custom location for installed agent extensions |

### TUI Debugging and Rendering Options

PrimeAgent's terminal UI ([`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts)) responds to several display-related variables:

- **`PI_DEBUG_REDRAW`** — enables verbose redraw diagnostics for troubleshooting rendering glitches
- **`PI_TUI_DEBUG`** — activates extensive TUI logging throughout the render loop
- **`PI_CLEAR_ON_SHRINK`** — clears empty rows when terminal dimensions decrease, preventing visual artifacts
- **`PI_HARDWARE_CURSOR`** — forces hardware cursor mode for terminals with compatibility issues
- **`PI_TUI_WRITE_LOG`** — writes complete TUI transcript to specified path for post-mortem analysis

### Quick Example: Offline Mode with Custom Paths

```bash
PRIME_AGENT_CODING_AGENT_DIR=$HOME/.company-prime-config \
PI_OFFLINE=1 \
PI_FULLSCREEN=1 \
prime-agent

```

This launches PrimeAgent using a company-managed configuration directory, skips all network requests, and enters full-screen immediately.

---

## JSON Configuration File Structure

Both user and project configurations use identical schemas defined in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts). The `Provider`, `Model`, and `ModelOptions` interfaces govern valid keys.

### Complete Configuration Example

```json
{
  "providers": [
    {
      "id": "openai",
      "apiKey": "OPENAI_API_KEY",
      "baseUrl": "https://api.openai.com/v1"
    },
    {
      "id": "anthropic",
      "apiKey": "ANTHROPIC_API_KEY"
    },
    {
      "id": "custom-azure",
      "apiKey": "AZURE_OPENAI_KEY",
      "baseUrl": "https://my-corp.openai.azure.com"
    }
  ],
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "maxTokens": 8192,
      "temperature": 0.7,
      "effort": "high"
    },
    {
      "provider": "anthropic",
      "model": "claude-3-sonnet-20240229",
      "maxTokens": 10000,
      "temperature": 0.5
    }
  ],
  "ui": {
    "theme": "dark",
    "keybindings": {
      "app.configuration.previousTab": ["Shift+Tab"]
    }
  },
  "extensions": [
    "my-company/custom-provider",
    "my-company/extra-tools"
  ]
}

```

### Providers Section

Each provider entry requires:

- **`id`** — unique identifier referenced by models
- **`apiKey`** — literal string, environment variable name, or shell command (resolved by [`resolve-config-value.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/resolve-config-value.ts))
- **`baseUrl`** — optional endpoint override for self-hosted or regional deployments

The resolver normalizes `apiKey` values at runtime. Passing `"OPENAI_API_KEY"` (no `$` prefix) instructs PrimeAgent to read from that environment variable; a `$` prefix executes the value as a shell command.

### Models Section

Model entries bind to providers and accept these tuning parameters:

- **`provider`** — must match a defined provider `id`
- **`model`** — provider-specific model identifier
- **`maxTokens`** — response token limit
- **`temperature`** — sampling randomness (0.0 to 2.0)
- **`effort`** — reasoning level for supported models (`"low"`, `"medium"`, `"high"`)
- **`compat`** — compatibility flags for non-standard endpoints

These values populate the interactive model selector in the TUI configuration menu.

### UI and Extensions Sections

The `ui` object controls visual presentation:

- **`theme`** — `"dark"` or `"light"`
- **`keybindings`** — custom chord mappings (see next section)
- **Kitty keyboard protocol** — enable for enhanced key detection

The `extensions` array lists npm-style packages dynamically imported at startup, enabling custom providers, tools, or system prompt fragments.

---

## Keybinding Configuration Options

Default keybindings are defined in [`packages/coding-agent/src/core/keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/keybindings.ts) with metadata including descriptions and default chords. User overrides merge into this map without requiring code changes.

### Default Binding Structure

```json
{
  "ui": {
    "keybindings": {
      "app.configuration.previousTab": ["Shift+Tab"],
      "app.configuration.nextTab": ["Tab"],
      "app.toggleFullscreen": ["Ctrl+F"],
      "app.quit": ["Ctrl+Q", "Ctrl+C"]
    }
  }
}

```

Key features:

- Multiple chords per action (array format)
- Case-insensitive modifier names (`Ctrl`, `Shift`, `Alt`, `Meta`)
- Automatic TUI menu updates when configuration changes

The [`keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.ts) source defines descriptions like `"Select previous configuration tab"` that appear in the interactive help overlay.

---

## Extension Access to Configuration

Extensions receive the merged configuration through `systemPromptOptions` as documented in [`packages/coding-agent/docs/extensions.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/extensions.md). This enables dynamic behavior based on active settings.

### Reading Configuration in Extensions

```typescript
// src/extensions/my-extension.ts
export async function activate(
  systemPromptOptions: SystemPromptOptions
) {
  const { models, providers, ui } = systemPromptOptions;
  
  // Conditionally register tools based on available providers
  if (providers.some(p => p.id === 'web-search-api')) {
    systemPromptOptions.tools.push({
      name: 'searchWeb',
      description: 'Execute web search via configured provider',
      parameters: { query: 'string' }
    });
  }
  
  // Adjust system prompt based on theme
  const themeContext = ui.theme === 'dark' 
    ? 'User prefers dark interface; minimize bright code examples.'
    : '';
}

```

Extensions can also register providers dynamically, effectively extending the configuration schema at runtime.

---

## Configuration Resolution Flow

The complete loading sequence in [`packages/coding-agent/src/modes/interactive/components/configuration-menu.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/components/configuration-menu.ts):

1. **Environment scan** — all `PI_*` variables captured
2. **User config load** — from `~/.prime/agent/config.json` (or `$PRIME_AGENT_CODING_AGENT_DIR`)
3. **Project config load** — from `<cwd>/.prime/agent/config.json`
4. **Deep merge** — project values override user values; arrays typically replace rather than append
5. **Default application** — unspecified fields use hard-coded defaults
6. **UI exposure** — `ConfigurationMenuComponent` renders editable view

The test suite in [`packages/coding-agent/test/configuration-menu.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/configuration-menu.test.ts) validates this merging behavior across edge cases like nested object conflicts and invalid schema detection.

---

## Practical Configuration Recipes

### Per-Project Model Locking

Commit this to enforce consistent models across your team:

```json
// .prime/agent/config.json
{
  "models": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.2,
      "effort": "high"
    }
  ],
  "ui": {
    "keybindings": {
      "app.agent.sendMessage": ["Ctrl+Enter"]
    }
  }
}

```

### CI/CD Non-Interactive Mode

```bash
export PI_OFFLINE=1
export PI_SKIP_VERSION_CHECK=1
export PI_AGENT_DIR=/tmp/prime-agent-ci
mkdir -p "$PI_AGENT_DIR"
cat > "$PI_AGENT_DIR/config.json" << 'EOF'
{
  "providers": [{"id": "mock", "apiKey": "unused", "baseUrl": "http://localhost:9999"}],
  "models": [{"provider": "mock", "model": "ci-model"}]
}
EOF
prime-agent --batch < tasks.json

```

---

## Summary

- **PrimeAgent configuration options** operate across three layers: `PI_*` environment variables, user JSON files in `~/.prime/agent/`, and per-project configs in `.prime/agent/`
- **Environment variables** provide immediate runtime control over networking, display, and directory locations
- **JSON configuration** follows schemas defined in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) with sections for `providers`, `models`, `ui`, and `extensions`
- **Keybindings** merge user overrides into defaults from [`packages/coding-agent/src/core/keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/keybindings.ts)
- **Extensions** access full configuration via `systemPromptOptions` for dynamic provider and tool registration
- **Resolution order** runs environment → user → project → defaults, implemented in [`packages/coding-agent/src/modes/interactive/components/configuration-menu.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/components/configuration-menu.ts)

---

## Frequently Asked Questions

### How do I override just one setting without editing JSON files?

Use the corresponding `PI_*` environment variable. For example, `PI_OFFLINE=1` forces offline mode without touching any configuration file. Variables are processed first and take precedence over all file-based settings.

### Can I use YAML instead of JSON for configuration files?

Yes. PrimeAgent accepts both [`config.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/config.json) and [`config.yaml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/config.yaml) (or `.yml`) in any configuration directory. The parser detects format by extension.

### Where should I store sensitive API keys?

Reference environment variable names in your JSON rather than embedding literal values: `"apiKey": "OPENAI_API_KEY"`. The resolver in [`packages/coding-agent/src/core/resolve-config-value.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/resolve-config-value.ts) will read the actual value at runtime. For shell command execution, prefix with `$`: `"apiKey": "$security get-secret openai"`.

### Why aren't my project configuration changes appearing?

PrimeAgent loads project configuration from the current working directory at startup. If you launch from a different path, the project config won't load. Also verify the file is at [`.prime/agent/config.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.prime/agent/config.json) (note the leading dot) and that JSON syntax is valid—the TUI will show a warning banner for parse errors.