The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Terminal runtime |
| 2 | |
| 3 | The environment server owns PTYs, session lifetime, and retained output. Every |
| 4 | client, including the desktop renderer, attaches through the environment connection. |
| 5 | This lets clients reconnect or share a running session. Renderer choices stay local |
| 6 | to each client and do not change terminal contracts. |
| 7 | |
| 8 | ## Output and retention |
| 9 | |
| 10 | [Terminal history](../../apps/server/src/terminal/Manager.ts) is incremental. |
| 11 | PTY callbacks append new chunks; live events carry only those chunks. Materializing |
| 12 | or copying full scrollback on every callback makes output cost grow with retained |
| 13 | history, so snapshots and coalesced persistence are the materialization boundaries. |
| 14 | Persistence queues the mutable history buffer and reads its latest value when the |
| 15 | write runs. Clear, restart, and close must drain writes before completing their |
| 16 | lifecycle boundary. |
| 17 | |
| 18 | Server history is capped at 5,000 lines and 8 MiB of UTF-8 text per terminal, so a |
| 19 | long unterminated line cannot bypass retention. Eviction removes the oldest output |
| 20 | without splitting Unicode code points; live output is not truncated. Release |
| 21 | discarded chunk references immediately, even if array compaction happens later. |
| 22 | Client buffers have a separate 512 KiB cap. Measure throughput with full scrollback |
| 23 | when changing this path. |
| 24 | |
| 25 | Restoration must read only the bounded tail of current or legacy history files, |
| 26 | skip any incomplete UTF-8 prefix, and apply the line limit. Close the read handle |
| 27 | before rewriting the capped file. Reading whole old logs would defeat the memory |
| 28 | bound during startup. |
| 29 | |
| 30 | ## Renderer ownership |
| 31 | |
| 32 | Android and web use the same `libghostty-vt` C ABI for terminal behavior. Platform |
| 33 | adapters own drawing and input integration, and React stays out of terminal frames. |
| 34 | The web adapter shares one WebAssembly instance per browser tab while each terminal |
| 35 | owns and frees its own handles. The canonical upstream pin is |
| 36 | [`native/libghostty-vt/VERSION`](../../native/libghostty-vt/VERSION); both native and |
| 37 | web artifacts must be rebuilt when it changes. Web embeds the revision in its build |
| 38 | info so the ABI check can detect drift without a second pin. |
| 39 | |
| 40 | Restoring scrollback must not send terminal replies to the current shell. Historical |
| 41 | device queries can otherwise provoke fresh replies that appear as junk at the |
| 42 | prompt. The server strips query/response traffic from retained history, and the |
| 43 | [web renderer](../../apps/web/src/terminal/ghostty/core.ts) detaches its PTY writer |
| 44 | during replay. Preserve both protections when changing retention or renderer code. |