# How to Set Up Custom Prompts and System Instructions for Prime Agent Sessions

> Learn to set up custom prompts and system instructions for Prime Agent sessions using three flexible methods: replace, append, or programmatic modification via extensions.

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

---

**Prime Agent supports three methods to customize system instructions: replace the entire prompt with `--system-prompt`, append context with repeatable `--append-system-prompt` flags, or programmatically modify prompts via extensions.**

Configuring custom system instructions lets you control how the underlying LLM behaves during coding sessions. In Prime Intellect's open-source agent framework, prompt customization is built into the core session lifecycle through CLI arguments and extension hooks.

## Replace the Entire System Prompt

Use `--system-prompt` when you want complete control over the model's instructions, discarding the default assistant behavior.

Run this from your terminal:

```bash
prime-agent --system-prompt "You are a senior Python developer. Answer only with code snippets."

```

The string provided becomes the sole system prompt sent to the LLM. This option is parsed in [`packages/coding-agent/src/cli/args.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts) and passed directly to the session constructor.

## Append Instructions to the Default Prompt

Use `--append-system-prompt` (repeatable) to layer additional context without losing the base prompt structure.

```bash
prime-agent \
  --append-system-prompt "You have access to a UNIX shell." \
  --append-system-prompt "Never reveal internal file paths."

```

The final assembled prompt follows this order:

1. Default prompt generated by `buildSystemPrompt()` in [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts)
2. First appended instruction
3. Second appended instruction (and so on)

This approach preserves Prime Agent's core behavioral safeguards while adding domain-specific constraints.

## Build Prompts Programmatically via Extensions

For reusable, dynamic prompt customization, create an extension that modifies `sessionOptions` before the session launches.

Here's the pattern demonstrated in [`packages/coding-agent/examples/extensions/prompt-customizer.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/examples/extensions/prompt-customizer.ts):

```typescript
import { Extension } from "@prime-intellect/prime-agent";

export const PromptCustomizer: Extension = {
  name: "prompt-customizer",
  async onSessionStart(ctx) {
    // Access existing appended prompts
    const extra = ctx.sessionOptions.appendSystemPrompt?.join("\n") ?? "";
    
    // Define your custom header
    const header = "You are an expert data scientist specializing in PyTorch.\n";
    
    // Optional: report prompt length via UI
    ctx.ui.setStatus("system-prompt", `System: ${header.length + extra.length} chars`);
    
    // Modify the base prompt directly
    ctx.sessionOptions.systemPrompt = header + (ctx.sessionOptions.systemPrompt ?? "");
    ctx.sessionOptions.appendSystemPrompt = extra ? [extra] : [];
  },
};

```

Register this extension in your Prime Agent configuration or activate it via `--extension prompt-customizer`.

## Use the JavaScript/TypeScript API Directly

When embedding Prime Agent in your own application, pass prompt options to `createAgentSessionFromServices`:

```typescript
import { createAgentSessionFromServices } from "@prime-intellect/coding-agent";

const session = await createAgentSessionFromServices({
  systemPrompt: "You are a Rust expert. Focus on memory safety.",
  appendSystemPrompt: [
    "All answers must be single-line.",
    "Do not use emojis."
  ],
});

```

The options object mirrors CLI flag names exactly, ensuring consistent behavior across interfaces.

## How Prompt Assembly Works Under the Hood

The prompt building pipeline in Prime Agent follows three stages:

- **Parsing**: [`packages/coding-agent/src/cli/args.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts) extracts `--system-prompt` and collects all `--append-system-prompt` occurrences into an array
- **Generation**: `buildSystemPrompt()` in [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts) assembles the final string
- **Application**: `AgentSession` in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) injects the completed prompt into the LLM request payload

Extensions hook into `onSessionStart` after parsing but before generation, enabling last-minute modifications.

## Summary

- **`--system-prompt`** replaces the default prompt entirely for one-off behavioral overrides
- **`--append-system-prompt`** (repeatable) layers context while preserving core instructions
- **Extensions** enable reusable, programmable prompt customization through the `onSessionStart` lifecycle hook
- **Programmatic API** accepts identical options via `createAgentSessionFromServices` for embedded deployments

## Frequently Asked Questions

### Can I combine `--system-prompt` and `--append-system-prompt`?

Yes, though `--system-prompt` takes precedence as the base. If you provide both, `--append-system-prompt` values are concatenated after your custom `--system-prompt` rather than the default. This behavior is handled in [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts).

### Where does the default system prompt originate?

The default prompt is hardcoded in `buildSystemPrompt()` within [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts). It establishes baseline assistant behavior, tool descriptions, and safety guidelines that most users extend rather than replace.

### Do appended prompts maintain their order?

Yes. Prime Agent preserves CLI argument order for `--append-system-prompt` flags. The parser in [`args.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/args.ts) collects them into a array, and `buildSystemPrompt()` iterates sequentially when concatenating.

### Can extensions modify prompts after a session starts?

No. The `onSessionStart` hook fires once during session initialization. For dynamic prompt changes mid-session, you would need to restart the session with new options or implement custom message preprocessing outside Prime Agent's standard flow.