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

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:

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

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

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:

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 extracts --system-prompt and collects all --append-system-prompt occurrences into an array
• Generation: buildSystemPrompt() in packages/coding-agent/src/core/system-prompt.ts assembles the final string
• Application: AgentSession in 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.

Where does the default system prompt originate?

The default prompt is hardcoded in buildSystemPrompt() within 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 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.

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