Prime Agent Modes Explained: Interactive, Print, JSON, RPC, and ACP

Prime Agent supports five distinct execution modes—Interactive, Print (text or JSON), RPC, and ACP—that control how the CLI processes prompts and returns output.

The PrimeIntellect-ai/prime-agent repository provides a flexible command-line interface that adapts to different workflows, from human-friendly terminal UIs to machine-readable JSON streams. Each Prime Agent mode determines whether the tool runs interactively, executes a single prompt, or operates as a programmable server.

Interactive Mode (Default TUI)

Interactive mode launches a full-screen Text-User-Interface (TUI) where users type prompts, view live streaming assistant messages, browse conversation history, and execute slash-commands. This is the default behavior when invoking the pi command without additional flags.

Invoke via:

pi

# or explicitly

pi --mode interactive

The implementation resides in packages/coding-agent/src/modes/interactive/interactive-mode.ts, which handles input capture, message rendering, and history management. When the dispatcher in src/main.ts detects interactive mode, it instantiates new InteractiveMode(...) to manage the session lifecycle.

Print Mode: Text and JSON Output

Print mode executes a single prompt and exits immediately, making it ideal for scripting and automation. The mode branches into two output formats controlled by the --mode argument.

Text Mode (Single-Shot Plain Text)

Text mode sends the prompt to the agent, waits for completion, and prints only the final response as plain text to STDOUT.

Invoke via:

pi -p "Explain quantum computing"

# or

pi --mode text "Explain quantum computing"

The logic lives in packages/coding-agent/src/modes/print-mode.ts within the runPrintMode(...) function.

JSON Mode (Structured Event Streaming)

JSON mode streams all raw events—including session headers, individual tokens, tool calls, and final responses—as newline-delimited JSON (NDJSON). This format enables programmatic consumption of the agent's internal reasoning steps.

Invoke via:

pi --mode json "Generate a Python function"

Like text mode, this uses runPrintMode(...) from print-mode.ts, but serializes the event stream to JSON instead of extracting final text.

RPC Mode

RPC mode launches the agent as a child process that communicates over STDIO using a lightweight Remote-Procedure-Call protocol. External programs can drive the agent by sending JSON-encoded requests and receiving structured replies, enabling custom front-ends or automated testing frameworks.

Invoke via:

pi --mode rpc

The implementation in packages/coding-agent/src/modes/rpc/rpc-client.ts defines the protocol semantics. When selected, src/main.ts instantiates new RpcClient(...) to handle message parsing and response serialization.

ACP (Agent Command Protocol) Mode

ACP mode provides a bidirectional, command-oriented protocol that is strictly richer than RPC. It supports multiplexed commands, real-time progress updates, and explicit termination signals for long-running actions. This mode powers the daemon-based supervisor architecture and external tools requiring fine-grained control over the agent's lifecycle.

Invoke via:

pi --mode acp

The implementation in packages/coding-agent/src/modes/acp/acp-mode.ts manages the complex state machine for command multiplexing. The dispatcher creates new AcpMode(...) when this protocol is requested.

How Mode Selection Works Internally

The CLI argument parser in packages/coding-agent/src/cli/args.ts validates the --mode flag against allowed values. As registered in packages/coding-agent/src/cli/command-registry.ts, the accepted choices are:

["--mode <text|json|rpc|acp|daemon>", "Select the output mode (default: text)"]

Once parsed, src/main.ts acts as the mode dispatcher, routing to the appropriate runtime:

• interactive → new InteractiveMode(...)
• text / json → runPrintMode(...) (from print-mode.ts)
• rpc → new RpcClient(...) (from rpc-client.ts)
• acp → new AcpMode(...) (from acp-mode.ts)

Summary

• Interactive mode provides a full TUI for human-driven development sessions via interactive-mode.ts.
• Print text mode returns single-shot plain text responses for shell scripting.
• Print JSON mode streams structured events as NDJSON for programmatic parsing.
• RPC mode enables JSON-RPC over STDIO for simple programmatic control via rpc-client.ts.
• ACP mode offers an advanced command protocol with multiplexing and lifecycle management via acp-mode.ts.

Frequently Asked Questions

What is the default mode when running the Prime Agent CLI?

The default mode is interactive, which launches the full-screen TUI when you execute pi without specifying --mode. This behavior is hardcoded in the entry point logic of src/main.ts.

How do I programmatically consume Prime Agent output?

Use JSON print mode (pi --mode json) to receive newline-delimited JSON events containing every token and tool call. For bidirectional control, use RPC mode for simple request-response patterns or ACP mode for complex workflows requiring progress updates and command multiplexing.

What is the difference between RPC mode and ACP mode?

RPC mode provides a basic request-response protocol over STDIO suitable for simple automation, implemented in rpc-client.ts. ACP mode (Agent Command Protocol) is a richer, bidirectional protocol supporting multiplexed commands, progress streaming, and explicit lifecycle management, making it suitable for daemon supervisors and long-running tasks.

Where is the mode selection logic implemented in the source code?

Mode selection is parsed in packages/coding-agent/src/cli/args.ts and dispatched in packages/coding-agent/src/main.ts. Each mode's runtime is implemented in its respective file under packages/coding-agent/src/modes/, such as interactive/interactive-mode.ts, print-mode.ts, rpc/rpc-client.ts, and acp/acp-mode.ts.

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