also looking at this
docs: the documentation the README points at
#63
9 files
+509
-10
| @@ -0,0 +1,71 @@ | ||
| 1 | # Troubleshooting | |
| 2 | ||
| 3 | ## It is not answering | |
| 4 | ||
| 5 | Work down this list. The first two cover almost everything. | |
| 6 | ||
| 7 | ### 1. Read the log | |
| 8 | ||
| 9 | ```bash | |
| 10 | tail -n 100 ~/Library/Logs/Uplink.log | |
| 11 | ``` | |
| 12 | ||
| 13 | This is the whole support story for the downloaded app: there is no crash reporting and no | |
| 14 | diagnostics bundle. It records every poll failure, every refused reply and every crash, with a | |
| 15 | stack. It rotates at 5 MB, so check `~/Library/Logs/Uplink.log.1` too if the tail looks truncated. | |
| 16 | ||
| 17 | ### 2. Check the menubar | |
| 18 | ||
| 19 | The popover lists what setup still needs, and each line says what is wrong rather than only that | |
| 20 | something is. The common ones: | |
| 21 | ||
| 22 | - **Read Messages** is waiting for Full Disk Access. See [Permissions](./permissions.md). | |
| 23 | - **Sign in** means the agent CLI is installed but not signed in. | |
| 24 | - **Install** means the CLI is not there at all, and the line gives the command. | |
| 25 | - **Send replies** means macOS has not been asked, or was refused, for permission to control | |
| 26 | Messages. This one fails after a run completes, so a task can look done and the phone hear | |
| 27 | nothing. | |
| 28 | ||
| 29 | From a clone, `./buddy uplink:doctor` checks the same things and says how to fix each one. That | |
| 30 | command needs the repository, so it is not available if you downloaded the app. | |
| 31 | ||
| 32 | ### 3. Check the obvious ones | |
| 33 | ||
| 34 | - **Is it paused?** The menubar has a pause switch. | |
| 35 | - **Is the licence current?** An expired one stops it answering. The menubar says so. | |
| 36 | - **Is the Mac awake?** A laptop with its lid closed sleeps unless it is on power with a display | |
| 37 | attached. Texts that arrive while it sleeps are not run, and you get one reply saying so. | |
| 38 | - **Are you texting from an allowed handle?** By default that is this Mac's own Messages handles. | |
| 39 | - **Are you texting over iMessage?** SMS is refused by design. A green bubble never reaches it. | |
| 40 | ||
| 41 | ## It answered once and then stopped | |
| 42 | ||
| 43 | Look for a run that is still going. `status` texts back what it is working on. `stop` cancels it | |
| 44 | and anything queued behind it. | |
| 45 | ||
| 46 | One thread runs one task at a time, so a long task blocks the ones behind it. That is deliberate: | |
| 47 | two runs resuming one agent session would each write their own history. | |
| 48 | ||
| 49 | ## A text got "that arrived while this Mac was asleep" | |
| 50 | ||
| 51 | It did, and it was not run. The cutoff exists so a Mac waking up does not replay a day of | |
| 52 | instructions that could do real work nobody wants now. Send it again to run it now. | |
| 53 | ||
| 54 | ## Texting myself does not reach the Mac | |
| 55 | ||
| 56 | A text to your own number can be delivered to your other devices without going through the | |
| 57 | satellite link at all. Test it once in satellite mode before relying on it. | |
| 58 | ||
| 59 | If it does not arrive, sign Messages on the Mac into a second Apple ID and set the allow list to | |
| 60 | your own phone number instead. | |
| 61 | ||
| 62 | ## It says it cannot resume the conversation after switching agents | |
| 63 | ||
| 64 | That is expected. A session id belongs to the agent that made it, and the other one cannot resume | |
| 65 | it, so texting `claude` or `codex` starts a fresh conversation. The working directory stays. | |
| 66 | ||
| 67 | ## Nothing here helped | |
| 68 | ||
| 69 | Open an issue with the last hundred lines of the log: | |
| 70 | <https://github.com/stacksjs/uplink/issues>. Take out anything in a prompt you would rather not | |
| 71 | share; the log records what you texted. | |