Add a screen-reader-friendly Codex TUI mode
Open 💬 6 comments Opened Apr 30, 2026 by taylorarndt
💡 Likely answer: A maintainer (github-actions[bot], contributor)
responded on this thread — see the highlighted reply below.
I know external contributions may not be open right now, but I have a local fix ready if the team wants it or wants to use it as a reference.
VoiceOver users currently hear decorative terminal UI as content while Codex is working. For example, active command/status rows can be announced as repeated spaces, bullets, "running", and box-drawing characters. This interrupts reading code and makes it hard to review terminal output while Codex is still producing updates.
The main pain points:
- Live command/status rows are re-rendered with spinner/bullet/shimmer-style decoration.
- Box drawing such as
│and└is announced as "box drawing". - When new content arrives, VoiceOver may re-read older completed transcript content, causing the user to lose their place.
Recommended behavior:
- Add
codex --screen-readerorcodex --accessible. - Disable spinner/shimmer/decorative bullets in that mode.
- Render plain indentation instead of box drawing.
- Minimize redraws that cause completed history to be treated as new spoken content.
- Keep the current visual TUI unchanged for users who want it.
I have a branch with a first patch that starts by making the no-animation path quieter for active exec/status rows and removing box drawing from exec output prefixes.
6 Comments
I pushed the local reference branch here: https://github.com/taylorarndt/codex/tree/fix/voiceover-screen-reader-tui\n\nVerification run locally:\n\n``
text\ncargo test -p codex-tui\n``\n\nThe patch keeps the default visual TUI path unchanged and only makes the existing no-animation path quieter: active exec/status rows omit spinner/bullet decoration, and exec output prefixes use plain indentation instead of box drawing.Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
Thanks for the suggestion. As you are aware, we already have the beginnings of this with the
animations = falseconfig flag, which you can add to the[tui]section of your config file. This disables all spinners, shimmers, and other animations that can interfere with a screen reader. I like the approach you've explored where we build upon this existing feature for incremental improvements.Update on the proof-of-concept branch: I expanded it to remove additional box-drawing prefixes from more transcript surfaces, including status details, unified exec interaction input, MCP detail rows, plan updates, image/file detail rows, multi-agent event details, and multi-file diff headers.\n\nFor local macOS VoiceOver testing, I am also running the patched binary with no alternate screen so the terminal behaves more like normal scrollback instead of a fullscreen redraw surface. That is a mitigation for the issue where VoiceOver can start reading from the top/older history when new content arrives.\n\nI also found another related Mac issue: character echo while typing in the TUI composer is not reliable for VoiceOver, likely because the terminal UI owns raw keyboard input rather than exposing a native text field. I think that should be part of the screen-reader-friendly mode design as well.\n\nVerification still passes locally:\n\n``
text\ncargo test -p codex-tui\n``I've introduced a small change that fixes some recent regressions. Animations were added that were not conditioned on the
tui.animationsconfig key. These are not fix, and I've restructured the code to help avoid future regressions like this.This doesn't address the full feature request, but it's a start.
I just came across this, I wonder if there's much progress on this as the last thing that was done appears to have been back in May.