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

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. 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 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) 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

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. The Provider, Model, and ModelOptions interfaces govern valid keys.

Complete Configuration Example

{
  "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)
• 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 with metadata including descriptions and default chords. User overrides merge into this map without requiring code changes.

Default Binding Structure

{
  "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 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. This enables dynamic behavior based on active settings.

Reading Configuration in Extensions

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

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

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

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 with sections for providers, models, ui, and extensions
• Keybindings merge user overrides into defaults from 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

---

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 and 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 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 (note the leading dot) and that JSON syntax is valid—the TUI will show a warning banner for parse errors.

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