Local agent
A job says "agent offline" and just sits there. That's by design — the job is waiting for your agent, visibly, and will run the moment it comes back. Check the Agent tab (or Settings → Tokens & Agents) for presence: an agent counts as Online if it checked in within the last ~2 minutes. If your Mac is awake but the agent shows offline:
launchctl kickstart -k gui/$(id -u)/dev.davidchang.nexus-agent
tail -50 ~/Library/Logs/nexus-agent.log
The log shows repeated 401s / "re-pair" errors.
The agent's token was revoked or has gone stale. Generate a fresh pairing code in Settings → Tokens & Agents → Pair a Nexus Agent and re-run the installer with it: curl -fsSL https://nexus.davidchang.dev/install.sh | bash -s -- --pair NX-<code>. The service self-heals the moment a fresh token is stored.
The agent dies right after starting under the service. Almost always a Node-resolution problem — launchd/systemd don't have your shell environment, so version-manager shims (asdf, nvm) fail. Re-running the installer fixes it: it resolves an absolute, shim-free Node at install time (and fetches a pinned Node if your system one is missing or too old).
Hosted runs happen even though my Mac is on. Local wins only when the agent is online (checked in within ~2 minutes). Sleep, a dead daemon, or a revoked token all route hosted-capable work to the cloud runner if you have an Anthropic key saved.
I paired a second account but the agent shows the wrong space / my other account's data.
Before agent profiles (2026-07-20), one machine could only hold one agent identity — a second --pair just re-registered the same background service over the first, so it looked like it paired but was actually still running the original account. Install the second account into its own profile instead, so both run side by side:
curl -fsSL https://nexus.davidchang.dev/install.sh | bash -s -- --pair NX-<code> --profile work
Then confirm each install landed on the account you meant:
~/.nexus-agent/bin/nexus-agent profiles
This lists every profile on the machine with its space, gateway, and service state — if one shows the wrong space, re-pair it with the right code and --profile name. See Install the Nexus Agent for the full walkthrough.
"profile … is already paired — the pairing code was NOT used"
You asked to pair a second account into a profile that already has one. Install it under its own
profile instead (--profile work), or pass --repair if you really meant to replace the account
that profile is paired to. Before this check existed, the code was silently ignored and the
installer reported success against the existing account.
Connectors
A connection shows "needs reconnect." Its token expired or was revoked provider-side. Hit Connect again on that row — same flow as the first time. Note that reconnecting creates a fresh connection; if an approval was pending against the old one, reject it and let the next run re-propose.
Slack sends fail with missing_scope.
Workspaces connected before message-sending was added lack the chat:write scope. Reconnect the workspace; every actual send still goes through your approval.
Wrong account keeps getting connected (Asana especially). Asana has no account chooser — it connects whoever is signed in. Use Copy connect link on the row and open the link in a browser profile where the right account is signed in. The link is single-purpose and expires in 10 minutes.
A brief only covers the last week. That's the Free plan's 7-day per-connector lookback, enforced server-side. See Billing.
Skills and schedules
My custom schedule text isn't accepted.
The plain-English parser is deliberately conservative: if it isn't sure, it shows a hint instead of guessing. Try one of the working shapes — every weekday at 9:30am, mondays at 7pm, every 2 hours — or enter raw cron (30 9 * * 1-5), which always passes through.
A scheduled run didn't fire overnight. If your agent was the target and your Mac was asleep, the job waited — it runs at wake (or fell back to the hosted runner after ~10 minutes if you have a valid Anthropic key). Check the schedule's missed-run policy in Settings → Schedules and the run ledger on the Agent tab.
A hosted run failed. Failed hosted runs are kept, marked, and replayable — nothing is silently dropped. The Agent tab's recent-runs ledger shows the failure and a replay control.
Anthropic key (hosted runner)
Settings shows my key "needs attention." Anthropic rejected the key mid-run (revoked, expired, or out of credit). Hosted runs stop routing until you save a fresh key — saving re-validates it immediately. Local-agent work is unaffected.
Notifications
No pushes on iPhone. Push requires the Home Screen install (open from the icon, not Safari), and deleting + re-installing the app silently resets its permission — re-flip Notify this device in Settings → Preferences after any reinstall. Also check Focus modes.
"This browser doesn't support push notifications." On iOS that means you're in Safari rather than the installed app. On desktop, check that notifications aren't blocked for the site in browser settings.
The app
White screen or crash page. Nexus ships a rescue screen with a single button that clears caches, unregisters the service worker, and reloads — use it; it fixes stale-installation wedges. If you somehow can't reach it, clearing site data in browser settings does the same.
I can't pinch-zoom on my phone. Intentional — Nexus is fixed-scale on mobile for a native-app feel. OS-level accessibility zoom still works.
Something else? Every run leaves a trail: the Agent tab's run log, the approvals History lens, and the audit log. If those don't explain it, get in touch — see below.
Getting help
Report it from inside the app. This is the fastest route by a distance, and the one to reach for first. Use the feedback button in the left rail (or Feedback in your account menu; the crash screen has one too). Pick bug, friction, or idea, and say what you expected.
It matters that you report it from the screen where it happened, because the report carries the context we'd otherwise have to ask you for: which page you were on, your app version, your last few runs and any error codes they produced, and recent failed requests. A screenshot of that screen is attached too — you can see exactly what's included before sending, and switch the screenshot off if the screen holds something you'd rather not share.
You can follow what happened to anything you've sent under Settings → Feedback.
Email. For anything that isn't a bug — billing, privacy requests, account deletion, or a question you'd rather ask a person — write to support@davidchang.dev. If you're reporting a broken run this way, include its timestamp from the Agent tab; without it we're guessing.
Technical users: the repo takes issues with bug-report and feature-request templates, which is the better route if you can describe a reproduction.