# How to Customize the Behavior of PrimeAgent: A Complete Configuration Guide

> Customize PrimeAgent behavior with environment variables, CLI flags, custom prompts, themes, tool definitions, and provider settings. Tailor its runtime without modifying source code.

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

---

**PrimeAgent offers multiple configuration layers—including environment variables, CLI flags, custom prompts, themes, tool definitions, and provider settings—that allow you to tailor its runtime behavior without modifying core source code.**

PrimeAgent is an open-source coding agent from **PrimeIntellect-ai/prime-agent** designed with extensibility at its core. You can customize the behavior of PrimeAgent through a layered configuration system that spans environment variables, JSON configuration files, and TypeScript modules. This guide examines the specific files and APIs that control each customization point, from low-level runtime settings to high-level UI theming.

## Environment and Global Configuration

The foundation of PrimeAgent customization starts with [`packages/coding-agent/src/config.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.js), which handles environment variable loading and global settings. The system recognizes **`$AGENT_DIR`** as the base directory for all agent data and configuration files. You can define API keys, default models, and daemon socket paths through standard `.env` files or shell environment variables.

Create a `.env` file in your repository root or `$AGENT_DIR` to configure providers:

```bash

# .env

OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXX
ANTHROPIC_API_KEY=sk-ant-XXXXXXXXXXXXXXXX

```

PrimeAgent automatically detects these keys via the environment API key handler and makes the providers selectable with the `/login` command.

## CLI Flags and Session Commands

Runtime behavior is controlled through commands documented in [`packages/coding-agent/docs/usage.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/usage.md). The CLI supports session management flags like **`--resume <id>`** to restore saved states, while interactive commands such as `/autonomous`, `/goal`, `/refine`, and `/heartbeat` adjust agent behavior during execution.

These flags integrate with the configuration loader to override defaults on a per-session basis. For example, you can limit autonomous operation depth or refine the current goal without restarting the daemon process.

## Customizing System Prompts and Memory

The agent's personality and instructions can be reshaped via custom prompt configurations. As demonstrated in [`packages/coding-agent/test/system-prompt.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/system-prompt.test.ts), you can supply a JSON configuration with **`customPrompt`**, **`appendSystemPrompt`**, or a **`custom_memory`** object to prepend or append content to the base system prompt.

Create a custom prompt configuration file:

```json
// $AGENT_DIR/custom-prompt.json
{
  "customPrompt": "You are a specialist in data-visualization. Always produce Plotly charts.",
  "appendSystemPrompt": "\n# Remember: keep responses concise."

}

```

Launch the session with `prime-agent --prompt-config $AGENT_DIR/custom-prompt.json` or set `PRIME_PROMPT_CONFIG` in your `.env` file to apply the configuration automatically.

## Theming and UI Appearance

Visual customization is handled through JSON theme files stored in **`$AGENT_DIR/themes/<name>.json`**. The expected schema is documented in [`packages/coding-agent/test/theme-export.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/theme-export.test.ts), supporting properties like `background`, `foreground`, and `accent` colors.

Create a custom theme file:

```json
// $AGENT_DIR/themes/solarized-dark.json
{
  "name": "solarized-dark",
  "background": "#002b36",
  "foreground": "#839496",
  "accent": "#b58900"
}

```

Activate your theme by launching with `prime-agent --theme solarized-dark`. The TUI reloads theme configurations on the fly, allowing you to iterate on color schemes without restarting the agent.

## Tool Definitions and Custom Renderers

PrimeAgent allows you to define custom tools by implementing the **`ToolDefinition`** interface. The test file [`packages/coding-agent/test/tool-execution-component.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/tool-execution-component.test.ts) shows how to create tools with custom `renderCall` and `renderResult` methods that control how tool interactions appear in the TUI.

Define a custom tool with specialized rendering:

