CC Babysitter Docs
Menu
On this page

Troubleshooting

Troubleshooting

What each warning on a card or the page means, and each Activity line about trouble or an automatic action. Each entry says what to do.

Search the docs for a message's first words to find its entry. A quote that ends in ... is the start of a longer message, which goes on with a session, a folder or a reason.

Won't come back if its app closes

CC Babysitter brings a session back in the background with the claude CLI, which runs on its own only in a folder it trusts. Inside a git repository the CLI takes that trust only from the repository's own folder. Claude Desktop also accepts a trusted folder above it, so a session that works in Desktop can still be refused in the background. A git worktree takes the trust from any folder above it. The CLI never starts a background session in your home folder.

For the trust, run the command the card shows in a terminal and answer Yes before you exit, and the warning goes away within seconds. For the home folder, start the session in a project folder instead.

Remote Control is off

Remote Control is what lets you reach the session from your phone or the browser. Nothing outside a session can switch it on, so the card says how to do it in the session's own app.

A session CC Babysitter brings back in the background usually has Remote Control on, and its Activity line says so. When the line says it is not connected yet, wait: the card shows when it is. When the line says it is off, attach to the session with the command it gives and type /rc.

Not responding

A session counts as frozen after 20 minutes of waiting on the model with the same output, the same processes and the same CPU time. It happens when its connection drops in the middle of a turn, and Remote Control goes offline with it. A session running a tool, waiting out a usage limit or a retry, or waiting on a question never counts.

A frozen background session is stopped with claude stop and started again, which keeps the conversation; the turn that froze is lost. A frozen session in a terminal or an app is only marked, since it belongs to that app. Press Escape in it to stop the turn and carry on there. Or close it, and CC Babysitter brings it back in the background if it is babysat. When claude stop could not stop a copy, Activity says how to stop it by hand.

Stuck

CC Babysitter stops trying when starting a session failed three times in five minutes, or its background copy froze three times in two hours. That way it never retries in a loop. Activity has the reason for the last failure.

Fix what the reason names, then press Try again on the card, or run ccbabysitter retry with the session. For a session stuck after freezing, Try again stops the copy only if it is still the same copy and still frozen. Then the session is started again. A copy that came back to life is only watched. Stop watching ends the babysitting instead.

A session brought back in the background

When a babysat session's app goes away, CC Babysitter starts the same session again in the background, under the same id. When that can be told, the Activity line says why the session went down. For example, Claude Desktop closed or updated, the computer restarted, or Claude Code ended it after it sat idle. When nothing tells, the line says only that its process exited.

Nothing needs doing. Reach the session from your phone. To go back to its app, use the card's Back to Desktop, Back to VS Code or End background copy. Some lines give one of these reasons but do not say the session was resumed. Those mean it could not be brought back: see the next entry.

A session could not be brought back

Starting the session again in the background failed. The line says why. Where it can, it ends with "Run by hand:" and the command to start the session yourself. For the usual reasons, see the entries on a folder that is not trusted, logging in and the CLI.

Claude Code sometimes starts a resume as a new copy of the session instead. CC Babysitter stops and removes that copy with claude stop and claude rm, and tries once more without flags. When it cannot, the line gives the commands to run by hand. After three failures in five minutes the session is stuck.

Claude Desktop says the session is running in the background

Only one copy of a session runs at a time. While CC Babysitter's background copy carries it, Claude Desktop shows this when you open the session, and may show "Claude Code crashed" for it.

Press Back to Desktop on the session's card, or run ccbabysitter stop with the session and --yes. Then open the session from Claude Desktop's sidebar. If Desktop shows "Claude Code crashed", press Try again there, and the session carries on.

The phone shows another name for the session

After a session goes back to Claude Desktop, the Claude app on your phone may show Claude Code's automatic title for it. That replaces the name you gave it. It is the same session; only the name shown changes, and that name comes from Claude Code.

The session is running in an app again

CC Babysitter was about to bring a session back and found it already running, in an app or as a background copy. It never starts a second copy of a session, so it went back to watching it where it runs.

