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

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

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.

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 demonstrates the UI flow and event handling.

# 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	rpc-client.ts, rpc-mode.ts	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 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 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 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.

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