Keeping Unattended Logs Readable — Measuring axScreenReader's Plain-Text Rendering Before Adopting It

Run the same task twice and count

Don't go by feel. Run one identical prompt under both conditions and count.

#!/usr/bin/env bash
# capture.sh — run the same task under two conditions and measure readability
set -euo pipefail
 
PROMPT="${1:?usage: capture.sh <prompt-file>}"
OUT="${OUT_DIR:-./_capture}"
mkdir -p "$OUT"
 
# Pin the width. If wrapping moves, line counts stop being comparable.
export COLUMNS=120
 
run_and_measure() {
  local label="$1"
  local raw="$OUT/${label}.raw"
  local plain="$OUT/${label}.plain"
 
  # script(1) supplies a pseudo-TTY. A plain redirect makes Claude Code treat
  # the run as non-interactive and change how it draws, so the two conditions
  # would no longer be comparable.
  script -q -c "claude -p \"$(cat "$PROMPT")\" --output-format text" /dev/null \
    < /dev/null > "$raw" 2>&1 || true
 
  # Build the "body": the same text with control sequences removed.
  perl -pe 's/\e\[[0-9;?]*[A-Za-z]//g; s/\e\][^\a]*\a//g; s/\r//g' "$raw" > "$plain"
 
  local bytes_raw bytes_plain esc lines uniq
  bytes_raw=$(wc -c < "$raw")
  bytes_plain=$(wc -c < "$plain")
  esc=$(perl -ne '$c += () = /\e\[/g; END { print $c + 0 }' "$raw")
  lines=$(grep -c '' "$plain" || true)
  uniq=$(sort -u "$plain" | grep -c '' || true)
 
  printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
    "$label" "$bytes_raw" "$bytes_plain" "$esc" "$lines" "$uniq"
}
 
printf 'label\traw_bytes\tplain_bytes\tesc\tlines\tuniq_lines\n'
( unset CLAUDE_AX_SCREEN_READER; run_and_measure tui )
( export CLAUDE_AX_SCREEN_READER=1; run_and_measure plain )

The script(1) wrapper matters because Claude Code renders differently depending on whether its output is a terminal. Redirect naively with claude ... > log.txt and you get non-interactive output — which is not the log your unattended runs are actually accumulating. If your scheduled work runs under a pseudo-TTY (a CI job runner, a script-based wrapper), measure under one too.

Pinning COLUMNS is the same idea. Change the wrap width and the line count changes with it, and line counts stop meaning anything.

Here is what one real task looked like on my machine — reading a handful of MDX files and checking them for consistency.

These numbers move with your environment and your task. Rather than trusting this table, run capture.sh against your own workflow.

Reading the results — don't stop at the byte count

Raw bytes fell from 412KB to 74KB, an 82% drop. Pleasant, as far as it goes.

But the body grew from 61KB to 72KB — up 17%. There is more actual content in the plain-text run. The TUI folds and elides long output to fit a screen; plain-text rendering just lets it through. Summarize this as "the logs got smaller" and you have thrown that fact away.

The number worth reading was the unique-line ratio:

• tui: 496 / 1,842 = 27%
• plain: 601 / 638 = 94%

Three quarters of the TUI log is the same lines redrawn. That ratio, not the byte count, is what decided whether the log could be read afterward. Bytes are an outcome, not a metric.

You can confirm the practical effect with a trivial count. "Before" is the naive pass over the raw log:

# Before: counting the raw TUI log (redraws get counted repeatedly)
$ grep -o 'Bash(' _capture/tui.raw | grep -c ''
37
 
# After: counting plain-text output (matches the real number of calls)
$ grep -o 'Bash(' _capture/plain.plain | grep -c ''
9

That is precisely the "nine or thirty-seven?" question from that morning. I did not fix how I was counting. I started recording in a form that could be counted.

Folding plain text into a ledger

Once output lands as honest lines, you can fold it line by line — run it through a machine before a human reads it.

#!/usr/bin/env node
// ledger.mjs — read a plain-text log line by line and fold it into JSONL
import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";
 
const [, , file] = process.argv;
if (!file) {
  console.error("usage: node ledger.mjs <plain.log>");
  process.exit(2);
}
 
// Keep classification rules here and nowhere else. Output wording shifts
// between versions, so there should be exactly one place to fix.
const RULES = [
  { kind: "tool_use", re: /^\s*\S{0,2}\s*(Bash|Read|Edit|Write|Grep|Glob)\((.*)\)\s*$/ },
  { kind: "error", re: /\b(Error|error:|failed|Traceback)\b/ },
  { kind: "permission", re: /\b(permission|approve|denied)\b/i },
  { kind: "result", re: /^\s*(Done|Completed|✓)\b/ },
];
 
