Troubleshooting initech

$ initech doctor

  Prerequisites
  ok  initech v1.3.0
  ok  claude (Claude Code)
  ok  git 2.44.0
  ok  Terminal: 212x56 (meets 80x24 minimum)

  Project Health
  ok  initech.yaml valid
  ok  6 workspaces found
  ok  All CLAUDE.md files present

  All checks passed.

"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 or use initech at to schedule the message for later.

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.

MCP client can't connect

The MCP server isn't reachable or auth is failing.

Check:

• Is mcp_port set in initech.yaml? Omitting it disables the MCP server.
• Does the bearer token match? Check the TUI banner or use the MCP Setup Modal (` then mcp).
• For remote connections, is mcp_bind set to 0.0.0.0? The default is 0.0.0.0, but if set to 127.0.0.1, only local connections work.
• Test with curl: curl -H "Authorization: Bearer <token>" http://<host>:9200/mcp

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>).

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 doctor" as a first diagnostic

Doctor checks the binary, claude, git, terminal size, and PATH in one shot. Most install-time issues on Windows show up here before they cause confusion in initech init or the TUI.

Fix: When something is off, run initech doctor first and fix anything it flags red. Re-run after each fix. Only when doctor reports "All checks passed" should you move on to opening a GitHub issue.

$ initech --verbose