Tool guide
Rescue plan
The agent that fixes problems is the agent that is broken. So the repair route cannot run through it: you need a second pair of hands that does not share its failure, and an order to check things in.
What this fixes
"The agent is broken" covers four different failures, and they have almost nothing in common. Spending ten minutes naming the layer saves an hour of reinstalling the wrong thing.
- It will not start. Installer, runtime, permissions, antivirus quarantine, a config file that is no longer valid JSON.
- It starts, but nothing you type arrives. Input handling: the window has focus but the input box does not, an IME is stuck, a global hotkey from another program is eating keystrokes.
- It starts and errors on every request. The account layer: expired key, wrong base URL, proxy or VPN in the middle, a system clock that is far enough off to fail TLS.
- It answers, but the work never lands. The write layer: the folder is read-only, the process is running in a sandbox, or it has been pointed at a directory that no longer exists.
Build the rescue kit before you need it
- A second agent, already installed and logged in. Different vendor, free tier is fine. It does not need to be good; it needs to run on the same machine and be able to read files and run commands.
- A terminal you can trust. PowerShell or Terminal, outside the agent. If the agent is the only way you know to run a command, that is the actual problem.
- A copy of the config folder — the folder holding the agent's settings, saved to a second drive, dated. Not the keys themselves, just the shape of the config, so you can see what changed.
- One file that says where things are: install path, config path, log path. Three lines. Write it while everything works, because you will not be able to look it up later.
Diagnose in this order
- Read the log before touching anything. The first error, not the last. Most failures state the cause in line three and then print forty lines of consequence.
- Check the clock and the disk. A system clock more than a few minutes out breaks TLS with a message about certificates. A full drive breaks writes with a message about permissions. Both are five-second checks and both get misdiagnosed as "the vendor is down".
- Separate the account from the client. Call the same API with a different client — the other agent — using the same key. If that works, the key is fine and the client is broken. If it fails, the client is fine and the account is broken.
- Start it with a clean config. Rename the config folder, launch, see whether it starts. If it does, the problem is one line in your config; bisect by restoring half of it.
- Reinstall over the top. Not uninstall-then-install. Over the top keeps local data; uninstall often does not. If the installer offers "repair", take it.
- Use the second agent for the rest. Paste the log into it and have it read the files. It will do the searching while the broken one sits idle.
Where this goes wrong
- Uninstalling first. It is the most common way to turn a ten-minute fix into a lost afternoon of local history, saved prompts and session files. Try over-the-top first, every time.
- Copying a config folder from another machine. It brings the other machine's paths with it, and the failure looks like a permissions bug. Copy the file, then edit the paths.
- Rotating the key as step one. Then you have two changes to reason about instead of one, and the old key is gone. Verify the key from a different client before replacing it.
- Deleting the log to "start fresh". The log is the only witness to the failure. Move it, do not delete it.
- Trusting the agent to diagnose itself. A client with a broken network stack will report the server as down with complete confidence.
Checklist
- You know which of the four layers failed, in words, before you changed anything.
- A second agent is installed, logged in, and has read a file on this machine today.
- The log from the failure is saved somewhere the reinstall cannot touch.
- Config folder backed up, dated, on a second drive.