"Session open in" is the other way round. The background copy is gone, and the session is open in an app again, after Back to Desktop or because the app restored it. It is babysat there. Nothing needs doing in either case.

More than one background copy

Two background copies of one session were running, which should not happen. CC Babysitter keeps the copy it knows and stops and removes the others with claude stop and claude rm. It leaves a copy alone when its short id cannot be put in a command safely. That happens, for example, when an app session of the same conversation has the same short id. Then, and when a clean-up failed, check claude agents and remove the copy by hand.

Babysat on its own on a server

On a machine with no display, a new background session is babysat as soon as it starts, so it survives SSH drops and reboots. Switch Babysit every new background session off in Settings, or run ccbabysitter settings auto-babysit off, to choose each time instead.

Nothing to bring back

Claude Code saves a conversation only after its first message, so a session that ended before anything was said has nothing to start again from. Its babysitting ends, and Activity says so. To babysit it, say something in it first, then press Babysit.

The last three lines are about a session shown as stuck for this reason, which ended before anything was said. Once a conversation is there for it, or it runs again, it is babysat again on its own.

Claude Code is not logged in

A Claude Code CLI that is not logged in reaches neither the model nor Remote Control, so a session started now could do nothing. The page shows this note, and New session and ccbabysitter start start nothing. Run claude once on this machine and log in, then try again.

The Claude Code CLI cannot be used

CC Babysitter brings sessions back with the claude CLI. Install Claude Code, or make sure claude runs in a terminal of the same account.

Before it brings a session back, CC Babysitter asks claude agents whether the session is running, so it never starts a second copy. An answer it cannot use counts as none: it starts nothing, and asks again on its next look.

The page needs its key

The page only answers requests that carry its key. The key stays the same across restarts. A page that ccbabysitter opened for you is different: it works only until CC Babysitter restarts, for example after an update. Run ccbabysitter to open the page again. The address ccbabysitter status prints carries the key and keeps working after restarts.

A refused request means the page was not opened from that address. Too many pages means close a tab. When no browser could be opened, open the address the terminal shows, or the one ccbabysitter status prints: the Activity line has it without the key. When the key or the address could not be saved, check that CC Babysitter's state folder can be written.

The page lost CC Babysitter

CC Babysitter quit, or stopped, while the page was open. Babysat sessions keep running, but nothing brings them back until it runs again. Run ccbabysitter, and the page reconnects. If start at login is on, it also starts again the next time you log in.

Saved state could not be read or saved

CC Babysitter keeps the babysat sessions and its settings in its state folder: ~/.local/share/ccbabysitter on macOS and Linux, %LOCALAPPDATA%\CCBabysitter on Windows. A state file it cannot make sense of, or one written by a version it cannot use, is moved to state.json.bad. CC Babysitter then starts from the defaults, and the sessions that were babysat need Babysit again.

"Could not read" means the file stayed where it is, but CC Babysitter could not open it, usually for its permissions. The next save writes the defaults over it, so fix the folder's permissions and run ccbabysitter again before changing anything. A save that failed is tried again on the next change: check that the disk has room and the folder can be written.

The computer may sleep

CC Babysitter asks the system to stay awake while a session is babysat. The system said no. Babysat sessions are still brought back when their app closes. But the computer may sleep, and nobody can reach a sleeping computer. CC Babysitter asks again each time it looks, and Activity says it is keeping the computer awake once the system agrees.

Sessions are noticed more slowly

CC Babysitter watches Claude Code's session folder to notice a session the moment it starts or ends. Without the watch it still looks every few seconds, so everything works, only a little later. Nothing needs doing.

The page stopped updating

These mean CC Babysitter itself went wrong, not your sessions. When the page stopped updating, run ccbabysitter quit, then ccbabysitter. When the web server stopped, run ccbabysitter. If it happens again, report it with the Activity line on the issue tracker (opens in a new tab).

Edit this page on GitHub (opens in a new tab)