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

> Explore Prime Agent modes interactive print JSON RPC and ACP Discover how these execution modes process prompts and return output for your CLI applications

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

---

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

```bash
pi

# or explicitly

pi --mode interactive

```

The implementation resides in [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
pi -p "Explain quantum computing"

# or

pi --mode text "Explain quantum computing"

```

The logic lives in [`packages/coding-agent/src/modes/print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
pi --mode json "Generate a Python function"

```

Like text mode, this uses `runPrintMode(...)` from [`print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
pi --mode rpc

```

The implementation in [`packages/coding-agent/src/modes/rpc/rpc-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) defines the protocol semantics. When selected, [`src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
pi --mode acp

```

The implementation in [`packages/coding-agent/src/modes/acp/acp-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/command-registry.ts), the accepted choices are:

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

```

Once parsed, [`src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/main.ts) acts as the mode dispatcher, routing to the appropriate runtime:

- `interactive` → `new InteractiveMode(...)`
- `text` / `json` → `runPrintMode(...)` (from [`print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/print-mode.ts))
- `rpc` → `new RpcClient(...)` (from [`rpc-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc-client.ts))
- `acp` → `new AcpMode(...)` (from [`acp-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp-mode.ts))

## Summary

- **Interactive mode** provides a full TUI for human-driven development sessions via [`interactive-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc-client.ts).
- **ACP mode** offers an advanced command protocol with multiplexing and lifecycle management via [`acp-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/args.ts) and dispatched in [`packages/coding-agent/src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/interactive/interactive-mode.ts), [`print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/print-mode.ts), [`rpc/rpc-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc/rpc-client.ts), and [`acp/acp-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp/acp-mode.ts).