Karthi Keyan

Posted on Dec 20

Resolving Agent "Terminal Blindness"

#antigravity #terminal #ai

Overview

"Terminal Blindness" is a condition where an AI coding agent can execute terminal commands but fails to see the resulting standard output (stdout) or standard error (stderr). This is almost always caused by shell integrations and "fancy" prompts that emit non-printable ANSI escape sequences and OSC (Operating System Command) codes.

Works for Kiro & Antigravity AI IDE

The Problem: The "Noise" vs. "Signal" Conflict

1. Escape Sequence Interference

Modern shells often use plugins like ble.sh, Starship, Atuin, or IDE-specific integrations (like VS Code or Kiro). These tools emit hidden sequences to the terminal to handle:

Command success/failure indicators (OSC 633)
Current working directory tracking
Syntax highlighting
Prompt "decorations"

2. The Agent's Perspective

When an agent reads the terminal buffer, its capture tools are designed to filter raw text. If a shell command is wrapped in heavy escape sequences (e.g., a PROMPT_COMMAND that triggers before and after every execution), the capture tool often sees a "mangled" stream. In many cases, the tool fails to synchronize with the output, resulting in an empty string being returned to the agent.

The Solution: The "Early Return" Strategy

The fix involves two architectural changes:

A. Environment Separation

We split the shell configuration into two distinct categories:

Machine Environment (~/.bash_env.sh): Tools, PATHs, SDKs, and toolchain initializations (NVM, Cargo, Flutter, Brew). These emit no output.
Interactive Shell (~/.bashrc): UI/UX enhancements, completions, and shell integrations.

B. Agent Detection & Early Return

We implement a detection block at the very top of ~/.bashrc that triggers when the ANTIGRAVITY_AGENT environment variable is present.

# 1. Load the essential environment first
if [ -f ~/.bash_env.sh ]; then
    . ~/.bash_env.sh
fi

# 2. Detect the agent and short-circuit the interactive "fluff"
if [[ -n "$ANTIGRAVITY_AGENT" ]]; then
    export PS1='$ '      # Pure, simple prompt
    unset PROMPT_COMMAND # Remove hooks that emit invisible codes
    return               # STOP processing the rest of .bashrc
fi

# 3. Everything below this line only runs for the HUMAN user
# (Completions, Shell integrations, aliases, etc.)

Impact & Affected Environments

Operating Systems

This issue is OS-agnostic but is most prevalent on systems where users favor customized developer environments:

Fedora/Ubuntu/Arch Linux: High prevalence due to easy access to ble.sh, zsh, and oh-my-zsh.
macOS: Extremely common with Users running iTerm2 integrations or zsh themes.
Windows (WSL2): Common when users mirror their Linux setups.

Specific Software Triggers

You are likely to encounter this if you use:

Shell Integrations: OSC 633 (VS Code), OSC 133, or IDE-specific shell hooks.
Enhanced Bash: ble.sh is a frequent culprit as it re-implements much of the bash input/output logic.
Prompt Managers: Starship, Oh My Posh, or Powerlevel10k.
History Tools: Atuin or other tools that hook into the command lifecycle.

Summary of Benefits

Agent Sight: Crystal-clear stdout/stderr visibility for the AI.
Zero Human Trade-offs: The user keeps their fancy prompt and workflow tools untouched.
Speed: The agent's shell starts faster by skipping unnecessary completions and UI logic.

DEV Community