The best way to control Claude Code, Codex and more from any computer or phone

main
md 44 lines 2.48 KB
Rendered Raw
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.