---
title: Phone grey or disconnected? Bring it back
nav: Phone is grey
summary: A grey phone or web page usually means the computer opened a new session, not that the relay broke; Agent J follows the new session by itself, Settings → Emergency repair fixes the rest from the phone, and one command checks and repairs the service, the relay and the Agent.
order: 27
---
# Phone grey or disconnected? Bring it back

When the phone or web page turns grey and says disconnected, the usual cause is neither the network nor the relay: **the computer started a new session**. A reboot, closing and reopening the terminal, `/clear`, or a Claude Code restart after an upgrade all give the desktop a new session ID. In shared mode Agent J follows one session; when that one is gone, the phone has nobody to talk to.

## From the phone first: Emergency repair

Stuck, offline, dropping, or no replies? You don't have to go back to the computer. Open Settings → **Emergency repair** (the second item) and go in order. On the offline card, the **Emergency repair** button opens the same place.

**① Reset connection.** Tap it first. It tries one step at a time and stops as soon as the link works again, showing each step on the card:

1. Reconnect.
2. Find your conversation again.
3. If needed, start a new conversation. Your earlier one is kept: ask the Agent in the chat to bring it back, or run `agentj rescue undo` on the computer.
4. Restart Agent J on the computer.

When the card turns green with "Fixed. You can go back to the chat.", you're done. ≡ All commands has the same "Reset connection", and typing `/reset` does it too.

**② Ask Agent J Father for remote help.** Use it when ① didn't help. The computer checks itself, removes private details on the computer, and sends that report to Agent J Father; the card shows a ticket number. Support can suggest a few fixed repairs (reconnect, restart, keep running without anyone logged in, go back to the previous version, start a new conversation); the computer runs only those, shows each one, and sends the result back. Nothing is sent until you tap, and the report never holds passwords, keys, your conversations or your files.

**③ AI account signed out.** This one is about the Claude / Codex account, not the connection: it opens AI login rescue.

**When Agent J on the computer is frozen.** `agentj service install` and every update also install a small rescue helper. If Agent J stops answering for about 45 seconds, the helper answers the phone instead: the page shows "Agent J on your computer isn't responding · rescue helper online", and ① and ② still work. Check it on the computer with `agentj rescue status`.

**Someone at the computer?** When the phone can't reach the computer at all, ask them to open a terminal, paste one line and press Enter:

```
curl -fsSL https://agentj.app/rescue | sh
```

On Windows, in PowerShell: `irm https://agentj.app/rescue.ps1 | iex`. It checks the computer, repairs only what is safe, and sends a privacy-filtered report to support. Details: [Emergency rescue](https://agentj.app/rescue/).

## Since 0.18.4: it reconnects by itself

When the followed session goes away, Agent J looks for the new one in the same working folder and attaches it — nothing to restart. The phone then shows "Back on track — attached to the new session …".

How it chooses:

- Only Claude Code sessions you opened yourself in the same working folder count; headless `claude -p` runs and background jobs never do.
- One such session: that one. Several: the one that just opened, or the only one started after the old session.
- Two or more equally likely: it does not guess. The phone lists their short IDs; in the session you want, say "connect my phone".

## Codex and OpenCode: no automatic follow (unless the old thread is gone)

"Reconnects by itself" above works for Claude Code only. With Codex or OpenCode as the main Agent, a new thread (session) you open on the computer is not followed: the phone stays with the old one. To move to the new thread, run `agentj config set agent.shared_session_id <new thread ID>` on the computer, then `agentj service restart`.

Two more things. When the Codex thread the phone followed no longer exists on the computer, the phone says "The shared session is gone" and follows the Codex thread used most recently in this folder (skipping one a terminal codex is holding); when that is unclear it shows a card so you pick one, or "Start a new conversation". And Claude Code, Codex and OpenCode each keep their own shared session: switch the main Agent and back, and each one is still on its own session — none borrows another's session ID. A value set with `agentj config set agent.shared_session_id` is used only by the Agent it belongs to.

## When it cannot: one command

Tell the Agent on the computer that your phone is grey, or ask it to connect your phone. It runs:

```
agentj doctor --reconnect
```

It checks three links in order, repairs only the broken one, and ends with one plain sentence:

| Link | Look at | Broken means | Repair |
|---|---|---|---|
| Service | does `agentj status` answer | `agentj serve` is not running | start or restart the service |
| Relay | is `relay_state` `up` | the computer cannot reach the Agent J relay (network or account) | wait, then restart the service once |
| Agent | is `agent_status` `down` | Agent J is not attached to a live session | attach again; run inside a session to attach that one |

If several sessions are open, name one: `agentj doctor --reconnect --session <ID>`.

`agentj status` also points to this command when the Agent is down.

## The new-session self-check

The main Agent's built-in instructions say: on the first turn of every new session (also after compaction, `/clear` or resume), run `agentj status --json`, and run the command above if anything is not up. A new session that Agent J does not serve yet is told the same through the hook Agent J installed in that folder. You never need to remember a command or know what to type.

## The relay stays "reconnecting"

Since 0.22.x every failed relay attempt says where it stuck, in the service log (`journalctl --user -u agentj`, or the window running `agentj serve`), in `agentj status --json` (`relay_last`, and `relay_stuck` in words) and in `agentj doctor`:

```
· relay connect failed #4: … (phase=auth why=auth_refused code=4003) · retry in 1.2 s
```

`phase` is where it stopped (`seat` reading the seat certificate, `connect` DNS / TCP / TLS / WebSocket, `auth` the relay checking this computer's signature); `code` is the relay's close code. `agentj doctor` also probes the computer's own signed connection (the "host leg"), not only a phone-side test socket, so a green phone-side check with a stuck host leg is no longer hidden.

| What it says | Usually means |
|---|---|
| `why=replaced code=4001` | two `agentj serve` use the same identity: keep exactly one (`pgrep -af 'agentj serve'`) |
| `why=seat code=4002` | no valid seat certificate: see the seat row of `agentj doctor` |
| `why=auth_refused code=4003` / `why=identity` | the computer's identity files disagree: send `agentj doctor --json` to support; do not delete the state folder |
| `why=limit` | too many connections from this public IP: wait a few minutes |
| `why=timeout phase=connect`, `why=dns`, `why=tls` | network, DNS, proxy or certificate trouble on this computer |

Quote that line when you ask for help.

## Still grey

Try Settings → Emergency repair ② on the phone. At the computer, run `agentj doctor` for the full check, then follow the [support](/docs/support/) page. Do not edit config files by hand, and never paste a key into the chat.