Troubleshooting

"Unable to connect to the daemon"

The desktop app shows Connecting to the daemon… and then an error — the host it starts didn't come up, or isn't answering where the app expects.

• Retry, then restart the app. The host starts with the app, so restarting is the fix for most cases and the message says so.
• Check for a stale override. Open Settings → Daemon. If the "Daemon URL" field is set, the app is pointing somewhere specific instead of discovering the local host — clear it to auto-discover, or correct it.
• Check the log (paths in local data) if it keeps failing; the host's startup output goes there.

Host refuses to start: "already running"

If a second host starts for the same install, it exits immediately with [linkcode/daemon] already running (pid {pid}) at {url}. Only one runs at a time — a second would split the same local database. This normally resolves itself; if it doesn't, quit LinkCode fully (check for a leftover process) and start it again.

Port already in use

The host listens on port 19523 by default and hunts upward (19524, 19525, … up to 19532) if something else holds it. If every port in that range is taken, it fails with no free port for socket.io in 19523–19532. Free one of them, or set LINKCODE_PORT to move the host elsewhere. Clients discover the real URL automatically from ~/.linkcode/runtime.json (see local data).

An agent won't start

Check Settings → Agents for its runtime state:

• Not installed — press Download, or install the CLI yourself. Grok Build is always the second case: LinkCode can't download it.
• Signed out — press Sign in. Claude Code and Codex complete the flow in your browser; if the page shows an authorization code, paste it back into LinkCode.
• Unverified — the install found on your machine isn't the version this LinkCode release was tested against. Usually fine; download the paired version if it misbehaves.

For OpenCode specifically, a thread that fails with opencode: failed to start server (...) means no usable opencode binary was found. Let LinkCode download one, or install it yourself where the host can see it — its PATH, or ~/.opencode/bin.

A Claude Code turn ends instantly with no output

Usually expired or invalid credentials. Re-authenticate from Settings → Agents, or run claude in a terminal and sign in there.

Terminals unavailable

pty sidecar not configured: terminals are unavailable on this host means the terminal helper isn't reachable. The packaged app ships it, so this points at a damaged install — reinstall LinkCode. It's expected when running a host from source without building the helper first.

Pull request status is missing

The Git overview needs the GitHub CLI on the host machine. The panel says which half is missing: install gh, or run gh auth login. Repositories with no remote, or on an unsupported host, show no pull request section at all.

The Simulator panel says setup is incomplete

The panel lists what's missing — Xcode and its command-line tools, an iOS runtime, a simulator device — and ticks each one off as you fix it, including downloading the runtime for you (several gigabytes; leave the panel open). Simulators are macOS-only. Some hosts can list devices but not stream them, in which case the panel says so rather than pretending to connect.

macOS Gatekeeper / Windows SmartScreen

LinkCode's desktop builds are signed and notarized (macOS) or signed via Azure Trusted Signing (Windows). You shouldn't see a Gatekeeper or SmartScreen warning on a properly downloaded release build. If you do, make sure you downloaded the installer directly from a LinkCode release rather than a mirrored copy.

Where are the logs?

The desktop app captures the host's output to a file — ~/Library/Logs/LinkCode/main.log on macOS, %APPDATA%\LinkCode\logs\main.log on Windows, ~/.config/LinkCode/logs/main.log on Linux. A host you started yourself from a terminal logs to that terminal instead.