One PTY, two screens: choosing who controls terminal size

Gemron Guo — Mon, 07 Sep 2026 11:56:02 +0000

A browser terminal can look responsive while showing the wrong grid.

Imagine a desktop displaying 140 columns and a phone displaying 48. Both clients are attached to the same running command-line application. If each emulator independently resizes itself to its container, the application still receives only one terminal size. Cursor positioning and line wrapping can then disagree between the application and one of its viewers.

This is a state-ownership problem hiding inside a layout problem.

Separate three sizes

There are three quantities worth naming:

Container size: the pixels available in one browser.
Proposed grid: the rows and columns that fit that container at its current font size.
Accepted grid: the rows and columns the host has applied to the shared terminal.

On Windows, ResizePseudoConsole takes the pseudoconsole handle and a character-grid size. It changes the dimensions seen by attached console applications. Meanwhile, xterm.js resize changes a client emulator's grid.

Calling the browser method does not, by itself, coordinate the host or the other browser.

A useful invariant is: every viewer of the same terminal should render the host's accepted grid. A narrower container can scroll horizontally. It should not silently invent a different number of columns for the same live output.

Choose an ownership policy

Several policies are reasonable, with different costs.

Policy	Benefit	Cost
Fixed desktop grid	Stable desktop layout	Phones need horizontal scrolling
Smallest attached viewport	Content fits every viewer	One passive phone can shrink everyone's terminal
Active viewer owns the grid	Layout follows the person interacting	Changing devices changes the grid for every viewer

The third policy needs an explicit distinction between reporting a size and claiming control. A background window opening a sidebar is a size report. An intentional interaction with the terminal can be a claim.

Do not make every resize observer callback a claim. Otherwise, background layout changes can take ownership back immediately after the user switches devices.

A small state machine

The core decision can be expressed separately from networking and rendering:

type Grid = { cols: number; rows: number };
type ViewportState = { owner: string | null; grid: Grid };

function mayResize(owner: string | null, viewer: string, claim: boolean) {
  return owner === null || owner === viewer || claim;
}

This is illustrative policy code, not a complete terminal server. The surrounding handler needs to:

Authenticate the connection and validate positive integer dimensions within supported limits.
Serialize ownership and resize decisions for each terminal.
Reject passive reports from viewers that do not own it.
Apply the requested grid to the host terminal.
After success, commit the accepted state and broadcast it to every viewer.

Clients then resize their emulators from that accepted event. Keeping a local proposal separate avoids treating an unacknowledged request as an accomplished resize.

An owner change can matter even if the dimensions stay identical. Deduplicating messages only by rows and columns would lose that handoff.

Disconnects and failure cases

When an owner disconnects, clearing ownership while retaining the last accepted grid avoids a surprise resize for remaining readers. The next intentional interaction can claim ownership. A reconnecting client should obtain the current grid before presenting the session as ready.

Failed host resizes should leave the previously accepted grid authoritative. Rapid claims from two clients need a defined order. If the protocol uses multiple channels or asynchronous handlers, include a revision number or another ordering mechanism; broadcasting dimensions alone does not establish that order.

Sharing terminal dimensions also does not solve input ownership. Allowing two clients to type into the same process is a separate product decision.

Checks that reveal the bug

A useful manual exercise is to attach a wide desktop and a narrow phone, then:

Interact on the phone and confirm both emulators adopt the same accepted dimensions.
Resize a passive desktop panel and confirm it does not steal ownership.
Switch control back to the desktop while a full-screen terminal application is open.
Disconnect the active viewer and check that the remaining screen keeps its grid.
Simulate a rejected resize and verify that clients keep the last accepted state.

These are suggested checks, not a report of a new device test run. They target the boundary between local layout and shared state, where ordinary single-window testing misses the problem.

AI disclosure: This article was generated by an AI agent from the author's terminal-workbench implementation notes, with technical claims checked against the relevant source code and the API documentation linked above. The code sample is illustrative.

How I Stopped Losing Track of Claude Code and Codex Sessions

Gemron Guo — Sun, 02 Aug 2026 06:15:53 +0000

Using one coding agent is simple. Using several across multiple projects is where the real mess begins.

I often had Claude Code and Codex running side by side. One agent was working, another was waiting for approval, and yesterday’s useful session was buried under a different path, branch, or terminal window.

The agents were capable. My workspace was not.

That frustration led me to build Termexo, a local-first Windows workbench for coding agents.

The problem was not the model

The hardest part was no longer generating code. It was keeping track of context:

Which agent is still working?
Which one needs my approval?
Where did I leave yesterday’s session?
Which project, path, and branch did that terminal belong to?
Which model profile was active?

A pile of terminal windows can answer all of those questions—but only if you remember everything yourself.

What I wanted instead

I wanted one recoverable workspace where I could:

run Claude Code and Codex in real PTY terminals;
arrange terminals in custom grids;
see when an agent needs attention;
search and resume native sessions;
restore a workspace after restarting the app;
switch Claude-compatible model profiles without rebuilding environment variables;
keep API keys in Windows Credential Manager.

That became Termexo.

Why keep the native CLI?

Termexo does not replace Claude Code or Codex with a custom chat interface. The real CLI remains visible and usable.

That matters because the terminal is still the source of truth. Existing commands, hooks, approvals, keyboard shortcuts, and session behavior continue to work. Termexo focuses on the coordination layer around those tools.

A workspace should be recoverable

A useful coding-agent session should not disappear just because the app restarted or a terminal was closed.

Termexo treats terminals, layouts, projects, and native agent sessions as parts of the same workspace. The goal is simple: when you return, you should be able to understand what was happening and continue without rebuilding the entire setup from memory.

Attention should be visible

When several agents are active, I do not want to stare at every terminal. Termexo can surface approval requests and completion events through system notifications and taskbar attention indicators.

This sounds small, but it changes the workflow. You can focus on one task while another agent works, then switch only when the second task actually needs you.

Local-first by default

Termexo does not require a Termexo account. Workspaces and settings stay on the machine, and credentials are stored through Windows Credential Manager.

The project is Windows-only today. It is still evolving, but it already solves the problem that originally pushed me to build it: losing track of several useful coding-agent sessions at once.

If you regularly run multiple coding agents, I would love to know which part of that workflow wastes the most time for you.

Website: termexo.com
GitHub: gemron/Termexo
Product Hunt: Termexo

— 爱玩科技

DEV Community: Gemron Guo