```typescript
// my-tools/custom_tool.ts
import { ToolDefinition, Text } from "prime-agent";

export const customTool: ToolDefinition = {
  name: "custom_tool",
  description: "Shows a custom call/result pair",
  renderCall: (ctx) => new Text(`⚙️ Call: ${ctx.input}`, 0, 0),
  renderResult: (ctx) => new Text(`✅ Result: ${ctx.output}`, 0, 0),
};

```

Register these tools through the `--tools` CLI argument or by importing them into your session's tool list. This approach allows you to create visual indicators or formatted output specific to your workflow.

## TUI Components and Key Bindings

Keyboard shortcuts and editor behavior are configurable through **[`packages/tui/src/keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keys.ts)** or custom keybinding modules. For advanced UI customization, **[`packages/tui/src/editor-component.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/editor-component.ts)** defines the interface for plugging in alternative editor components, enabling integration with vim, emacs, or custom text widgets.

Override default keybindings with a custom module:

```typescript
// $AGENT_DIR/keybindings.ts
export const MY_KEYBINDINGS = {
  "Ctrl-O": "openFile",
  "Ctrl-S": "saveFile",
};

```

Run with `prime-agent --keybindings $AGENT_DIR/keybindings.ts` to apply your custom shortcuts. Custom components must implement the editor interface to handle input and rendering within the terminal UI.

## Adding Custom LLM Providers

To integrate new LLM backends, modify **[`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts)** to define provider-specific options and register the implementation in **[`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts)**. The [`packages/ai/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/README.md) documentation outlines the registration steps and option struct requirements.

This architecture allows PrimeAgent to support proprietary or self-hosted models alongside built-in providers. The configuration object bubbles through the daemon, worker, and IPython kernel as shown in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md), ensuring every component respects the same provider settings.

## Summary

- Use **[`packages/coding-agent/src/config.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.js)** and `.env` files for global environment and API key configuration
- Control session behavior via CLI flags like `--resume` and interactive commands documented in [`packages/coding-agent/docs/usage.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/usage.md)
- Override system prompts using JSON configs with `customPrompt` and `appendSystemPrompt` fields as tested in [`packages/coding-agent/test/system-prompt.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/system-prompt.test.ts)
- Deploy custom themes by placing JSON files in `$AGENT_DIR/themes/` and activating with `--theme`
- Extend functionality through custom **`ToolDefinition`** implementations with specialized renderers
- Customize the TUI through [`packages/tui/src/keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keys.ts) or by implementing the editor interface from [`packages/tui/src/editor-component.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/editor-component.ts)
- Add new LLM providers by extending types in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) and registering in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts)

## Frequently Asked Questions

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

Set the model preference through environment variables in your `.env` file or use the `/login` command to switch between configured providers. The configuration loader in [`packages/coding-agent/src/config.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.js) processes these settings at startup, making models from OpenAI, Anthropic, or custom providers available for selection.

### Can I customize the appearance of tool execution in the terminal?

Yes, by defining a custom **`ToolDefinition`** with `renderCall` and `renderResult` methods as shown in [`packages/coding-agent/test/tool-execution-component.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/tool-execution-component.test.ts). These methods return Text components that control how tool calls and results display in the TUI, allowing you to create visual indicators or formatted output specific to your workflow.

### Where should I place custom theme files for PrimeAgent?

Place JSON theme files in **`$AGENT_DIR/themes/<name>.json`**, following the schema demonstrated in [`packages/coding-agent/test/theme-export.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/theme-export.test.ts). Activate your theme by launching with `prime-agent --theme <name>` or reload themes dynamically during a session.

### Is it possible to add custom keyboard shortcuts to the PrimeAgent TUI?

Yes, you can override default keybindings by supplying a custom TypeScript module that exports key mappings, or by modifying [`packages/tui/src/keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/keys.ts) directly. For complex editor behavior, implement the editor interface defined in [`packages/tui/src/editor-component.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/editor-component.ts) to handle custom input methods and rendering logic.