const counts = new Map();
let lineNo = 0;
 
const rl = createInterface({
  input: createReadStream(file),
  crlfDelay: Infinity,
});
 
for await (const raw of rl) {
  lineNo += 1;
  const line = raw.trimEnd();
  if (!line) continue;
 
  const hit = RULES.find((rule) => rule.re.test(line));
  const kind = hit ? hit.kind : "text";
  counts.set(kind, (counts.get(kind) ?? 0) + 1);
 
  // Emit only classified lines; plain text is counted and dropped.
  if (kind !== "text") {
    console.log(JSON.stringify({ line: lineNo, kind, text: line.slice(0, 300) }));
  }
}
 
const total = [...counts.values()].reduce((a, b) => a + b, 0);
const textRatio = ((counts.get("text") ?? 0) / total) * 100;
 
// Always print the unclassified share. A jump here means the rules went stale.
console.error(
  `summary total=${total} unclassified=${textRatio.toFixed(1)}% ` +
    [...counts.entries()]
      .filter(([k]) => k !== "text")
      .sort((a, b) => b[1] - a[1])
      .map(([k, v]) => `${k}=${v}`)
      .join(" ")
);

Why print the unclassified share every time? Because Claude Code's output wording can change between versions. When a rule quietly stops matching, the ledger starts returning a comfortable lie — "zero errors." Watching the unclassified ratio, and only revisiting the rules when it jumps, means you find out that it broke.

Run through this ledger, the log from that failed night folded down to two permission lines and one error line. A job of reading 400KB became a job of reading three lines.

Split the setting between attended and unattended

When I adopted this, I did not flip the machine. I split it by lineage.

# ~/bin/claude-unattended — unattended runs go through this wrapper
#!/usr/bin/env bash
set -euo pipefail
 
export CLAUDE_AX_SCREEN_READER=1
export COLUMNS=120
 
STAMP="$(TZ=Asia/Tokyo date +%Y-%m-%d_%H%M%S)"
LOG_DIR="${LOG_DIR:-$HOME/logs/claude}"
mkdir -p "$LOG_DIR"
 
RAW="$LOG_DIR/${STAMP}.log"
 
claude "$@" > "$RAW" 2>&1
STATUS=$?
 
# Build the ledger whether it passed or failed. Recording only failures
# leaves you with nothing to compare "normal" against.
node "$HOME/bin/ledger.mjs" "$RAW" > "$LOG_DIR/${STAMP}.jsonl" \
  2> "$LOG_DIR/${STAMP}.summary"
 
exit "$STATUS"

The trailing exit "$STATUS" is there so that the ledger step cannot repaint the task's own exit code. Letting logging concerns contaminate the real verdict makes every later diagnosis harder than it needs to be.

Building the ledger on success too is about having a baseline. Record only failures and you will not know whether tool_use normally sits near ten or near fifty — which means you cannot tell whether tonight was abnormal. Keeping the summary lines from successful runs side by side did more for me than any single failure log.

When I run claude by hand, it is the TUI as before. Progress updating in one place really is easier for a human to follow, and there was no reason to break that.

Four things that are easy to misread

A drop in raw bytes is not "less output"

What shrank is redraw debris, not content. The body may well grow. Keep the storage conversation and the readability conversation apart.

Don't measure with a bare redirect

claude ... > log.txt produces non-interactive output that does not match what your unattended runs accumulate. If they run under a pseudo-TTY, measure under script(1).

Wrapping still depends on terminal width

Plain text is still wrapped text. Without pinning COLUMNS, line counts drift day to day and comparisons quietly stop working.

Don't grow the rule set

The finer the rules, the more silently they break when wording shifts. Isolate them in one place, watch the unclassified ratio, and touch them only when it jumps. That has held up longest for me.

What to do next

Start by running capture.sh against one task you actually run overnight. Ignore the raw byte count and look at the unique-line ratio. If it is well under 50%, that log is already unreadable — you just haven't needed to read it yet.

Once you have that number, swap exactly one unattended entry point over to a wrapper. Moving the machine-wide default can wait until the lineage has run for a few days.

That an accessibility setting turned out to be the cleanest fix for unattended readability was a genuine surprise to me. The audience differs, but the thing being made legible — the shape of the output — turns out to be the same.