Skip to main content
Start with the doctor. It finds most problems:
Then find your problem below. For a message that you see, search Error messages.

​
Install

​
No agents found

The installer prints No supported coding agents found (scanned <n>). 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.

​
The installer refuses a settings file

The installer prints Refusing to touch <file>: 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.

​
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:

​
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:
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:

​
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 <url>, 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.

​
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.

​
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 <folder>. 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.

​
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=<every agent to 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.
  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.

​
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.

​
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:
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:

​
Get help

Send these to 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.