session-debugging
Skill2 starsChanged 2 days agoMITView on GitHub
Use when observing or driving a live harness session's terminal from an agent — reading what a shell / TUI / REPL / claude session is showing, injecting keystrokes, running a shell command inside a live PTY, or diagnosing a worker that looks stuck or unresponsive (harness-cli session snapshot / send / exec).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- issue-orchestrator/issue-orchestratortheir own version, first seen Sep 6, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- issue-orchestrator/issue-orchestrator★ 10same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-tourSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- supervising-workersSkill
- codebase-tourSkill
- dummy-harnessSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- implementation-pitfallsSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- session-debuggingSkill
- supervising-workersSkill
- surface-parity-checklistSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
All three authenticate with your task ticket — no operator PSK — but they do
- Distinctive: line 85
When you are waiting for something rather than reading one result, poll for the expected render instead of guessing a sleep:
- Very specific: line 242
--raw: instead writes the verbatim replay bytes (escapes intact) — cat it into a real terminal to reproduce the screen exactly, or … - Distinctive: line 332
AFTER the text is taken as literal text — you will see it *typed* in the snapshot instead of submitting.
- Very specific: line 408
Read the worker's row on ls first.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debugging live sessions (snapshot / send / exec)
Overview
You have no TTY, so session attach is not for you (it splices a real local
terminal to the remote PTY). The non-TTY trio gives you eyes and hands on any
live interactive session:
harness-cli session snapshot <id> # SEE the current screen (read-only)
harness-cli session send -enter <id> <text> # TYPE keystrokes (co-write, no takeover)
harness-cli session exec <id> <cmd>... # RUN one shell cmd, wait, get output + exit code
harness-cli session resize --size 40x150 <id> # SIZE the PTY (no takeover)All three authenticate with your task ticket — no operator PSK — but they do not need the same capability, because they are not the same power:
| tool | attach mode | capability |
snapshot | view | exec_view |
send / exec | cowrite | exec_cowrite |
resize | view | exec_view + exec_resize |
snapshot is a read-only attach and never disturbs whoever is driving;
send/exec co-write into the live PTY without taking over the human
controller and without resizing. The human may be attached in parallel — that
is expected.
The caps are checked with implication (each accepts itself or anything
stronger), so exec_cowrite alone covers all three and exec_control covers
everything. If you were granted only exec_view you can look but not type —
that is a deliberate grant, not a misconfiguration: ask your spawner for
exec_cowrite rather than assuming it was an oversight.
Get <id> from harness-cli session ls (interactive sessions) or ls
(all tasks) — pipe it into a variable; never hand-type a 32-hex id.
Choosing the tool
- Foreground is a POSIX shell (bash/zsh/sh — incl. one reached over ssh or
inside a netns) →
exec: synchronous, greppable output, real exit code. A shell inside a multiplexer does not count — see exec footgun 5. - Foreground is anything else (TUI, REPL, claude, full-screen app) →
send+snapshotloop.execon a non-shell foreground finds no completion marker and times out with a diagnostic — that timeout is your signal to switch. - Target is a claude worker you're coordinating → the agentboard for
anything expressible as prompt text (tasks, corrections, questions), and the
keyboard ONLY for what is not: client-level control —
/clear,/compactand other slash commands, an Esc interrupt, a permission-prompt answer, a menu selection (see "Diagnosing a stuck claude worker" below). An agentboard payload reaches a claude peer as prompt text: the runner types only the fixed<harness:agentboard-wake>marker into the PTY, and the payload arrives through theUserPromptSubmitinbox hook. Soagent send --data '/clear'clears nothing — the worker reads the two words as content. That is structural, not a gap to route around. - Completion is signalled per channel too. An agentboard instruction ends
with the peer's reply; a keystroke-level one has no reply coming, so its only
edge is PTY quiescence (
session await-idle— seeharness-cli skill supervising-workers). Do not arm an idle watcher for a peer you already asked to report back on the agentboard.
The drive loop (send → snapshot → assert)
For a single step, --snapshot does both halves in one call — it sends, lets
the input drain, then renders the screen to stdout (the summary stays on
stderr, so a pipe gets only the screen):
harness-cli session send -enter --snapshot "$ID" 'echo pong-$RANDOM'
harness-cli session send -e --snapshot --style "$ID" '\x1b[B' # ↓, then look--settle-ms (default 1500) is the window the program gets to react before the
render; --rows/--cols/--style/--color/--ansi/--json/--without-synth/--detect
mean what they mean on session snapshot, and all of them are refused without
--snapshot rather than silently ignored.
When you are waiting for something rather than reading one result, poll for the expected render instead of guessing a sleep:
harness-cli session send -enter "$ID" ./mytui
for i in $(seq 20); do
harness-cli session snapshot "$ID" | grep -q 'Main Menu' && break
sleep 0.5
done
harness-cli session snapshot "$ID" # then read the state you asserted on- Verify INPUT, not just the render. A correct-looking screen proves output
plumbing, not input plumbing. After sending keys, assert the program
responded: the screen changed, a cursor moved, or — in a shell — echo a
nonce round-trip (
send -enter "$ID" echo pong-$RANDOM, then snapshot for it). - Control keys via
-e, which interprets\n \r \t \e \xHH \\:send -e "$ID" '\x03'= Ctrl-C,'\x1b'= Esc,'\x1b[A'…'\x1b[D'= arrow keys,'\t'= Tab,'\r'= Enter. -enterappends a carriage return — a CR, so it submits on Windows cmd.exe too.- Give an agent TUI its Enter in a SECOND call. Whether a CR arriving in
the same burst as the text submits is the foreground program's decision, not
the harness's — the harness is a byte pipe that neither inspects nor alters
it. It differs between agents, and it has changed between versions of the
same agent, so there is nothing here worth learning as a fact: the two-call
form is correct either way and survives the next upgrade.
send <id> <text>(no-enter), snapshot to confirm the text is in the box, thensend -e <id> '\r'separately. Plain shells and classic line-editors are fine with-enterin one call. - One call per keypress in a TUI. Printable runes that arrive in a single
write are delivered to the program as ONE key event, so
send <id> 'jjj'reaches a TUI as the single key"jjj", which matches no binding: the cursor does not move three rows, it does not move at all (verified live against a bubbletea table). Repeat the call per keypress instead of batching. This is not a harness artifact — key-repeat and paste batch the same way, which is why a widget that means to accept a burst has to read it rune by rune, and not every widget does. A shell is unaffected: it consumes the whole write as typed text.
Command reference
session snapshot [--style] [--color] [--ansi] [--detect] [--json|--raw] [--without-synth] [--rows N --cols N] <id>
Renders the session's current screen to plain text via a headless VT emulator
(--rows/--cols are a fallback if the session reports no size). Note they only
affect rendering: a session started without an attached terminal may have no
size at all, and a full-screen program in it refuses to draw ("terminal too
small" — codex and agy paint nothing whatsoever at 0x0).
Each snapshot already waits --settle-ms (default 1500) collecting output
before rendering — factor that beat into poll loops.
--rows/--cols here are NOT the same flags as on session new. Same
spelling, different subject: on snapshot they size the offscreen renderer and
never touch the PTY; on session new they size the PTY itself. To actually
give a session a size, use session resize:
harness-cli session resize --size 40x150 "$ID" # standalone
harness-cli session send -enter --resize 40x150 "$ID" ./mytui # size, THEN type--resize on send applies before the text, which matters: a full-screen
program that receives keystrokes while it is still 0x0 paints nothing, and that
reads like the send having failed.
It needs exec_resize on top of exec_view, and applies only while no
control client is attached — the size belongs to the control seat whenever
someone holds it. Both refusals look the same from here (the server discards
the frame either way), so the command reports "not applied" and exits 3
rather than pretending; do not treat a silent success as proof.
Sizing at open (session new -d --rows 40 --cols 150) is still the route
always available to the spawner and needs no extra capability.
For a running session whose agent is a shell, session exec <id> 'stty rows 40
cols 140' also works with only exec_cowrite — it types the resize rather
than claiming it, so it is unaffected by who holds the seat, but it only works
when the foreground IS a shell.
stty is not equivalent, and the difference bites exactly where you would
reach for it. A size reaches the SERVER only as a TerminalWindowSize frame;
stty is an ioctl on the PTY, so the program sees the new size and the server
never learns it. Measured: after stty, snapshot still prints
session … reported no terminal size and renders at the --rows/--cols
fallback; after session send --resize, it stops warning and renders at the
size you gave. So on a session sized only by stty:
- the server keeps rendering its own grid at 80x24 — the default it holds
until a frame says otherwise — while the program draws at whatever
sttyset; - the replay's screen repaint is built from that 80x24 grid, so a full-screen program comes back partial rather than corrupt — a handful of lines out of a screenful. This path is marked untested in the implementation, which is a warning, not a reassurance.
The failure looks like the program being broken or the snapshot being unable to
handle full-screen apps. It is neither. Use session resize / send --resize
whenever you intend to READ the screen afterwards, and keep stty for the case
it is actually for: no exec_resize, and you only need the program itself to
believe a size.
A resize also makes the program repaint (SIGWINCH), which is useful on its own:
harness-cli session send --resize 45x200 --snapshot --settle-ms 3000 "$ID" ''That sizes, forces a full redraw, and renders in one call — the reliable way to capture a full-screen program whose opening draw has already aged out of the replay ring. Two details decide whether it works:
- One call. A separate
session resizefollowed by asnapshotcan miss the repaint, because the ring is what the snapshot reads and you are racing the redraw into it.--resizeonsendapplies before anything else the call does, so the redraw and the capture are ordered. - A size that CHANGES. Resizing to the size it already has is a no-op — no SIGWINCH, no repaint — and leaves you reading whatever the ring happened to hold. Alternate between two sizes across successive captures.
- The plain render drops SGR, so a faint placeholder / ghost-autocomplete
/ dim hint looks identical to real input.
--styleprints a--- styles ---section listing faint/bold/etc. spans (r<row> c<a>-<b> faint: "...") — an input-box line that shows up asfaintis a placeholder, not something that was typed. - The same blindness hides which pane has focus and which row is selected in
a full-screen TUI: both are drawn with SGR (usually
reverse), so the plain text is identical whether or not anything is selected. Before sending Tab or Enter into a TUI, find thereversespan in--styleand see where the cursor actually is. Guessing costs more keystrokes than looking, and a wrong guess can move focus AWAY from the panel you wanted. --coloradditionally reports fg/bg as hex (fg#ff87af: "Error: ..."— error-red, status colors). Verbose (most cells carry a color), separate opt-in. CJK/wide runs are coalesced, not split per character.--ansire-emits the screen WITH its colours and attributes instead of describing them beside a colourless one. It is for a person looking at the output, not for you: you cannot read an escape sequence any better than you can read a colour, which is why--style/--colorexist. Reach for it when reporting to the operator, or when a screen only makes sense in colour. It is the final screen, so it is one screenful — a live pane measured 1,196 B plain, 2,537 B with--ansi, and 1,045,629 B with--raw. Refused with--jsonand with--raw; composes with--style/--color/--detect.--jsonemits one object instead of text — same screen, different encoding:{task, rows, cols, title, cursor{x,y,visible}, alt_screen, live{window_ms,frames,bytes,anchored}, attrs, color, lines[], spans[]}.linesis the grid one row per entry and is always exactlyrowslong, and each span is{row, start, end, attrs[], fg, bg, text}, solines[span.row]gives you the row a span sits on and you never parse the--- styles ---text.attrsandcolorreport which style dimensions were COLLECTED, which is what separates "spansis empty because I did not ask" from "asked, and the screen has none" — spans stay empty unless you also pass--style/--color.start/endare grid COLUMNS, not offsets into that string: they coincide with character positions only while every earlier cell on the row is single-width, so slice by them at your own risk on a line holding CJK or emoji, and use the span's owntextinstead.--rawinstead writes the verbatim replay bytes (escapes intact) —catit into a real terminal to reproduce the screen exactly, or inspect the actual bytes when the rendered text looks wrong. Not combinable with--style/--color/--json(those describe the VT render; this is a different artifact);--rows/--colsare ignored. It shows the burst as it arrived: the PTY's own bytes together with the ones the server synthesised for the replay — a terminal-mode preamble and a screen repaint built from its own model of the screen — with the synthesised total reported on stderr, so you always know how much of what you are holding the server wrote.--without-synthdrops those, leaving only what the PTY produced. It applies to the rendered forms too, not just--raw. Reach for it when the question is whether the SERVER's own replay is what made a screen look wrong; that is the one case where the repaint is the noise rather than the answer. Everywhere else you want the default, because the repaint is what reconstructs a screen whose opening bytes the replay ring has since evicted.--detectjudges what STATE the screen shows instead of leaving you to read it:working/blocked/idle/unknown, plus the rule that decided and the text that rule read.blockedmeans waiting on a HUMAN — an approval, a menu, a question — which is the case PTY quiescence cannot tell from thinking, since both are silent.--detect-agent NAMEpicks the rule set (defaultclaude); with--jsonthe full per-rule explain rides along underdetect. The report also prints alive:line — the arrival measurement described under--jsonbelow — beside the verdict. No rule reads it: it is there for you to weigh when the screen-based verdict isunknown, not as part of how the verdict was reached.Two things about the verdict are worth knowing before you act on one:
unknownis notidle. It means no rule claimed the screen (a plain shell, an agent with no rules, a screen nobody has met yet) and it comes with afallback_reasonsaying so. Treating it as "free" is the mistake the state exists to prevent.- Several rules can match at once, and the highest priority wins. That is
not tie-breaking, it is the design: Claude keeps its input box on screen
for the WHOLE turn, so the idle rule fires on a working session and has to
lose. If a verdict looks wrong, read the
--jsonrule list — every rule reports whether it matched and what region text it read, so you can see which one took it and why the others did not.
- The grid is width-wrapped: a long line (a SID, a URL) is split across
rows, so a grep can miss it.
--jsondoes NOT fix this —linesis the same wrapped grid. For greppable logical lines useexec(below) or--raw. --jsonalso carries three things that are terminal state rather than cells, plus one that is not about the screen at all. None of them can be recovered by reading the rendered text, and they appear only there: the text forms print the screen, and the screen cannot show them.title— the session's last OSC window title. Some agents put their turn state there as a glyph prefix. Claude in a harness session no longer does: the server answers its OSC 7501 probe, so claude reports its state through that protocol instead. The state then shows asprogram=onls, and the title carries only text. It survives a long quiet stretch: the server's screen repaint re-emits the title from its own model, so one whose original OSC has aged out of the replay ring still reaches you. An emptytitletherefore means the session has not set one. (--without-synthmakes it read empty again, because that view is the ring alone — which is what this said before the repaint carried the title.)cursor—{x, y, visible}, zero-based column and row into the same gridlinesdescribes. Two rows that read identically can have the cursor in completely different places, so this is how you tell a prompt waiting for input from a finished transcript, and where a line-editor's caret actually sits before you send an arrow key.visibleis separate from the position because the two are independent: a hidden cursor still has one, and an app that hides it while drawing still moves it.alt_screen— true while a full-screen app is live. The same grid means different things either side of it: on the alternate buffer it is an app's canvas that vanishes when the app exits, on the primary it is the tail of scrollback. Worth checking before you conclude that output "disappeared".live— how much output arrived in REAL TIME while the snapshot was being taken:{window_ms, frames, bytes, anchored}. An attach opens with the server replaying its ring at wire speed, so the window starts at the replay's closing repaint and everything before it is discarded. This is the one signal a pane border, a resize or an unrecognised UI cannot corrupt — reach for it when--detectreturnsunknownand you still need to know whether anything is happening. Two limits, both load-bearing:framescounts TRANSPORT boundaries, not screen repaints (one repaint can span several, several can coalesce into one), so it is an arrival rate and not a frame rate; and silence does not separate "waiting for a human" from "finished", which is the same wall quiescence hits.anchored: falsemeans no repaint arrived, so the window still holds replayed history and the counts are not a rate at all. A zero count inside a stated window is a measurement —0 frames in 1500 mssays something,0 framesalone does not.
session send [-enter] [-e] [--flush-ms MS] [--snapshot [--rows N] [--cols N] [--settle-ms MS] [--style] [--color] [--ansi] [--json] [--without-synth]] <id> <text>...
Injects keystrokes via a cowrite attach. Flags go BEFORE <id>;
everything after <id> is the text, joined ssh-style
(send -enter <id> echo hello world sends echo hello world — no quoting
needed; quote as one argument to preserve exact whitespace). A -enter placed
AFTER the text is taken as literal text — you will see it typed in the
snapshot instead of submitting.
--snapshot renders the screen after sending, on the same connection: one call
instead of send + snapshot + a guessed sleep. The screen goes to stdout and
the "N bytes sent" summary to stderr, so a pipe gets only the screen, and
-quiet (which drops that summary) composes with it. Every snapshot-only flag
is refused without --snapshot instead of being ignored. They carry
session snapshot's meanings unchanged, --json included, so one drive step
can return structured screen data without a second dial.
session resize --size ROWSxCOLS [--wait-ms MS] [-quiet] <id>
Sets the PTY size from a view attach — no takeover, the controlling client (if
any) keeps its stream. Needs exec_view + exec_resize.
The acknowledgement is real, not assumed: an accepted size is fanned back out
to every observer including the sender, so the command waits for its own size
to come back (--wait-ms, default 2000). No echo → exit 3 and a message
naming both possible reasons. --size is ONE flag spelled ROWSxCOLS
deliberately — --rows/--cols already mean two other things nearby (the
offscreen render on snapshot, the PTY on session new).
session exec [--timeout D] [--json] [--exit-only] [--raw] <id> <cmd>...
The synchronous shortcut for send + snapshot + guess-a-sleep when the
foreground is a POSIX shell. Injects the command (flags before <id>, rest
joined ssh-style), WAITS (default --timeout 30s), and returns the command's
combined stdout+stderr
as logical lines — SGR stripped, \r-overwrite/erase-line applied, NOT
re-wrapped — plus its exit code. The exec process exits with the command's
exit code (124 timeout, 125 error, 126 the foreground shell exited), so it
composes:
if harness-cli session exec "$ID" test -f /tmp/flag; then …; fi
harness-cli session exec --timeout 60s "$ID" 'make test 2>&1 | tail -20'
harness-cli session exec --json "$ID" ps aux # {exit,output,timed_out,shell_exited,duration_ms}Footguns:
- It types into the LIVE foreground shell: state persists across calls
(
cd/exportcarry over) AND shell-terminating commands bite — a bareexit/execends the shell and KILLS the session. To test an exit code, wrap it:(exit N)orbash -c 'exit N'. - stdout/stderr can't be separated (one PTY).
- Single logical line only (
;&&|$()compose fine; a literal newline is rejected). - Non-POSIX-shell foreground (a claude/REPL prompt) → no completion marker →
timeout with a diagnostic (exit 124). Use send/snapshot there. The typed
bytes are NOT rolled back — the command text has already landed in the
foreground program as input (a REPL will show it as a syntax error);
clear the line (
send -e <id> '\x03') before driving on. - A terminal multiplexer is not a shell either, even though the pane inside
it is one. herdr / tmux / screen own the outer PTY and repaint their own
grid onto it, so the command runs in the pane and its output — completion
marker included — appears ON SCREEN, while the outer PTY carries only
redrawn cells. The marker never crosses as the byte sequence
execscans for, so the call times out (exit 124) on a command that already ran to completion. Verified against herdr 0.8.2:echo pong-$$; tty; stty sizeprinted/dev/pts/3and35 146in the pane and its__HEXEC_…_E__0line was plainly visible insnapshot, whileexecreported no completion within 30s. This is the case where the timeout diagnostic's "or the session foreground is not a POSIX shell" reads as wrong and is not. Drive the multiplexer with send/snapshot, or address the inner pane through the multiplexer's own API.
Flag ordering
snapshot / attach flags are order-free (their only positional is the
<id>). send / exec are NOT — their text/cmd is free-form, so flags must
stay before <id>.
Diagnosing a stuck claude worker
Read the worker's row on ls first. lifecycle=waiting means blocked on a
human, idle means its turn ended, and working means it is busy. The
worker's hooks report these, and program= is claude's own report beside them
(see harness-cli skill harness-cli references/task-state.md). Then use
snapshot --detect to see the detail on screen.
blocked is the first two cases below, working the third. A verdict of
unknown means the rules did not recognise the screen — NOT that the worker
is free.
- Permission prompt (worker spawned without auto mode) → answer it:
send "$ID" 1(menu digits usually act alone; if it still sits there, follow withsend -e "$ID" '\r'as its own call — see the delayed-Enter note above for why the CR goes separately). For the future, respawn with--agent-arg --permission-mode --agent-arg auto. - Menu / "resume" style prompt → drive it with arrows + Enter via
send -e. - Spinner / "thinking" → not stuck; long autonomous stretches are normal. Poll snapshot; don't interrupt mid-think.
- Runaway turn you must interrupt →
send -e "$ID" '\x1b'(Esc).
Unsticking the terminal is keyboard work; handing the worker new instructions afterwards still belongs on the agentboard.
After a keystroke-level reset
/clear and /compact leave the worker with no memory of what you agreed on,
while its retained inbound messages stay on the board. Re-brief it over the
agentboard afterwards — and note that an instruction it already carried out
will be re-read as pending unless you retracted it (harness-cli skill
harness-cli → "A reply retires what it answers", and its references/retract-purge.md).
What a session showed before you looked: record
snapshot --raw holds only the replay ring (1 MiB by default). A session
opened with --record (or switched on with record on <id>, which needs
record_persist) keeps the same bytes for its whole run on the server:
harness-cli record ls "$ID" # its runs: size, expiry, recording
harness-cli record get --without-synth "$ID" # the latest run, as --raw prints it
harness-cli record get "$ID#2" | grep -a 'FAIL' # an earlier runReading needs exec_view, like snapshot. Input is never recorded, and an
event-stream session never is (its transcript is its record). A record past
the server's cap keeps the most recent part and says truncated-from in
record ls. --format asciicast writes asciinema's format, for a person to
replay — it is no easier for you to read than the raw bytes.
Parsing raw PTY bytes
A PTY echoes an injected Enter as a bare \r with no LF. When grepping
--raw output or captured PTY bytes, treat \r, \n, and buffer edges all
as line boundaries — matching on \n-terminated lines alone misses markers.
(The rendered snapshot/exec outputs already normalize this.)
Common mistakes
| Symptom | Cause → fix |
-enter shows up typed on screen | Flag placed after <id> → flags before <id> |
exec times out on a REPL/TUI/claude | Foreground isn't a POSIX shell → send + snapshot |
exec timed out but the command demonstrably ran | Foreground is a multiplexer (herdr/tmux/screen): it repaints the grid, so the completion marker never crosses the outer PTY → send + snapshot |
Session died after an exec | Bare exit/exec killed the shell → (exit N) |
| Snapshot shows "input" nobody sent | Faint placeholder/ghost text → confirm with --style |
Regex-parsing the --- styles --- report | It is a projection, not the source → --json --style and read spans[] |
| grep misses a long line in snapshot | Width-wrapped grid → exec (logical lines) or --raw |
| Text sits in the input box, never submits | THIS agent/version ignores a same-burst CR (they differ, and change) → send text, then send -e <id> '\r' separately |
Screen unchanged after send | Render lag (poll longer) or input plumbing broken → nonce echo round-trip |
A repeated key in one send does nothing | Runes in one write arrive as ONE key event ("jjj" matches no binding) → one call per keypress |
| Screen looks garbled in snapshot | Render artifact vs real bytes → --raw and inspect escapes |
A full-screen TUI renders as a few stray lines, and snapshot warns "reported no terminal size" | The session was sized with stty, which the server never sees → session resize / send --resize; combine with --snapshot in one call so the SIGWINCH redraw is what gets captured |
| Can't tell which line the caret is on, or whether one is shown | The rendered text cannot carry it → --json and read cursor |
| A full-screen app's output seems to have vanished | It was on the alternate buffer and the app exited → --json and read alt_screen |
--detect says unknown and you still need to know if anything is happening | Screen rules read the grid, which a pane border or an unknown UI corrupts → read live (--json, or the live: line under --detect); it is measured off the stream, not the grid |
/clear sent over the agentboard did nothing | Payload lands as prompt text, never as a slash command → session send |
await-idle woke you with nothing to do | The peer's agentboard reply was already the completion edge → don't arm one for a peer you asked to report back |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

