Troubleshooting
The short list of things that go wrong, what to do, and where to reach us.
"My agent isn't detected"
Settings → Terminal shows the runtime health table. If a CLI you just installed isn't there — or shows Not installed — hit Re-probe runtimes. Rows can also show Sign-in needed, Rate limited, or Usage limited when the runtime itself needs attention: fix those in the runtime's own CLI (run it in a tab and follow its prompts).
"push command not found"
The CLI installs to ~/.local/bin/push. If your shell can't see it,
Settings → Workspace → Push CLI and skill shows the exact copy-paste PATH
fix for your setup.
"A session didn't come back"
Resume is designed to survive quits, updates, and reboots. If a tab ever comes back detached, right-click it → Copy Session Information… and include that in a bug report — it's the session's identifiers, and it's what lets us reconstruct what happened.
Updates
Push checks a signed feed automatically. Most updates install quietly and show an update chip in the tab strip; Push → Check for Updates… fetches on demand; only critical fixes interrupt you with a dialog. If an update seems stuck, quit and reopen — staged updates apply on relaunch, and your sessions resume after.
"My phone can't reach my Mac"
In order of likelihood:
- The Mac is asleep. That's a state, not an error — captures queue and sync when it wakes. To keep it reachable, enable Always On.
- The Push server needs a nudge. From the phone: Settings → Workspace → Restart Push app — or on the Mac, the Server menu → Restart Server.
- The pairing is stale. Check Settings → Workspace → Devices on the Mac; revoke the old entry and pair again.
"I hit the recording limit"
The monthly allowance reset date and your usage are in Settings → Transcription & Data on the phone. Typed capture keeps working meanwhile, and terminal voice input isn't counted. Current allowance details: pricing.
"Meeting recordings aren't transcribed"
Meeting transcription (Beta) runs on your own OpenRouter key — Settings → Meeting → Transcription. No key means recordings are saved but not transcribed; add a key and future recordings transcribe.
Logs
Server → Open Logs on the Mac. Logs live locally under ~/.push/ with
everything else.
Reaching us
- Bugs and feature requests — the public tracker: github.com/MasslessAI/push. Include your version (Mac: Push → About Push; iPhone: Settings → About) and the platform.
- Security issues — privately, please: see SECURITY.md in the tracker. Don't file security reports as public issues.
- What changed recently — the changelog.