Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Readable transcript of what a coding agent is doing in its terminal.
The problem: a PTY carries a *terminal protocol*, not a log. Claude Code and
Codex are full-screen TUIs — they position the cursor absolutely, erase regions,
and repaint rows in place. Handing that stream to a language model verbatim
wastes context on control codes, and merely filtering the escape sequences out
is worse than useless: the leftovers arrive in an order nobody read. Measured on
a real Claude Code startup, 872 characters of output reduced to one usable line.
So a terminal screen is replayed instead (:mod:`.screen`), and the transcript is
read off it in two parts:
* **history** — rows that scrolled off the top, i.e. what already happened,
* **display** — the rows currently on screen, i.e. what is happening now.
On top of that sits one light editorial pass for the benefit of a model reading
it: blank and decoration-only rows are dropped, and consecutive identical rows
are folded (a repainted spinner row is one event, not two hundred).
Honest limits: no double-width glyph handling, so a CJK character can shift a
box border by a column; and a two-column TUI layout still reads left-to-right
per row, exactly as it looks on screen. Both are irrelevant for answering "what
is this agent working on?", and both keep the module dependency-free.
"""
from __future__ import annotations
import re
from collections import deque
from dataclasses import dataclass, field
from .screen import ScreenBuffer
# Kept for callers that want plain text out of a coloured string (the prompt
# sanitizer uses it). Screen replay does NOT go through this.
_CSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
_OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
_ESC_RE = re.compile(r"\x1b[@-Z\\-_]")
_MISC_RE = re.compile(r"\x1b[<>=]")
# A row made only of these draws a frame or an animation; it carries no
# information for a model summarizing the session.
# One COMPLETE escape sequence, anchored where a match is tried. Used to answer
# "did this chunk stop in the middle of one?" — see :func:`_ends_mid_escape`.
_ANY_ESC_RE = re.compile(
r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_]|[<>=])"
)
# The TAIL of a CSI sequence whose ESC was dropped: parameters, then optional
# intermediates, then the final byte. The leading "[" is optional because the
# split may have fallen either side of it.
_CSI_TAIL_RE = re.compile(r"\[?[0-?]*[ -/]*[@-~]")
#: ``ESC [ ? <params> h|l`` — how a CLI turns terminal features on and off.
_PRIVATE_MODE_RE = re.compile(r"\x1b\[\?([0-9;]+)([hl])")
# A private-mode prefix at the END of the bytes seen so far. PTY reads can cut
# after any byte, including between ``ESC[?10`` and ``00h``.
_PRIVATE_MODE_PARTIAL_RE = re.compile(r"\x1b(?:\[(?:\?(?:[0-9;]*))?)?$")
_PRIVATE_MODE_PARTIAL_MAX = 128
# A full erase is either ED 2, or ED 0 after moving to the top-left cell.
# Codex uses the latter. Missing it made successful redraws trigger all five
# height nudges, visibly moving the terminal down and up every half second.
# Only intervening controls that cannot move the cursor are accepted.
# Kept in step with frontend/terminalRepaint.ts by shared protocol fixtures.
_FULL_CLEAR_RE = re.compile(
r"\x1b\[2J|\x1b\[(?:0*1?)(?:;0*1?)?[Hf]"
r"(?:\x1b\[[0-9;:]*m|\x1b\[\?(?:25|2026)[hl])*\x1b\[0*J"
)
_FULL_CLEAR_SCAN_TAIL = 128
_DECORATION_CHARS = set("─│┌┐└┘├┤┬┴┼━┃╭╮╯╰═║╔╗╚╝╠╣╦╩╬▀▄█▌▐░▒▓▔▁·.-_=*#~ ")
_SPINNER_CHARS = set("|/\\-◐◓◑◒✻✽✢·✳✶⣿")
def strip_ansi(text: str) -> str:
"""Remove terminal escape sequences, leaving printable text."""
text = _OSC_RE.sub("", text)
text = _CSI_RE.sub("", text)
text = _MISC_RE.sub("", text)
text = _ESC_RE.sub("", text)
return "".join(ch for ch in text if ch >= " " or ch in "\t\n\r")
def _ends_mid_escape(text: str) -> bool:
"""Does ``text`` stop INSIDE an escape sequence?
A PTY read ends wherever the kernel filled its buffer, so an escape can be
split across two chunks. The last ``ESC`` decides it: if what follows is a
complete sequence the chunk is self-contained, and if it is not, the rest is
at the front of the NEXT chunk.
"""
esc = text.rfind("\x1b")
return esc >= 0 and _ANY_ESC_RE.match(text, esc) is None
def _is_decorative(ch: str) -> bool:
"""True for a glyph that only ever draws a frame or an animation.
Braille patterns (U+2800..U+28FF) get a range check rather than a character
list: every modern CLI spinner cycles through dozens of them, and listing
the ones a given agent uses today would go stale when it changes its
spinner.
"""
if ch in _DECORATION_CHARS or ch in _SPINNER_CHARS:
return True
return 0x2800 <= ord(ch) <= 0x28FF
def is_noise(line: str) -> bool:
"""True for a line that carries no information worth keeping."""
stripped = line.strip()
if not stripped:
return True
return all(_is_decorative(ch) for ch in stripped)
@dataclass(slots=True)
class Transcript:
"""Readable view of one terminal, backed by a replayed screen."""
cols: int = 100
rows: int = 30
max_lines: int = 600
# Characters of raw PTY output seen — a cheap "is this agent doing
# anything?" signal that survives every row being filtered as noise.
raw_chars: int = 0
screen: ScreenBuffer = field(init=False)
def __post_init__(self) -> None:
self.screen = ScreenBuffer(self.cols, self.rows, scrollback=self.max_lines)
# ------------------------------------------------------------------ input
def feed(self, chunk: str) -> None:
"""Replay a raw PTY chunk (escape sequences and all)."""
if not chunk:
return
self.raw_chars += len(chunk)
self.screen.feed(chunk)
def resize(self, cols: int, rows: int) -> None:
"""Follow the pane's size so the replayed screen matches the real one."""
self.cols, self.rows = cols, rows
self.screen.resize(cols, rows)
# ----------------------------------------------------------------- output
def lines(self) -> list[str]:
"""History plus the current screen, cleaned and de-duplicated."""
out: list[str] = []
for line in [*self.screen.history(), *self.screen.display()]:
text = line.rstrip()
if is_noise(text):
continue
if out and out[-1] == text:
continue # a repainted, unchanged row
out.append(text)
return out
def tail(self, count: int = 40) -> list[str]:
"""Last ``count`` meaningful lines, oldest first."""
if count <= 0:
return []
return self.lines()[-count:]
def clear(self) -> None:
self.screen.reset()
self.raw_chars = 0
"""How much raw PTY output a pane keeps for its next viewer.
Enough to cover several full repaints of a coding agent's TUI, so a pane that
is looked at again shows what it was showing rather than a black rectangle —
and small enough that a dozen panes across a handful of workspaces stay a
rounding error in memory (12 panes x 6 workspaces x 128 KB is under 10 MB).
"""
REPLAY_LIMIT_CHARS = 128 * 1024
@dataclass(slots=True)
class ReplayBuffer:
"""The tail of a terminal's RAW output, kept for a viewer that comes back.
Separate from :class:`Transcript` because the two answer different
questions. The transcript is for a *reader*: escape sequences replayed onto
a screen and turned into readable rows. This is for a *terminal*: the exact
bytes, in order, so xterm on the other side can be handed them verbatim and
end up in the state the pane was in.
That distinction is load-bearing for switching workspaces. The agent keeps
running while nobody watches, so reconnecting has to reconstruct the screen
from something — and the only thing that reconstructs a full-screen TUI is
the stream that drew it. Cleaned-up text would come back as a wall of
prose where a framed, coloured interface used to be.
Bounded by total characters, dropping whole chunks from the front — and
``truncated`` then says so, because **a cut stream does not repair
itself**. This buffer used to assume it did ("a TUI repaints itself
constantly"), and that assumption is what put empty rectangles in two panes
of a live workspace (reported 2026-07-27). A coding agent built on Ink
paints its interface ONCE and afterwards rewrites only the row that
changed, addressed by RELATIVE cursor moves — so a tail that lost its front
replays the spinner row the agent wrote last onto rows where the prompt box
it drew twenty minutes ago is simply missing. Nothing later redraws it.
Whoever replays a truncated buffer therefore has to ask the agent for a
fresh paint afterwards; :meth:`SessionRegistry.attach` does it with a
window-size change, the one request every TUI answers with a full redraw —
usually. Claude Code 2.1.283 let half of them pass unanswered while busy
(measured 2026-09-28), so the answer is checked for, via :attr:`clears`.
**The modes are kept even when the bytes that set them are gone.** A CLI
negotiates what kind of terminal it is talking to exactly ONCE, in its first
few hundred bytes — measured against Claude Code 2.1.220: ``ESC[?1049h``
(take the whole screen) and ``ESC[?1000h ESC[?1002h ESC[?1003h ESC[?1006h``
(send me the mouse). Those bytes fall out of a 128 KB tail within minutes of
an agent working, and every viewer that re-joined afterwards built a
terminal that did not know any of it: xterm stayed on the normal buffer and
kept the wheel to itself, while the agent went on believing it owned both.
A wheel turn then scrolled the viewer's own stale buffer — which the agent
overwrote on its next repaint, since it addresses the screen absolutely — so
scrolling a Claude Code pane did nothing at all, in the app, forever, while
a Codex pane (which negotiates neither) was unaffected. Reported four times
over as "the scrollbar only works in Codex"; the scrollbar was the symptom.
So every private mode the agent has set is remembered as it goes past, and a
truncated replay is prefixed with the ones still in force. Cheap — a regex
over each chunk, a dict of at most a dozen entries — and it puts the viewer
in the state the agent thinks it is in, which is the whole job of a replay.
"""
limit: int = REPLAY_LIMIT_CHARS
_chunks: deque[str] = field(default_factory=deque, init=False)
_size: int = field(default=0, init=False)
#: Has anything been dropped since the last :meth:`clear`? Read by the
#: viewer path to decide whether the replay alone can be trusted.
truncated: bool = field(default=False, init=False)
#: Did the last dropped chunk stop inside an escape sequence? Then the rest
#: of that sequence is at the front of what remains.
_open_escape: bool = field(default=False, init=False)
#: Every private mode seen, in the order it was first negotiated, with the
#: value it was last given. Insertion order matters: a screen switch has to
#: be replayed before what was drawn on that screen.
_modes: dict[str, bool] = field(default_factory=dict, init=False)
#: Incomplete private-mode prefix from the preceding PTY read.
_mode_scan_tail: str = field(default="", init=False)
#: How many whole-screen erases have gone past — a counter, never reset by
#: a rebase. A full repaint of a full-screen TUI starts with one, so this
#: rising is how the repaint nudge knows it was answered (see
#: ``SessionRegistry._confirm_repaint``).
clears: int = field(default=0, init=False)
#: The last bytes of the preceding read, in case it split an erase.
_clear_scan_tail: str = field(default="", init=False)
#: Does the kept drawing belong to a terminal size the agent has since
#: left? Set by :meth:`rebase_for_resize` for an agent that paints whole
#: frames, cleared by that agent's next whole-screen erase — the fresh
#: frame that replaces the old one. A replay taken meanwhile still shows
#: the old frame, and its viewer has to ask for the new one.
awaiting_frame: bool = field(default=False, init=False)
#: Has this process painted a whole frame — an erase while holding the
#: screen? Per process, unlike ``clears``: a pane's next agent may repaint
#: differently.
_paints_frames: bool = field(default=False, init=False)
def feed(self, chunk: str) -> None:
if not chunk:
return
self._note_modes(chunk)
previous = len(self._clear_scan_tail)
scanned = self._clear_scan_tail + chunk
# The longer scan tail can contain an already counted erase. Count
# only matches completed by this read, including split home/ED pairs.
erases = [match for match in _FULL_CLEAR_RE.finditer(scanned) if match.end() > previous]
self.clears += len(erases)
self._clear_scan_tail = scanned[-_FULL_CLEAR_SCAN_TAIL:]
if erases:
# A fresh frame has started, including an erase split across reads.
self.awaiting_frame = False
if self.holds_screen:
self._paints_frames = True
erase = erases[-1].start() if erases and self.holds_screen else -1
if erase >= 0:
# A full-screen agent just emptied its screen, so everything it
# drew before this is gone from it — and what follows is a frame
# built from nothing, the one replay that rebuilds a viewer on its
# own. Keeping the older bytes instead is what let the tail lose
# its front: a busy agent's 128 KB fill within minutes, and a
# viewer re-joining then got partial row updates for a frame it
# never saw, rows drawn over rows until a repaint nudge was
# answered — which a busy Claude Code does only half the time
# (2026-09-29). The modes the dropped bytes negotiated are kept
# the same way ``rebase_for_resize`` keeps them.
self._rebase(scanned[erase:])
return
self._chunks.append(chunk)
self._size += len(chunk)
while self._size > self.limit and len(self._chunks) > 1:
dropped = self._chunks.popleft()
self._size -= len(dropped)
self.truncated = True
self._open_escape = _ends_mid_escape(dropped)
def _note_modes(self, chunk: str) -> None:
"""Remember what the agent has told the terminal it wants.
``ESC[?1000;1006h`` sets several at once, so each parameter is recorded
on its own. Modes are kept whichever way they were set — a mode the
agent turned OFF is restored as off, because several of them (wraparound,
the cursor) are ON in a terminal that was just built. The scan carries
an incomplete prefix across PTY reads because the kernel may split the
sequence after any byte.
"""
scanned = self._mode_scan_tail + chunk
for params, action in _PRIVATE_MODE_RE.findall(scanned):
for param in params.split(";"):
if param:
self._modes[param] = action == "h"
partial = _PRIVATE_MODE_PARTIAL_RE.search(scanned)
candidate = partial.group(0) if partial is not None else ""
self._mode_scan_tail = (
candidate if len(candidate) <= _PRIVATE_MODE_PARTIAL_MAX else ""
)
@property
def holds_screen(self) -> bool:
"""Is the agent drawing on the alternate screen, i.e. a full-screen TUI?"""
return self._modes.get("1049", False)
def _mode_prologue(self) -> str:
"""The negotiation a truncated replay lost, re-stated in order."""
return "".join(f"\x1b[?{mode}{'h' if on else 'l'}" for mode, on in self._modes.items())
def text(self) -> str:
"""Everything kept, oldest first — ready to be written to a terminal.
A truncated tail is repaired at its front before it goes out. Dropping
whole chunks can still leave the CONTINUATION of a sequence there — a
terminal handed ``[38;5;214m`` with no ``ESC`` prints it as visible text
in the middle of the agent's interface — so that remnant is skipped, and
an attribute reset makes the starting colour deterministic rather than
inherited from bytes that are gone.
The repair also re-states the modes the agent negotiated (see the class
docstring): they are set once at startup and are the first thing a long
tail loses, and a viewer that never heard them is a terminal the agent
cannot reach with the mouse.
"""
text = "".join(self._chunks)
if not self.truncated or not text:
return text
if self._open_escape:
remnant = _CSI_TAIL_RE.match(text)
if remnant is not None:
text = text[remnant.end() :]
return self._mode_prologue() + "\x1b[0m" + text
def rebase_for_resize(self) -> str:
"""Start a new replay epoch for a new terminal size; return the replay.
Cursor-addressed TUI output only has meaning at the terminal size that
produced it. Replaying that stream into a differently sized viewer
leaves old status rows and fragments between the newly painted ones.
A resize therefore starts a new replay epoch: the caller sends the
returned replay to a reset viewer, then asks the live TUI to repaint.
**An agent that paints whole frames keeps its old one until the new
one arrives.** Claude Code answers a resize with a frame that opens
with a whole-screen erase (measured on 2.1.284), so the old drawing
cannot leave fragments behind it — the erase wipes it, and the viewer
stays hidden until that erase lands. Dropping it instead left the
replay with nothing to draw: when the agent was too busy or starved to
answer, every pane of a workspace came back as an empty black
rectangle and stayed one until the agent next repainted on its own,
which for an agent waiting for input is never (reported 2026-09-30,
with the machine short of memory and disk). The old frame is kept and
``awaiting_frame`` says a new one is owed. Only an agent that has
already shown a whole-screen erase qualifies: Codex repaints with
partial erases, so a kept frame would show through its new one.
Private modes survive because most coding CLIs negotiate alternate
screen and mouse tracking only once, at process startup. Dropping
those together with the stale drawing would repair the text while
silently breaking the pane's mouse and scrollbar.
"""
if self.holds_screen and self._paints_frames:
self.awaiting_frame = True
return self.text()
return self._rebase("")
def _rebase(self, frame: str) -> str:
"""Start a fresh replay epoch: the negotiated modes, then ``frame``."""
prologue = self._mode_prologue() + "\x1b[0m"
self._chunks.clear()
self.truncated = False
self._open_escape = False
self.awaiting_frame = False
self._chunks.append(prologue)
self._size = len(prologue)
if frame:
self._chunks.append(frame)
self._size += len(frame)
while self._size > self.limit and len(self._chunks) > 1:
dropped = self._chunks.popleft()
self._size -= len(dropped)
self.truncated = True
self._open_escape = _ends_mid_escape(dropped)
return prologue
def clear(self) -> None:
"""Forget everything — this buffer is being handed to a fresh process.
Including the remembered modes. They describe what the PREVIOUS agent
negotiated, and it is gone; the new one states its own within its first
few hundred bytes, straight into the empty buffer below. Keeping them
would put a dead process's screen mode at the front of the next
truncated replay, and a viewer that clears before drawing a replay has
nothing else to derive its state from.
"""
self._chunks.clear()
self._size = 0
self.truncated = False
self._open_escape = False
self._modes.clear()
self._mode_scan_tail = ""
self._clear_scan_tail = ""
self.awaiting_frame = False
self._paints_frames = False
__all__ = [
"REPLAY_LIMIT_CHARS",
"ReplayBuffer",
"Transcript",
"is_noise",
"strip_ansi",
]