Building a native terminal for AI coding agents in Rust + GPUI

Arthur Jean built Paneflow, a native terminal workspace for AI coding agents, using Rust and the GPUI framework. The tool is designed to address the limitations of traditional terminal multiplexers by offering git-aware workspaces, live dev-server detection, session restore, and a JSON-RPC control plane for programmatic agent management. The author emphasizes that for a terminal emulator, the UI framework must handle glyph rasterization directly, which led to the rejection of Electron and Tauri in favor of a native Rust approach.

Author: Arthur Jean, solo indie maker. More on paneflow.dev and arthurjean.com . Repo: github.com/ArthurDEV44/paneflow . MIT licensed. I spend my days running Claude Code, Codex, and OpenCode in parallel panes. Different agents on different branches, each with their own dev server, all in one terminal. tmux can do this, but every multiplexer I tried treated agents the same as any other shell process: no first-class branch context, no live dev-server detection, no session restore that survives a reboot, no programmatic way for an external tool to drive the editor. I built Paneflow https://paneflow.dev because I needed it. This is a post-mortem, not a launch post. Paneflow is a native terminal workspace, splits, panes, branch-aware workspaces, session restore, built in pure Rust on top of Zed's GPUI framework https://zed.dev and the upstream alacritty terminal crate. It started as a port of cmux https://github.com/manaflow-ai/cmux , a macOS-only Swift/AppKit project, and the Rust rewrite forced a string of decisions I had no good intuition for at the start. I want to walk through the ones that mattered: which UI frameworks I tried and rejected, how the GPUI/alacritty boundary actually looks, how dev-server detection works under the hood, the N-ary layout tree that replaced binary splits, the cross-platform PTY plumbing, the JSON-RPC control plane that makes agents first-class, and four lessons that surprised me. If you take one thing away, take this: for a terminal emulator, the UI framework must own glyph rasterization. Everything else flows from that single constraint. Why a terminal for AI coding agents VSCode and classic IDEs matter less and less when you work with Claude Code or Codex. The work has shifted: instead of typing code in an editor, I'm directing agents from a shell. One pane runs Claude Code working on a feature branch. Another runs Codex doing a refactor on a second branch. A third tails the dev server. A fourth has notes and a markdown viewer open. The terminals we know weren't designed for this. They render a grid, they pipe stdin/stdout, they let you split. They don't know which workspace is on which branch, which pane has a server bound to port 5173, which session restored from yesterday's setup. Every multiplexer treats every pane identically, so the orchestration cognitive load lands entirely on you. Paneflow is built exactly for this mode. Workspaces are git-aware: each one knows its branch and the sidebar surfaces it. Dev-server detection scans for Vite, Next.js, Webpack, and others, then resolves their actual listening ports through the kernel, not by trusting whatever the framework printed. AI agent buttons in the tab bar launch Claude Code, Codex, or OpenCode in the active pane with one keystroke. A local JSON-RPC server exposes the editor so external tools can drive workspaces, send keystrokes, or post agent lifecycle events programmatically. Sessions save and restore so closing the app and reopening it tomorrow lands you exactly where you left off. Side-by-side comparisons vs cmux, WezTerm, iTerm2, and Warp at paneflow.dev/compare https://paneflow.dev/compare . The rest of this post is about how the engine works. Why not Electron, why not Tauri The first option I evaluated was Electron + xterm.js. The architecture review rejected it immediately: "Electron: heavy memory footprint contradicts cmux's 'not Electron' philosophy ." cmux was conceived as a native, low-RAM tool, and the whole point of porting it was to keep that property on Linux and Windows. So Electron was out without debate. The second option was Tauri https://tauri.app , and I genuinely spent time there. I started a real implementation, laid out the architecture, got the first interactions running. On paper it held up: lighter binary than Electron, frontend in whichever stack you want, Rust backend for the sensitive logic, cross-platform distribution with minimal friction. But as I went deeper, two things sharpened up. First, the technical blocker. The webview API surface is too narrow for the kind of low-level keyboard, IME, and input grabbing a multiplexer needs. Everything you take for granted in a native terminal precise key chords without a JS intermediary, clean Asian IME, focus management between panes without a round-trip to the webview becomes a workaround or a hole. For an editor or a typical productivity app, those trade-offs are acceptable. For a terminal that has to absorb every keystroke at sub-frame latency, they are not. Second, and this is what really decided it: I wanted to build something new, not wrap a webview with one more layer on top. When Zed https://zed.dev started, they could have built on Electron, on Tauri, on GTK or Qt. They chose to write their own framework, GPUI https://github.com/zed-industries/zed/tree/main/crates/gpui , because no existing option could deliver what they wanted for code editors: dense GPU-accelerated text rendering at 120 fps with sub-frame keystroke-to-pixel latency. The result speaks for itself. Zed's bet for IDEs applies word for word to terminals. Not wrap, not lean on a portability layer that flattens every feature to the lowest common denominator, but build on a foundation designed specifically for dense, native, low-latency text rendering. The difference with Zed is that I did not have to write the framework: they had already done it. GPUI owns text rendering end-to-end: shaping, atlasing, GPU draw, the lot. There is no "bring your own text path," there is no webview to work around. Adopting GPUI meant choosing the "dedicated native framework" approach over "webview with a Rust shell." Architectural ambition over ecosystem ease. That was the decision. The GPUI mental model A two-paragraph briefing so the rest of this post reads cleanly. Mutable state in GPUI lives in Entity<T . You mutate through a Context<T , you signal observers with cx.notify , you spawn async work with cx.spawn . Views implement Render and return a div tree built with a Tailwind-shaped builder API. Every observable thing in Paneflow the app root, the cursor blink phase, every terminal view, every pane, the sidebar is an Entity<T . Keyboard input flows through GPUI's actions macro, which generates zero-sized typed structs in the paneflow namespace SplitHorizontally , LayoutTiled , UndoClosePane , ... that the framework dispatches through the focus chain. Adding a keybinding is one struct, one handler, one bind. GPUI's repaint is diff-based and dependency-tracked at observation time, so a cx.notify only invalidates the rects that subscribed. That's the whole surface area you need to follow what comes next. Plugging in alacritty terminal The terminal grid itself is alacritty terminal = "0.26" from crates.io src-app/Cargo.toml:26 . I migrated off Zed's internal fork as soon as 0.26 was released. Staying on a vendored fork of someone else's editor's fork of alacritty was not a sustainable path. The shared state is unsurprising: Arc<FairMutex<Term<ZedListener . ZedListener is a thin newtype wrapping a futures UnboundedSender<AlacEvent . alacritty's Term calls listener.send event event whenever the grid mutates; the receiver lives on the GPUI main thread. What is surprising is that Paneflow does not use alacritty's EventLoop::spawn . That helper is convenient for embedded-terminal-in-an-editor cases, but a multiplexer wants finer control over OSC scanning, synchronized output, and shutdown. Instead, every terminal session runs two hand-rolled detached threads src-app/src/terminal/pty loops.rs : - pty reader loop reads PTY bytes into a 4096-byte buffer, runs OSC scanners OSC 7 for CWD, OSC 133 for prompt boundaries, XTVersion for shell identification , advances the VTE Processor against the locked Term , and emits a single wakeup when bytes were processed outside a DEC 2026 synchronized-output window. - pty message loop receives Msg from a PtyNotifier over std::sync::mpsc and writes input or resize commands back to the PTY master. The reader's hot path is roughly this: js let mut term = term.lock ; processor.advance &mut term, &buf ..n ; drop term ; if processor.sync bytes count < n { listener.send event AlacEvent::Wakeup ; } The check on sync bytes count is the synchronized-output coalesce: a TUI like neovim or btop announces "I'm about to draw a frame, hold the wakeup until I'm done," and we honor it. Without that check, a busy TUI would generate hundreds of wakeups per logical frame and the GPU would render them all. On the GPUI side, the TerminalView 's cx.spawn event loop drains the wakeup channel for up to 4 ms max 100 events , then issues one cx.update and one cx.notify . That's the keystroke-to-pixel path: shell writes, reader thread, VTE, wakeup, 4 ms batcher, cx.notify , GPUI diff repaint, atlas draw. There's a PANEFLOW LATENCY PROBE=1 env var on debug builds that traces this path end-to-end, which is the right tool when you suspect the batcher is doing something wrong. Detecting dev servers from /proc/net/tcp One of the things I wanted from the start was a sidebar that knows what's running in each workspace. If a pane is hosting a Vite dev server on port 5173, I want a one-click open. If a Next.js app is on 3000, same. The naive solution is to regex the terminal output: catch "vite dev: http://localhost:5173 http://localhost:5173 " when the framework prints it. That works half the time. The other half, the line scrolls off, or the framework prints to stderr in a way the OSC scanner missed, or the user piped it through tee and the announcement never came back. So Paneflow does both. src-app/src/terminal/service detector.rs regex-matches a list of 22 framework signatures against the terminal output as a fast, immediate signal: js const FRAMEWORKS: & &str, &str, bool = & "next.js", "Next.js", true , "turbopack", "Next.js", true , "vite", "Vite", true , "nuxt", "Nuxt", true , "remix", "Remix", true , "astro", "Astro", true , "webpack-dev-server", "Webpack", true , "uvicorn", "uvicorn", false , "flask", "Flask", false , "axum", "Axum", false , // ... ; The third tuple element is is frontend : frontend frameworks get a clickable URL in the sidebar; backend ones get a status badge. The ground truth, though, comes from the kernel. src-app/src/workspace/ports.rs walks the PID tree of every workspace and queries listening sockets directly. On Linux, that means parsing /proc/net/tcp and /proc/net/tcp6 : php cfg target os = "linux" pub fn detect ports pids: & u32 - Vec<u16 { let mut all pids = HashSet::new ; for &pid in pids { for descendant in collect descendant pids pid { all pids.insert descendant ; } } let owned inodes = collect socket inodes &all pids ; let mut ports = Vec::new ; for path in & "/proc/net/tcp", "/proc/net/tcp6" { if let Ok content = read capped path, 256 1024 { for line in content.lines .skip 1 { let fields: Vec<&str = line.split whitespace .collect ; if fields 3 = "0A" { continue; } // 0A = TCP LISTEN if let Some port hex = fields 1 .split ':' .next back && let Ok port = u16::from str radix port hex, 16 && let Ok inode = fields 9 .parse::<u64 && owned inodes.contains &inode { ports.push port ; } } } } ports.sort unstable ; ports.dedup ; ports } The walk is in two steps. First, collect descendant pids BFS-walks /proc/{pid}/task/{pid}/children to gather every descendant of the workspace's shell PID. Then collect socket inodes reads /proc/{pid}/fd/ for each PID, looking for symlinks of the shape socket: <inode , and accumulates the inode set. Finally, /proc/net/tcp is parsed line-by-line; column 3 is the TCP state hex 0A is TCP LISTEN , columns 1 and 9 are the local address and socket inode. We keep only ports whose inode is owned by our PID set, so we don't surface the SSH listener on port 22 just because someone happens to have a shell open. macOS doesn't have /proc , so the branch there uses libproc : php cfg target os = "macos" pub fn detect ports pids: & u32 - Vec<u16 { use libproc::libproc::file info::{ListFDs, ProcFDType, pidfdinfo}; use libproc::libproc::net info::{SocketFDInfo, SocketInfoKind, TcpSIState}; use libproc::libproc::proc pid::listpidinfo; // ... for each pid in the workspace tree: // listpidinfo::<ListFDs pid to get the FD table // filter to ProcFDType::Socket // pidfdinfo::<SocketFDInfo pid, fd to get the socket info // keep entries where soi kind == IPv4 and tcpsi state == LISTEN } Windows is currently a stub: detect ports returns an empty Vec and the sidebar falls back to the regex path. The native Win32 API is GetExtendedTcpTable , which is on the roadmap. The combination matters. Regex catches the immediate "Vite started" line within the second; /proc catches anything actually listening even when the announcement was lost. Both paths feed into the same sidebar entity via GPUI's EventEmitter , which fires ActivityBurst events on PTY activity rather than polling see lesson 3 below . The N-ary layout tree My first attempt at panes used a binary SplitNode enum: Leaf | Split { direction, ratio, first, second } . It worked. It also produced terrible UX the moment you wanted three equal columns. You had to nest a split inside a split, and a 50/50 split-of-a-50/50 is a 25/75, not 33/33. Every preset became a special case. Every drag-resize on the outer divider produced visually inconsistent inner sizes. I rewrote the tree as an N-ary structure. The relevant types live in src-app/src/layout/tree.rs:42-58 : pub struct LayoutChild { pub node: LayoutTree, pub ratio: Rc<Cell<f32 , pub computed size: Rc<Cell<f32 , } pub enum LayoutTree { Leaf Entity<Pane , Container { direction: SplitDirection, children: Vec<LayoutChild , drag: Rc<Cell<Option<DragState , container size: Rc<Cell<f32 , }, } Three things to call out: - A container holds any number of children. Three columns is one container with three children, not a binary tree of containers. Drag-resizing across siblings becomes a single ratio rebalance, not a recursive walk. Vec<LayoutChild , not Box<Self , Box<Self . - GPUI's render tree is single-threaded, and the layout body is rebuilt on every Rc<Cell<f32 for ratios. Render call. Putting ratios behind Rc<Cell<f32 lets the render closure read the ratio while the drag handler writes it, with no Arc and no lock. This is one of the patterns I underestimated coming in: GPUI's "no Arc<Mutex<... for UI state" rule pushes you toward Rc<Cell<... and Rc<RefCell<... everywhere, and that's correct. - Constants are deliberately small. MIN PANE SIZE = 80.0 tree.rs:62 , DIVIDER PX = 4.0 tree.rs:60 , max 32 panes per workspace, max 20 workspaces. The clamp on resize is dynamic, MIN PANE SIZE / container size at drag time, not a fixed range. Four presets ship today: even h and even v built from the same from panes equal constructor , main vertical 60% left, 40% stacked right , and tiled the tmux algorithm: increment rows then cols alternately until rows cols = N , then fill row-by-row . Rendering emits GPUI flex divs with flex basis relative ratio per child, and the divider is a 4 px element with a drag listener that rewrites two adjacent ratios in place. Cross-platform PTY via portable-pty Paneflow uses portable-pty = "0.8" https://crates.io/crates/portable-pty src-app/Cargo.toml:29 . Its native pty system resolves to ConPTY on Windows and openpty on Unix with no caller-side conditional compilation. The PtyBackend trait in src-app/src/pty.rs has exactly one production implementation, PortablePtyBackend , and the call site has zero cfg guards. The two I/O thread loops in pty loops.rs are pure std::io::Read / Write over the boxed handle.Where platform-specific code does appear, it's at exactly two seams: - Process shutdown. Unix uses libc::kill pid, SIGTERM with a grace window before SIGKILL . Windows uses TerminateProcess and WaitForSingleObject from windows-sys . Both branches are cfg -guarded in pty session.rs . - CWD detection. Linux reads /proc/<pid /cwd . macOS calls proc pidinfo . The Windows branch returns None for now and falls back to OSC 7 emission from the shell prompt. Three small cfg target os = "..." blocks; nothing leaks into the rest of the codebase. That's the entire surface area of "this code knows what OS it's running on", fewer than 100 lines across the whole app. Everything else compiles unchanged on Linux, macOS, and Windows. Agent orchestration via JSON-RPC This is the part the rest of the article was building toward. Paneflow exposes a JSON-RPC 2.0 server on a local socket so external tools, scripts, and AI agents can drive the editor programmatically. Workspace navigation, sending text to panes, splitting surfaces, and a six-method ai. namespace that lets agents publish their lifecycle events back to the UI: session start, prompt submit, tool use, notification, stop, session end. Transport: the interprocess https://crates.io/crates/interprocess crate's local socket module. On Unix it's a Unix domain socket at $XDG RUNTIME DIR/paneflow/paneflow.sock with $TMPDIR fallback on macOS ; on Windows it's a named pipe at \\.\pipe\paneflow . Same wire protocol newline-delimited JSON-RPC 2.0 , same Rust call sites, zero cfg at the dispatch level. The socket is strictly local : no network surface, no port binding. Trust derives from filesystem mode 0600 set immediately after bind , plus getsockopt SO PEERCRED on Linux and LOCAL PEERCRED on macOS: every accepted connection checks the peer's UID against the server's before any method dispatches. A mismatch returns JSON-RPC -32001 permission denied and closes the stream.Architecturally, methods fall in two buckets. Stateless methods system.ping , system.capabilities , system.identify reply directly on the socket thread: js match method.as str { "system.ping" = json {"jsonrpc": "2.0", "result": {"pong": true}, "id": id} , "system.identify" = json {"jsonrpc": "2.0", "result": { "name": "Paneflow", "version": env "CARGO PKG VERSION" , "protocol": "jsonrpc-2.0" }, "id": id} , = dispatch to gpui &request tx, method, params, id , } Stateful methods workspace. , surface. , ai. need the GPUI main thread because that's where all mutable state lives. The socket thread cannot touch Entity<T directly. So dispatch to gpui wraps the request in an IpcRequest with a one-shot response channel, sends it across an mpsc queue, and blocks on the reply with a 5-second timeout: fn dispatch to gpui request tx: &mpsc::Sender<IpcRequest , method: String, params: Value, id: Value, - Value { let resp tx, resp rx = mpsc::channel ; let ipc req = IpcRequest { method, params, id: id.clone , response tx: resp tx }; if request tx.send ipc req .is err { return json {"jsonrpc": "2.0", "error": {"code": -32000, "message": "App shutting down"}, "id": id} ; } match resp rx.recv timeout Duration::from secs 5 { Ok result = promote response result, id , Err = json {"jsonrpc": "2.0", "error": {"code": -32000, "message": "Timeout"}, "id": id} , } } On the GPUI side, process ipc requests in src-app/src/app/ipc handler.rs drains the receiver each tick, dispatches by method name, and sends the result back through the per-request response channel. Stateful handlers can return a structured JsonRpcError via a jsonrpc error sentinel value that promote response rewrites into a proper JSON-RPC error envelope at the boundary, so handlers stay synchronous and don't have to construct envelopes themselves. What this buys, concretely: a Claude Code session can announce itself with ai.session start and the sidebar marks the pane as agent-active. A shell script can push commands into the active surface with surface.send text . A test harness can spin up a workspace, run a battery of agent calls, and tear it down. The protocol is bytes on a socket; the security model is filesystem mode + peer credentials; the dispatch is a mpsc::channel between two threads. Here's the smallest useful client you can write today, just socat and a JSON line: echo '{"jsonrpc":"2.0","method":"surface.send text","params":{"text":"ls\n"},"id":1}' \ | socat - UNIX-CONNECT:$XDG RUNTIME DIR/paneflow/paneflow.sock The full method surface is documented in the README https://github.com/ArthurDEV44/paneflow ipc . Four things I got wrong 1. I over-invested in Tauri. I pushed a Tauri implementation pretty far before admitting that the webview API surface could not carry a multiplexer's constraints low-level input, IME, inter-pane focus . The right time to pivot was about two weeks before the moment I actually pivoted. Lesson: when a framework asks you to work around its own abstraction for two basic features, you're building against the framework, not with it. Pivot. 2. Block-character rendering gaps. Paneflow had a visible gap between adjacent block characters U+2580 to U+259F when rendered at certain font sizes. I spent six fix attempts on it: integer cell dimensions, origin rounding, shader edge math, shared-boundary subpixel adjustments. Every fix was plausible. None of them worked. The actual bug was that my block-character coverage table was incomplete: eleven codepoints U+2594, U+2596 to U+259F were missing, so they fell through to the default font path which has slight metric differences. The fix was extending the codepoint table, found by binary-scanning the binary of a TUI that triggered the bug. Lesson: when GPU quad math looks correct on every probe but the visual artifact persists, the problem is probably which codepoints you're emitting, not how. 3. Polling timers defeat cx.notify . An early version of the sidebar polled for port-scan results every 500 ms and CWD changes every 2 s. That produced six to eight unnecessary repaints per second when nothing was happening. The fix was a full migration to GPUI's EventEmitter / cx.subscribe / cx.emit push model, with custom events like ActivityBurst and CwdChanged emitted from the PTY reader. Idle repaints went to zero. GPUI's diff repaint is cheap, but it isn't free, and a cx.notify in a setInterval -shaped loop is exactly the pattern the framework was designed to replace. 4. Session persistence is table-stakes. I shipped the first internal build without session save/restore because the layout code was already complex and I wanted to land the v1 commit. The first thing I did with the build was open four workspaces, rebuild the binary, and lose all four. Every multiplexer user has tmux in their muscle memory. Restart-survives-state isn't a feature, it's the price of admission. Save it to ~/.cache/paneflow/session.json on CloseWindow , restore on startup, scope it into v1. Try it The repo is github.com/ArthurDEV44/paneflow https://github.com/ArthurDEV44/paneflow , MIT licensed. Linux Wayland and X11 and macOS Apple Silicon ship today as signed and notarized builds; native Windows is in flight, the code is largely ready, the signing infrastructure is being wired up. Prebuilt artifacts are on the download page https://paneflow.dev/download ; honest side-by-side comparisons vs cmux, WezTerm, iTerm2, and Warp at paneflow.dev/compare https://paneflow.dev/compare . Issues, suggestions, and "your N-ary tree should really be a Z-tree" arguments are all welcome on the tracker. I'm especially curious about what's missing for your workflow versus the multiplexer you use today; that's the feedback that shapes the next release. If this was useful, the engineering work I'm most proud of is in the terminal/element/ module, that's where glyph shaping, atlas blits, and the APCA adjustment pipeline all live, and it didn't fit in this post. I'll write that one up next.