Troubleshooting

Most problems with tCode fall into a small number of categories: it cannot be found on your PATH, a required dependency like git is missing, or something failed mid-session and left a reference you can use to dig further. This page covers each of those directly.

"tcode is not recognized" or "command not found"

This means the folder pip installed the tcode entry point into was not on your terminal's PATH when that terminal session started. Open a brand new terminal window and try again: tCode adds itself to PATH automatically the first time it runs successfully, so this typically resolves itself after that first run and does not come back. If it persists across multiple new terminals, confirm the install actually succeeded with pip show tcode-cli.

"tCode requires git to be installed"

Checkpoints, and the /rewind command that depends on them, are built on git commits internally, so tCode needs git available on your PATH to use them. Install it from git-scm.com, then restart tCode; it checks for git again on every startup.

Login is not completing

If the browser window tCode opens for login does not lead back to a working session, confirm the code you entered was typed exactly as shown, and that you are entering it in the terminal that opened the browser tab, not a different one. If the code has expired, running /login again generates a fresh one.

A crash with a reference ID

If tCode hits an unexpected error deep enough that it cannot continue the current turn, it prints a short reference ID and writes the full details to a file under ~/.tcode/crashes. That file has everything needed to understand what happened; the session itself keeps running rather than exiting, so you can continue working while looking into it separately.

A connector command says it is not linked

This means that specific provider, Gmail, Notion, GitHub, or Linear, has not been connected to your tAI account yet. Link it from tai.artfical.com → Settings → Connectors; once linked there, it works immediately in tCode on any machine signed in with that same account.

A permission prompt does not seem to be waiting for input

If a permission prompt appears but typing does not seem to register, confirm you are typing into the same terminal window tCode is running in rather than a different one, and that no other program has stolen keyboard focus. tCode always waits indefinitely for an answer to a permission prompt; it never times out or proceeds on its own.

A remote-triggered turn does not appear in the browser

If a machine was paired previously but a prompt sent from the web app does not seem to reach it, confirm tCode is actually running on that machine; pairing only works while a session is active. If the machine was recently unpaired from the web app's Remote Control settings, tCode notices this on its next reconnect attempt and will need /pair run again with a fresh code.

A change made by tCode is not what you wanted

This is not strictly an error, but it is the most common reason people look for help right after a turn finishes. /rewind undoes the most recent turn's file changes immediately; see Checkpoints and rewind for exactly what it restores and how to go back further than one turn if needed.

Output looks garbled or colors are missing

This is almost always a terminal compatibility issue rather than a tCode problem: an older or non-standard terminal emulator may not support the ANSI color codes tCode uses for syntax highlighting and status indicators. A modern terminal, the default terminal on a recent version of Windows or a standard Linux distribution, handles this correctly; /theme also lets you try a different color scheme if the issue is specifically about color contrast rather than garbled characters.