Windows Terminal Environment

The legacy console bundled with Windows (cmd.exe / conhost) ships with a default font that contains no emoji or Nerd Font icon glyphs, nor does it support true color, so zqagent can only fall back to degraded rendering here: ✅ becomes [OK], table borders degrade to ASCII, and colors look washed out. Functionality is unaffected, but it looks noticeably worse than on Linux / macOS.

This page covers the recommended configuration, plus zqagent's built-in automatic guidance.

Recommended Configuration

Layer	Recommendation	Notes
Terminal	Windows Terminal	True color, GPU acceleration, tabs and split panes; can host cmd / PowerShell / WSL at the same time
Font	Nerd Font (monospaced)	Supplies the missing icon glyphs, e.g. JetBrainsMono Nerd Font
Shell	PowerShell 7 or Git Bash	Scripting experience is closer to Linux
Prompt	oh-my-posh / starship	Icon-based prompt with git status

1. Install Windows Terminal

Option A (recommended; Win10 1809+ ships with winget):

winget install --id Microsoft.WindowsTerminal -e --accept-source-agreements --accept-package-agreements

Option B: open Microsoft Store, search for Windows Terminal, and install it.

2. Install a Nerd Font

winget install --id DEVCOM.JetBrainsMonoNerdFont -e --accept-source-agreements --accept-package-agreements

Any one of the equivalent fonts works too (use winget search nerd to look up package names): CaskaydiaCove Nerd Font, FiraCode Nerd Font, Hack Nerd Font. You can also download them from the Nerd Fonts website, extract the archive, then right-click the font file → "Install for all users".

Note: A Nerd Font is not the same as plain JetBrains Mono. After installing, make sure to select the variant with the Nerd Font suffix in your terminal, otherwise icons will still render as boxes.

3. Set It as the Default Terminal

Windows Terminal → Settings → Startup → "Default terminal application" → select Windows Terminal. After that, anything launched from cmd.exe / PowerShell will also open in Windows Terminal.

4. Select the Font in Windows Terminal

Settings → Profiles → Defaults → Appearance → Font → select JetBrainsMono Nerd Font.

Or edit settings.json directly:

{
  "profiles": {
    "defaults": {
      "font": { "face": "JetBrainsMono Nerd Font", "size": 11 }
    }
  }
}

5. Make the Shell Nicer (Optional)

winget install --id Microsoft.PowerShell -e      # PowerShell 7
winget install --id JanDeDobbeleer.OhMyPosh -e   # oh-my-posh prompt

zqagent's Behavior

• It probes terminal capabilities at startup: when emoji / Unicode are unsupported, it automatically degrades its own output to ASCII markers (✅→[OK], ❌→[x], ⚠️→[!]), and Markdown tables switch to ASCII borders as well.
• It proactively offers guidance when a legacy console is detected: it first asks whether to have the agent install Windows Terminal and a Nerd Font automatically via winget (each command goes through approval one by one); if the install fails, or no LLM connection is configured yet, it simply prints the manual installation walkthrough.
• Related environment variables:

Variable	Effect
ZQAGENT_TERM_SETUP=0	Disables the terminal setup guidance at startup
ZQAGENT_TERM_SETUP=1	Forces the guidance to trigger (handy for previewing the walkthrough)
ZQAGENT_EMOJI=1/0	Forces emoji and Unicode tables on / off
ZQAGENT_ASCII=1	Forces degradation to ASCII markers

Troubleshooting

Symptom	Fix
winget is not available	Install "App Installer" by searching Microsoft Store, or use Option B above
Icons still render as boxes	The font selected in the terminal is not the Nerd Font variant
emoji still shows as ?	Confirm you are running in Windows Terminal and that ZQAGENT_EMOJI has not been set to 0
Colors look washed out	conhost does not support true color; switch to Windows Terminal

Next Steps

• CLI Usage
• Built-in Tools