> ## Documentation Index > Fetch the complete documentation index at: https://alike.help/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Find your problem, check the cause, and fix it. Start with the doctor. It finds most problems: ```bash theme={null} npx @alikeai/setup --doctor ``` Then find your problem below. For a message that you see, search [Error messages](https://alike.help/help/error-messages.md). ## Install ### No agents found The installer prints `No supported coding agents found (scanned ). Nothing to do.` If it says `scanned 0`, check the agent IDs in `--harness=`. The installer finds each agent by its settings folder. The folder exists only after you run the agent once. 1. Open the agent and run one short session. 2. If you moved Claude Code's or Codex's settings folder, set `CLAUDE_CONFIG_DIR` or `CODEX_HOME` to the absolute path. 3. Run the installer again. See [How the installer finds each agent](https://alike.help/get-started/supported-agents.md#how-the-installer-finds-each-agent). ### The installer refuses a settings file The installer prints `Refusing to touch : it exists but is not valid JSON`. The file contains comments or other content that is not strict JSON. This is common in Zed and VS Code settings. The installer stops wiring that agent and exits with code `1`. Changes to the agent's other files stay in place. 1. Remove the comments from the file, or fix the JSON. 2. Run the installer again. For VS Code's `settings.json`, the installer does not fail. It asks you to add `"chat.hooks.enabled": true` by hand. ### An MCP server named "alike" already exists The installer prints `Refusing to overwrite an existing MCP server named "alike"`. Another server in that file uses the name `alike`. Rename or remove that entry, then run the installer again. ### I typed a flag, but the installer ran a full install The installer ignores flags that it does not know, and flags with a space instead of `=`. Check the spelling, for example `--doctor`, and use `--harness=claude`, not `--harness claude`. A full install is safe to run again. ### Windows The installer prints `Alike setup does not support Windows yet.` and changes nothing. Use macOS or Linux. You can still connect MCP clients on Windows by hand. See [Connect an MCP client](https://alike.help/reference/mcp-server.md). ## Pairing ### The pairing link opens the Alike home page You are not signed in. Sign in first. Then enter the code by hand under **Enter your pairing code** on the **Connect your agents** page, or in **Settings → AI Agents**. ### The code does not work The web app shows `That code is invalid or has expired.` A code works for 10 minutes and one time only. Run `npx @alikeai/setup --doctor` to get a new code. Check that you type the code from the terminal, not a code from an earlier run. ### My agent ran the installer and pairing stopped Many agents stop a shell command after a time limit. The pairing wait can be longer. Your wiring is in place. Run this in a terminal: ```bash theme={null} npx @alikeai/setup --doctor ``` ### Two machines keep disconnecting each other The machines have the same hostname. When one machine pairs, Alike cancels older credentials with the same hostname. Give each machine a unique hostname, then pair each one again. ### Pairing uses the wrong server Read the `Server:` line. If it does not show `https://alike.network/api-general`, check your environment: ```bash theme={null} echo $ALIKE_BASE_URL $ALIKE_TOKEN ``` Remove the variables with `unset ALIKE_BASE_URL ALIKE_TOKEN`, then run the installer again. If the machine already paired with the wrong server, the next run uses that server again. To pair with the production server, run: ```bash theme={null} npx @alikeai/setup --base-url=https://alike.network/api-general ``` ## Hooks ### Hooks never run The doctor prints `wired, but its hooks have NEVER fired`. **1. Restart the agent** Agents read hooks when they start. Close the agent fully and open it again. **2. Approve the hooks** Codex shows a **Hooks need review** prompt on the next run. Approve it. For Cline, check **Settings → Features → Hooks**. **3. Check that the agent can find Node** Hooks run `node`. Desktop apps that you open from the Dock or a launcher can miss the `PATH` of your terminal, for example when you install Node with `nvm`. Start the app from a terminal to test this. If the hooks then run, make `node` available to desktop apps, for example with a system-wide Node install. **4. Run a session and check again** Send one prompt in the agent. Then run `npx @alikeai/setup --doctor`. ### My agent says "Alike auth expired" The machine's credential stopped working. Run `npx @alikeai/setup --doctor` and approve the new code. ### Alike cannot be reached The installer prints `could not reach `, or the doctor prints `server unreachable`. * Check your internet connection. * Check that your firewall allows HTTPS to `alike.network`. * The installer does not support HTTP proxies. On a network that requires a proxy, pairing fails. Your agents keep working while Alike is unreachable. They get no context from Alike during that time. ### My agent continues after it finished When a teammate or another of your sessions asks you something, Alike can let the agent continue for one more turn to tell you. To turn this off, ask your agent: "Stop Alike from continuing a turn to tell me about questions." In Cursor, the extra turn appears as a new message in the chat. See [Tune what your agent gets](https://alike.help/use/tune-context.md). ### The brief says "Alike has nothing linked to this session yet" The branch does not link to a work item yet, and you have no recent sessions in this repository. This is normal on a new branch. Ask your agent: "Link this session to this branch in Alike." The agent then creates the work item, and later sessions on the branch get it. ### Alike's context is too noisy Ask your agent: "Apply the Alike `quiet` preset." To hide one item for good: "Tell Alike to stop showing me that item." See [Tune what your agent gets](https://alike.help/use/tune-context.md). ## MCP ### My agent asks me to sign in, but I paired the machine This is expected. Pairing covers the hooks only. Each agent's MCP connection needs its own sign-in, one time. ### Codex does not open a browser to sign in Run `codex mcp login alike`. ### My agent cannot find a tool, for example `create_reminder` Scheduling, planning, reminder, and meeting tools are hidden for builders at first. Ask your agent: "Call Alike's `get_more_tools`." If the agent still cannot use the tool, reconnect the MCP server. If the tools disappear later, ask again. ### Tools changed after I switched experience The tool list depends on your experience in **Settings → Experience**. After you switch, reconnect the MCP server in each agent. ### Rate limit exceeded The error is `Rate limit exceeded`, sometimes with `Retry after N seconds.` Wait, and try again. At an office or an event, many people share one network address and one limit. Hooks that hit a limit send nothing and do not slow your agent. ## Capture and dashboard ### The doctor finds 0 sessions for an agent The doctor prints `detected but 0 sessions found in `. Your version of the agent may keep its history in a different folder, or you have no history yet. Run one session and check again. If the problem stays, send the doctor output to [support@alike.work](mailto:support@alike.work). ### Sessions are not uploaded 1. Run `npx @alikeai/setup --doctor` and read the sweep section. 2. If you see `capture disabled (not selected at install)`, run the installer again and answer yes for that agent. Or run `npx @alikeai/setup --capture=`, for example `--capture=claude,codex`. 3. If no sweep ran, run `npx @alikeai/setup --sweep`. 4. If only Windsurf, Zed, or Continue is set up on the machine, set up an hourly capture. See [When capture runs](https://alike.help/use/sessions-and-capture.md#when-capture-runs). 5. Read `~/.alike/logs/sweep.log` for errors. ### "First real session" and "First injection" never light up These steps need a session after you restart your agents. Restart each agent, then send a prompt in a git project. ### Analytics shows no "Since Alike" line The line starts at your first live session. Your imported history fills the baseline first. This can take about an hour. ### The weekly email does not arrive The email is off by default. Turn it on in **Settings → Notifications → Email**. A machine must be paired. The email arrives on Friday evening in your time zone. ## Account ### I cannot sign in: "Account scheduled for deletion" Your account is in the 30-day deletion grace period. To cancel the deletion, email [privacy@alike.ai](mailto:privacy@alike.ai). ### I cannot remove a machine from my account The web app cannot remove machines yet. Run `npx @alikeai/setup --uninstall` on the machine. If you cannot reach the machine, contact [support@alike.work](mailto:support@alike.work). ## Machine clean-up ### The hourly capture still runs after uninstall On macOS, the uninstaller deletes the schedule file, but a loaded schedule stays active until you log out. Run: ```bash theme={null} launchctl remove works.alike.sweep ``` On Linux, delete the cron line with `crontab -e`. ### A settings file became readable by other users The installer writes settings files with the permissions `0644`. Set private permissions again, for example: ```bash theme={null} chmod 600 ~/.claude.json ``` ## Get help Send these to [support@alike.work](mailto:support@alike.work): * The output of `npx @alikeai/setup --doctor`. * Your operating system and the agent's version. * The last lines of `~/.alike/logs/sweep.log`, for capture problems. Do not send `~/.alike/credentials.json`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.