Troubleshooting

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

$ initech --verbose