Skip to main content

​
Keep Termix Updated

CLI agents (Claude Code, Codex, Gemini CLI, OpenCode) are actively developed and may change their telemetry format, config file structure, or command-line flags. When this happens, Termix needs to be updated to match. Always check for the latest version when something stops working: 
npm update -g termix-cli
Or if you use npx: 
npx termix-cli@latest

​
Telemetry Not Working

​
”Telemetry not configured” toast keeps appearing

This means the agent isn’t sending OTLP logs to Termix within 10 seconds of launching. For Codex or Gemini CLI:
  1. Click Configure automatically on the toast
  2. Restart the session when prompted
  3. If it still doesn’t work, check if the config file was written correctly:
    • Codex: ~/.codex/config.toml should have an [otel] section
    • Gemini: ~/.gemini/settings.json should have a telemetry object
For Claude Code: Telemetry should work automatically. If it doesn’t:
  • Make sure you’re launching Claude Code from Termix (not from a separate terminal)
  • Check that claude is in your PATH

​
Status indicator stuck on idle

If the status dot shows “zzZ” even when the agent is clearly working:
  • The agent may not be producing enough output to trigger burst detection (needs output within a 2-second window)
  • For OpenCode: make sure the bridge plugin is installed in ~/.config/opencode/plugins/
  • Try restarting the session

​
Status indicator stuck on working

  • The agent may still be processing in the background
  • If it’s genuinely idle, wait 2+ seconds — the burst timeout should reset
  • For OpenCode: the plugin may have disconnected. Restart the session.

​
Session Resume Issues

​
”Resume” button doesn’t appear

Resume requires:
  1. The agent preset has canResume enabled
  2. A session ID was captured during the original session
  3. Termix was shut down gracefully (Ctrl+C, not kill -9)
If the session ID wasn’t captured (telemetry wasn’t configured), resume won’t be available.

​
Resume starts a new session instead of continuing

The agent may not recognize the session ID. This can happen if:
  • The agent was updated and its session format changed
  • The session expired on the agent’s side
  • The session ID was captured incorrectly
Try starting a fresh session instead.

​
Agent Not Appearing in Launcher

  • Open Settings > CLI Agents and make sure the agent is enabled
  • Check that the agent’s command is installed and in your PATH. Try running the command directly in a terminal: 
    which claude    # or codex, gemini, opencode
  • If the command isn’t found, install the agent following its official documentation

​
Terminal Display Issues

​
Colors look wrong

  • Check if your theme’s polarity (light/dark) matches the UI mode. A dark theme in light mode (or vice versa) can cause contrast issues.
  • If you see a restart banner, click it — the terminal needs to restart for theme changes to take effect.
  • Try switching to a different theme in Settings > Appearance

​
Terminal not resizing properly

  • Termix uses a ResizeObserver to track terminal dimensions. If the terminal appears cut off, try:
    • Refreshing the browser page
    • Clicking on the session to re-focus it
    • Resizing your browser window slightly

​
Text appears garbled

  • Some agents use complex ANSI sequences that xterm.js may not render perfectly
  • Try a different terminal theme — some handle edge cases better
  • If persistent, check if the agent has a “plain output” mode

​
Connection Issues

​
”WebSocket disconnected”

The browser lost its connection to the Termix server. This usually means:
  • The Termix server crashed or was stopped
  • Your computer went to sleep and the connection timed out
Refresh the page to reconnect. Your sessions are still running on the server (if it’s still up).

​
Port 4000 already in use

Another process is using port 4000. This could be a previous Termix instance or another application. 
lsof -i :4000
Find and stop the process using the port, then start Termix again.

​
OpenCode Plugin Issues

​
Plugin not connecting

  1. Verify the plugin file exists: 
    ls ~/.config/opencode/plugins/termix-bridge.js
  2. Make sure Termix is running before launching OpenCode
  3. Check that OpenCode loads plugins from ~/.config/opencode/plugins/

​
Wrong session matched

The OpenCode bridge matches sessions by working directory. If you have multiple OpenCode sessions in the same directory, they may get mixed up. Use different working directories for different sessions.

​
Getting Help

If none of the above resolves your issue:
  1. Check the GitHub Issues for known problems
  2. Open a new issue with:
    • Your Termix version
    • The agent and version you’re using
    • Steps to reproduce the problem
    • Any error messages from the browser console or terminal