Sundial Try the demo
# Troubleshooting When something does not work, find the symptom below. Each entry gives the likely cause and the fix. Run every command from the repository folder. ## First, look Two commands tell you most of what is wrong: ```bash node bin/sundial doctor ``` ```bash node bin/sundial status ``` `doctor` checks the prerequisites (macOS, Node.js 22 or newer, pnpm, the Xcode Command Line Tools, sqlite3). `status` shows: - `home`: the data folder, and when it was installed. - `app`: whether `Sundial.app` is running (`agent` for a `--no-app` install: whether the LaunchAgent `dev.sundial.agent` is loaded). - `web`: the HTTP status of <http://127.0.0.1:3080>. **401 is normal here**: Sundial is up, and the check itself is not signed in. "no answer" means the web process is not running. - `database`: how many observations there are, and when the last one came in. - `launcher` and one line per sensor file: `ok`, `STALE` (the helper stopped writing), `MISSING` (it never wrote), or `absent` for sensors that are off or write only when something happens. ## Where the logs are - `~/.sundial/logs/sundial.log`: the web process. - `~/.sundial/logs/sidecars.log`: starting and stopping the Swift helpers. ```bash tail -n 50 ~/.sundial/logs/sundial.log ``` `sundial.log` also holds the sign-in link. Remove any line with `token=` before you share the log with anyone. ## The page says 401 **Cause:** this browser has no session cookie. That happens in a new browser, or after you clear its cookies. **Fix:** sign in again. It opens the sign-in link in your default browser. ```bash node bin/sundial open ``` If `open` says there is no sign-in URL yet, Sundial is not running. Check `status` and `sundial.log`. ## Nothing answers on port 3080, or port 3080 is in use **Cause:** another program listens on 3080, so Sundial's web process cannot start. See who holds it: ```bash lsof -nP -iTCP:3080 -sTCP:LISTEN ``` **Fix:** stop that program, then restart Sundial. Or install Sundial on another port. The install remembers it, so later commands such as `open` and `status` find it without the variable: ```bash SUNDIAL_WEB_PORT=3090 node bin/sundial install ``` ## A permission says "Not granted" after you granted it Work down this list and check `/setup` after each step. 1. **Restart.** macOS applies a new grant only to a freshly started helper. ```bash node bin/sundial restart ``` 2. **Remove and re-add the entry.** In System Settings → Privacy & Security, select Sundial, click **−**, then add `/Applications/Sundial.app` again with **+** and **⌘⇧G**, and restart. This is the usual fix after a rebuild: the helpers are signed on your Mac, so a rebuilt helper is a new program to macOS and the old entry no longer applies. 3. **Reset and grant again.** Clear the service, restart, and grant it fresh. ```bash tccutil reset Accessibility dev.sundial.daemon ``` For Screen Recording, Calendars, Contacts, Microphone and Automation, the helper asks for itself; a hand-added entry does not count. Reset the service and accept the prompt when it appears. "Waiting for the sensor" means the helper has not written its file yet; check the sensor lines in `status`. Details for every permission: [permissions.md](/sundial/docs/permissions/). ## App names show, but window titles are missing **Cause:** the window helper reads the app in front without any permission, but it needs Accessibility for the window title. **Fix:** grant Accessibility to Sundial and restart. If it already shows as granted, remove the entry and add it again (step 2 above). ## Nothing from the Mac is recorded at all **Cause:** the Swift helpers are not running. `status` shows `launcher: not running`, or every sensor line says `MISSING`. An install with `--no-sidecars` never starts them. **Fix:** restart, then read `sidecars.log`. ```bash node bin/sundial restart ``` Do not start `Sundial.app` with `open -a` or from Finder; see [permissions.md](/sundial/docs/permissions/#never-start-sundialapp-with-open--a). ## Gnomon does not answer in the chat **Cause:** no model is set yet. Sundial still records, and Today still shows your day, but the chat and the written summaries need a model. **Fix:** open <http://127.0.0.1:3080/setup>, choose a model under "A model for Gnomon", and press **Restart Sundial**. See [models.md](/sundial/docs/models/). ## Install fails The installer stops at the step that failed and prints the command that failed. - **Step 1:** fix each line marked `!!`, then run `install` again. - **Step 2, "exists, is not empty, and was not made by this installer":** `~/.sundial` holds files from something else. Move that folder away, or install into another one with `SUNDIAL_HOME`. - **Step 3:** `pnpm install` or the TypeScript build failed. The error is just above the `failed (exit …)` line. - **Step 4, the Swift build:** usually the Command Line Tools are missing or out of date. Run `xcode-select --install`, or update them in System Settings → General → Software Update. - **Step 4, `codesign`:** the build stops when a signature fails, on purpose: a helper that is not properly signed cannot hold a permission. Read the message `codesign` printed just above, fix that, and run `install` again. - **Step 7, "the web client did not answer":** read `sundial.log`. On a slow first start, give it more time: ```bash node bin/sundial install --timeout 300 ``` ## Restart or reinstall? - **Restart** after you grant a permission, edit `config.json` or `.env`, or change a model. It restarts the web process and the helpers, and rebuilds nothing. ```bash node bin/sundial restart ``` - **Install again** after you pull new code, or when files in `~/.sundial` are broken. It rebuilds and rewrites the start script and LaunchAgent, and keeps your database, `config.json` and `.env`. If a Swift helper changed, macOS asks for its permissions again. ```bash node bin/sundial install ``` ## Uninstall cleanly First see what would be removed: ```bash node bin/sundial uninstall ``` Then remove it: ```bash node bin/sundial uninstall --yes ``` This stops Sundial, removes the LaunchAgent and deletes `~/.sundial`: the database, config, `.env`, logs and the app bundles. It removes a folder only if it holds the installer's marker for that folder. The repository folder is not touched. Three things stay, and you remove them yourself: - The permission grants. Clear them with: ```bash tccutil reset All dev.sundial.daemon ``` ```bash tccutil reset AppleEvents dev.sundial.browser-helper ``` - The shell hook line in `~/.zshrc` or `~/.bashrc`, if you added it. - The Claude Code MCP entry, if you added it: ```bash claude mcp remove --scope user sundial ```