Troubleshooting initech

$ which initech          # installed and on PATH
$ claude --version       # Claude Code installed and on PATH
$ git --version          # git available
$ tput cols; tput lines # at least 80 x 24

"No conversation found" on agent startup

Claude Code's --continue flag tries to resume a prior conversation. On first run (or after clearing state), there's no conversation to resume.

Fix: Restart the agent. Claude will start a fresh conversation and the error clears. Use initech restart <agent> or press ` then type restart in the TUI.

Agent stuck at permission prompt

The agent is waiting for the operator to approve a tool call. This happens when the agent runs without --dangerously-skip-permissions (supervised mode).

Fix: Focus the pane and approve/deny the prompt. If this agent should be autonomous, add --dangerously-skip-permissions to its claude_args in role_overrides.

initech send returns "agent not found"

The target agent name doesn't match any running pane. Agent names are case-sensitive and must match the roles list in initech.yaml.

Fix: Check the exact name with initech status. For remote agents, use host:agent format (e.g., workbench:eng1).

Message sent but agent didn't respond

initech send guarantees delivery to the PTY, but the agent might be busy, at a prompt, or in a state where the input isn't processed as expected.

Fix: Peek first to see what the agent is doing: initech peek <agent> -n 10. If stuck, restart the agent. If busy, wait for it to go idle and send again.

Cross-machine connection refused

The TUI can't reach the remote daemon.

Check:

• Is initech serve running on the remote machine?
• Is the addr in your remotes config correct? (IP and port)
• Is a firewall blocking the port? Try nc -zv <host> <port>
• Do both sides have the same token?
• If using listen: ":7391" (bare port), the daemon binds to 127.0.0.1. Use listen: "0.0.0.0:7391" to accept remote connections.

TUI rendering looks broken

Garbled output, wrong colors, or misaligned panes.

Fix:

• Make sure your terminal supports 256 colors. initech sets TERM=xterm-256color for agent panes.
• Resize your terminal. Very small terminals cause layout issues. Minimum is 80x24.
• Try initech --reset-layout to start with auto-calculated grid defaults.
• If using tmux or screen as your outer terminal, make sure it passes through colors and mouse events.

Agent shows "idle" but is actually working

Activity detection reads Claude Code's JSONL session logs. If the log isn't being written (unusual), or if the agent is a non-Claude runtime that doesn't produce JSONL, the TUI can't detect activity.

Fix: For Claude Code agents, this is rare and usually resolves on its own. For non-Claude agents (Codex, OpenCode), activity detection may not work. Peek at the agent to check status manually.

initech init fails with "invalid role name"

Role names must contain only letters, digits, hyphens, and underscores. Spaces, dots, slashes, and special characters break IPC parsing and filesystem paths.

Fix: Use names like eng1, my-agent, data_scientist. Not eng 1 or eng.1.

Agent error loop (same error repeating)

The agent is stuck retrying an action that keeps failing. Common with compile errors, missing dependencies, or permission issues.

Fix: Peek at the agent to identify the error. Then either send a corrective message (initech send eng1 "stop, the issue is X") or restart the agent with a different instruction (initech restart eng1 --bead <id>).

A secondary window froze, then its agents appeared in window 1

That is the designed recovery, in two speeds. If a secondary window closes or its process dies, its agents fold back into window 1 immediately. If the window hangs — the process is alive but not responding, for example a frozen terminal tab — initech notices within about 12 seconds and folds its agents back the same way. Brief stalls of a few seconds do not trigger this; only a genuinely unresponsive window does. Your agents never stop running and are never hidden during any of it.

Fix: nothing to repair. When the window is usable again, rerun initech --window N — its groups move back exactly as they were.

Group moves are refused and a notice mentions the assignment store

The file that records which groups belong to which window (.initech/assignments.yaml) is corrupt. initech degrades to read-only: everything renders in window 1, moves are refused with a notice, and the corrupt file is left untouched for you to inspect.

Fix: repair the file, or simply delete it (assignments reset to everything-on-window-1), then reopen the agents modal. No restart is needed.

A chime played and a list appeared in the top-left corner

An agent is waiting on your input. The list shows each waiting agent, its question, and how long it has waited — oldest on top. The lifecycle is: one chime when the agent starts waiting, one reminder if it is still unanswered after two minutes, then silence while the list persists. Answering the agent clears its row automatically; the box disappears when nobody is waiting.

To silence the sound: set attention.sound: none in initech.yaml. The list continues to work.

An agent shows "dialog detected" with no question text

That agent's dialog was detected from its screen rather than from a precise signal — the case for codex and generic agents. The list states only what it actually knows; go to the pane to see the dialog itself. Claude Code agents show the real question text.

ConPTY not available / "terminal emulation failed"

initech requires ConPTY, which shipped in Windows 10 build 17763 (version 1809). Older builds, including Windows 8.1 and Windows Server 2016, do not have it.

Fix: Run Windows Update and confirm with winver that you are on 1809 or later (build 17763+), or any Windows 11. If you cannot upgrade, install via WSL2 instead.

Antivirus or SmartScreen blocks initech.exe

Some endpoint security tools quarantine fresh-downloaded executables. Windows Defender SmartScreen can also show "Windows protected your PC" the first time the binary runs.

Fix: For SmartScreen, click More info then Run anyway. For corporate antivirus, ask IT to allow-list %LOCALAPPDATA%\initech\bin\initech.exe. The release binaries are unsigned today; code-signing is on the roadmap.

"initech: command not found" after install

The PowerShell installer updates your User PATH, but only new terminals pick up the change. Group policy on managed devices can also override user PATH at login.

Fix: Close every PowerShell window and open a fresh one. If still missing, confirm %LOCALAPPDATA%\initech\bin\initech.exe exists and that echo $env:PATH includes that directory. On a managed device, ask your admin to add the path machine-wide or via login script.

TUI looks broken: boxes for glyphs, missing colors, garbled redraws

You are running initech inside legacy cmd.exe or the old console host, which has limited Unicode and ANSI support. initech's TUI was designed for modern terminal emulators.

Fix: Install Windows Terminal from the Microsoft Store and run initech from there. WezTerm and Alacritty work too. The legacy conhost.exe window does not.

$ initech --verbose