# JSON/RPC Client Modes vs TUI Execution in Prime Agent: A Technical Comparison

> Compare JSON/RPC client modes and TUI execution in Prime Agent. Understand raw streams, typed APIs, and interactive terminal experiences for your AI agent.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: technical-comparison
- Published: 2026-09-05

---

**Prime Agent offers three distinct execution modes: JSON client for raw line-based streams, RPC client for typed programmatic APIs, and TUI for full interactive terminal experiences.**

Prime Agent is a flexible coding agent from PrimeIntellect-ai that supports multiple front-end interfaces depending on your automation needs. Understanding the differences between **JSON/RPC client modes** and **TUI execution** helps you choose the right integration strategy for scripts, applications, or human-driven workflows.

## JSON Client Mode: Raw Programmatic Streams

The **JSON client mode** (`--mode json`) provides a headless, line-delimited interface where the agent communicates exclusively through **JSON-Lines** on stdin and stdout.

- Every event, response, and error is a single JSON object terminated by a newline
- No UI renders—the host process parses the stream directly
- Execution stops when stdin closes, giving the host full lifecycle control

This mode is implemented in [`packages/coding-agent/src/modes/rpc/jsonl.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/rpc/jsonl.ts), which handles the low-level reader/writer logic for the JSON-Lines transport.

## RPC Client Mode: Typed Programmatic API

The **RPC client mode** (`--mode rpc`) wraps the same JSON-Lines stream with a structured request/response envelope and exposes a convenient **TypeScript API** through the `RpcClient` class.

### Key Differences from JSON Mode

| Aspect | JSON Client | RPC Client |
|--------|-------------|------------|
| Interface | Raw stdin/stdout streams | `RpcClient` class with typed methods |
| Message format | Plain JSON objects | Wrapped with `id`, `type`, and other metadata |
| Lifecycle | Host-managed | Explicit `start()` and `stop()` calls |
| Helper methods | None built-in | `prompt()`, `refine()`, `getStderr()`, event buffering |

The `RpcClient` class 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) spawns the agent as a child process and manages the communication channel. The RPC mode entry point on the daemon side is [`packages/coding-agent/src/modes/rpc/rpc-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/rpc/rpc-mode.ts).

```typescript
import { RpcClient } from "@prime-agent/coding-agent/src/modes/rpc/rpc-client.js";

const client = new RpcClient({ provider: "openai", model: "gpt-4" });
await client.start();
await client.prompt("Refactor this function to use async/await");
client.onEvent((ev) => console.log(ev));
await client.stop();

```

## TUI Execution: Interactive Terminal Interface

**TUI execution** runs when no `--mode` flag is provided, launching a full-screen, mouse-aware terminal interface built on [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts).

### How TUI Differs from JSON/RPC Modes

- The same JSON-Lines protocol runs internally, but the **TUI package consumes those events** to render panes, editors, and tool panels
- Captures `Ctrl-C`/`Esc` for graceful shutdown rather than relying on stream closure
- Provides streaming output visualization, tool selection, and direct prompt entry

The TUI test harness in [`packages/tui/test/chat-simple.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/test/chat-simple.ts) demonstrates the UI flow and event handling.

```bash

# Launch interactive TUI—no flags needed

npx prime-agent

```

## Architectural Comparison

| Aspect | JSON Client | RPC Client | TUI |
|--------|-------------|------------|-----|
| Entry point | Direct binary with `--mode json` | Binary spawns itself with `--mode rpc` | Binary runs modeless |
| Main source files | [`jsonl.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/jsonl.ts) | [`rpc-client.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc-client.ts), [`rpc-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rpc-mode.ts) | [`tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tui.ts) |
| Typical use | Shell pipelines, CI scripts | Node.js application integration | Human operators |
| Output visibility | Raw JSON to stdout | Hidden by client wrapper | Rendered terminal UI |

## When to Use Each Mode

- **JSON client**: Simple automation, Unix-style pipelines, language-agnostic integrations
- **RPC client**: Node.js services needing robust error handling, request correlation, and type safety
- **TUI execution**: Development workflows, debugging, or any scenario requiring visual feedback and manual intervention

## Summary

- **JSON client mode** exposes raw JSON-Lines streams for minimal-overhead programmatic control
- **RPC client mode** adds a typed `RpcClient` wrapper with structured message envelopes and lifecycle management
- **TUI execution** transforms the same underlying protocol into a rich interactive terminal experience
- All three modes share the core [`jsonl.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/jsonl.ts) transport layer, differing only in how the host consumes the event stream

## Frequently Asked Questions

### Can I switch between modes without reinstalling Prime Agent?

Yes. All modes are built into the same binary. Launch with `--mode json`, `--mode rpc`, or omit the flag entirely for TUI. The underlying agent core remains identical—only the interface layer changes.

### Does the RPC client add significant overhead compared to raw JSON?

No. The `RpcClient` 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) uses the same JSON-Lines transport. The overhead is minimal framing metadata and a thin API wrapper; the I/O characteristics are nearly identical.

### Can I drive the TUI programmatically?

Not designed for that purpose. The TUI in [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) owns the terminal and input handling. For programmatic control, use RPC client mode instead, or pipe JSON to the JSON client mode.

### What happens to JSON output when running in TUI mode?

The JSON objects still stream internally, but the TUI renderer consumes them before they reach stdout. No raw JSON appears in your terminal—events become visual updates, progress indicators, and rendered content panels.