JCodeJCode
View as markdown

Troubleshooting

Almost every "it works in my terminal but not in JCode" problem is the same thing: JCode and your terminal aren't searching the same PATH. This page covers how to spot that and fix it.

JCode can't find my provider

A provider you've installed shows as Not installed.

JCode launches the agent CLIs you've already installed, it doesn't bundle them (see Providers). So it has to find the command on its own PATH. If your shell only adds that location to PATH under certain conditions, JCode can miss it.

See what JCode sees

Open Settings → your host → Providers, tap the provider, then tap Diagnostic. The rows that matter:

  • Resolved path — where JCode found the binary, or not found.
  • Daemon PATH — the PATH JCode is searching. Compare it to echo $PATH in a fresh terminal.
  • Version — whether the binary actually runs.

not found together with a Daemon PATH that's missing your binary's directory is the common case: that directory is on your terminal's PATH but not on JCode's.

Fix it

The durable fix is to make sure the command is on PATH for a normal login shell, then restart JCode, see why JCode's environment can differ for why that's the test that matters.

If you'd rather pin it directly, set the binary path in ~/.jcode/config.json:

{
  "agents": {
    "providers": {
      "claude": {
        "command": ["/absolute/path/to/claude"]
      }
    }
  }
}

command is [binary, ...args] and fully replaces the default launch command for that provider. Find the real path with which -a claude. type -a claude also tells you if claude is only a shell alias or function, those won't work, JCode runs the binary directly, so use the path it points to. Restart the daemon after editing (see below).

For alternative endpoints, multiple profiles, custom binaries, and ACP agents, see Custom providers. For per-agent install links, see Supported providers.

Why JCode's environment can differ from your terminal

The same mismatch shows up anywhere JCode runs your tools, an agent, or a terminal, reporting command not found for something you use every day.

When you open the desktop app from the Dock or Finder, the OS hands it a stripped-down environment, not your terminal's PATH. To compensate, JCode runs your login shell once at startup ($SHELL -i -l -c), captures its environment, and hands that to the daemon and everything it spawns. The rule of thumb: if a brand-new terminal can run the command, JCode should too. That's also the test, open a fresh terminal and try it there.

When you start the daemon yourself from a terminal (jcode), there's no login-shell step, it simply inherits that terminal's environment.

Either way, the fix for a missing tool lives in your shell config (.zshrc, .zprofile, …), not in JCode. Tools installed through version managers (asdf, mise, nvm, …) are the usual offenders, make sure they initialize for a clean login shell, not only inside one you've already opened.

This login-shell step runs on macOS and Linux. On Windows, JCode uses the environment it was launched with.

Reading the logs

  • Desktop app — the login-shell resolution is logged here. Look for [login-shell-env]: applied means it worked (it logs the PATH before and after); failed; keeping inherited env means it fell back to the stripped-down environment, with a reason (a timeout, a non-zero exit from your shell config, no output, …). A slow or erroring .zshrc/.zprofile is the usual cause.
  • Daemon — ~/.jcode/daemon.log ($JCODE_HOME/daemon.log if you've set a custom home).

Desktop app log location:

PlatformPath
macOS~/Library/Logs/JCode/main.log
Linux~/.config/JCode/logs/main.log
Windows%APPDATA%\JCode\logs\main.log

I changed config.json but nothing happened

config.json is read when the daemon starts. Restart it after editing:

jcode daemon restart

Or in the app, open Settings → your host → Overview and use Restart daemon. Running agents keep going, and clients reconnect automatically.

Still stuck?