Troubleshooting WezTerm for NoirCode

Even with a clean setup, developers occasionally run into issues. Here are the most common problems and fixes.

WezTerm Opens but PowerShell Doesn’t Start

Symptoms

Error starting shell Blank terminal Terminal closes immediately

Solutions

Verify PowerShell location:

where pwsh

Update .wezterm.lua:

default_prog = { "pwsh.exe" }

Or use the full path:

default_prog = { “C:\Program Files\PowerShell\7\pwsh.exe” }

NoirCode Command Not Found

Symptoms

‘noircode’ is not recognized

Solutions

Check installation:

noircode --version

If missing:

npm install -g noircode

bun install -g noircode

Verify your PATH:

$env:PATH

Restart WezTerm after updating environment variables.

Fonts Look Wrong

Symptoms

Broken icons Misaligned text Poor rendering

Solutions

Install a Nerd Font:

JetBrainsMono Nerd Font FiraCode Nerd Font Cascadia Code Nerd Font

WezTerm configuration:

font = wezterm.font("JetBrainsMono Nerd Font")

Slow Terminal Performance

Symptoms

Lag when scrolling High CPU usage

Solutions

Reduce scrollback:

scrollback_lines = 5000

Disable excessive transparency:

window_background_opacity = 1.0

Update graphics drivers.

Split Panes Not Working

Symptoms

Shortcut appears to do nothing.

Solutions

Confirm you’re using:

ALT + SHIFT + ENTER

for vertical splits.

If custom keybindings are configured, check .wezterm.lua for overrides.

SSH Sessions Disconnect

Symptoms

Remote server disconnects unexpectedly

Solutions

Use SSH keepalives:

Host * ServerAliveInterval 60 ServerAliveCountMax 3

Store in:

~/.ssh/config

Beginner NoirCode + WezTerm Setup Checklist

Use this checklist when setting up a new development workstation.

Core Requirements Install WezTerm Download WezTerm Launch successfully Verify terminal opens Install PowerShell 7 pwsh

PowerShell launches PowerShell version verified Install Git git —version

Git installed Git available in PATH Install Node.js node -v

Node.js installed npm available Install Bun (Optional) bun —version

Bun installed Install NoirCode noircode —version

NoirCode installed CLI accessible Configure WezTerm Create .wezterm.lua Set PowerShell as default shell Choose color scheme Configure font Test Developer Workflow

Open WezTerm and run:

git status

node -v

bun -v

noircode

All commands work Understanding WezTerm Shortcuts

One reason WezTerm is excellent for NoirCode is that it allows multiple terminals in a single window.

Think of it like having multiple monitors inside one terminal.

Tabs

Tabs are separate terminal sessions.

New Tab CTRL + SHIFT + T

Creates a fresh terminal.

Example:

Tab 1 -> NoirCode Tab 2 -> Git Tab 3 -> Docker

Next Tab CTRL + TAB

Move to the next terminal tab.

Previous Tab CTRL + SHIFT + TAB

Move backward through tabs.

Close Tab CTRL + SHIFT + W

Close the active tab.

Split Panes

Panes let you see multiple terminals simultaneously.

Vertical Split ALT + SHIFT + ENTER

Creates:

┌─────────┬─────────┐ │ Pane 1 │ Pane 2 │ └─────────┴─────────┘

Great for:

NoirCode | Git

Horizontal Split CTRL + ALT + SHIFT + ENTER

Creates:

┌───────────────┐ │ Pane 1 │ ├───────────────┤ │ Pane 2 │ └───────────────┘

Great for:

NoirCode ──────── Logs

Navigate Between Panes

Common defaults:

ALT + Arrow Keys

Example:

ALT + ← ALT + → ALT + ↑

ALT + ↓

Move focus between panes instantly.

Resize Panes

Typically:

CTRL + ALT + Arrow Keys

Grow or shrink the active pane.

Example:

NoirCode needs more space?

Expand its pane while reducing a log window.

Example NoirCode Workspace Layout Beginner Layout ┌─────────────────────┐ │ NoirCode │ ├─────────────────────┤ │ PowerShell │ └─────────────────────┘

Top:

noircode

Bottom:

git status

Intermediate Layout ┌────────────┬────────────┐ │ NoirCode │ Git │ ├────────────┼────────────┤ │ Build │ Tests │ └────────────┴────────────┘

Useful for active development.

Advanced Layout ┌────────────────────────────┐ │ NoirCode Agent │ ├────────────┬───────────────┤ │ Git │ PowerShell │ ├────────────┼───────────────┤ │ Build │ Docker Logs │ └────────────┴───────────────┘

This gives you:

AI assistant source control build output runtime logs shell access

all visible at the same time.

Recommended First-Day Setup

For a new NoirCode user on Windows 11:

Install WezTerm Install PowerShell 7 Install Git Install Node.js/Bun Install NoirCode Learn: Ctrl + Shift + T (new tab) Alt + Shift + Enter (vertical split) Ctrl + Alt + Shift + Enter (horizontal split) Alt + Arrow Keys (switch panes) Create a four-pane workspace with: NoirCode Git Build server Test runner

Once you’re comfortable with tabs and panes, WezTerm becomes an ideal command center for AI-assisted development with NoirCode.