← Back to Home

Support

Before reaching out, run the built-in self-diagnostic below. Then work through the checklist for anything it flags.

Run this first

Open Settings → Self-Diagnostics tab in the app. It checks all prerequisites automatically and gives you a plain-English diagnosis. Start here before working through the checklist below.

1. Prerequisites Status▾

InsomniDev checks four prerequisites on launch. If any show a red ✗ in the app, that's likely your issue.

  • —GitHub CLI. Install with: brew install gh
  • —GitHub authentication. Check with: gh auth status
  • —Claude Code CLI. Install with: npm install -g @anthropic-ai/claude-code
  • —Claude Code authentication. Verify with: claude auth status
  • —Git identity (name) must be set. Check with: git config user.name
  • —Git identity (email) must be set. Check with: git config user.email
  • —Xcode Command Line Tools (required for git and python3). Install with: xcode-select --install
2. Configuration▾

Open Settings in the app and verify your configuration. Common mistakes:

  • —Repo must be in owner/repo format (e.g. acme/my-project).
  • —time_window_start must be set to a time before time_window_end
  • —workroot path must exist on disk and have enough free space for the bot to clone your repo.
  • —All labels must exist on your GitHub repo.
  • —The base branch configured in Settings must exist in your GitHub repo.
3. Schedule & launchd Status▾
  • —Check that the launchd plist is installed: ls ~/Library/LaunchAgents/com.insomnidev.nightly.plist
  • —Check that the job is loaded: launchctl list com.insomnidev.nightly
  • —If the job is missing, try toggling the schedule off and back on in Settings.
4. Last Run Status▾
  • —The app shows the result of the last run in the menu bar popover (success/failure, timestamp, summary message).
  • —For the raw state file: cat ~/Library/Application\ Support/InsomniDev/state/last_run.json
5. Recent Log Output▾

The run log is the highest-signal artifact. It shows exactly what the bot did and where it failed.

  • —View in the app: Settings → Logs tab.
  • —View in Terminal: tail -n 100 ~/Library/Application\ Support/InsomniDev/logs/run.log
6. CLI Versions▾

Version mismatches between claude and gh are a common source of breakage.

  • —claude --version
  • —gh --version
  • —Update claude with: npm update -g @anthropic-ai/claude-code
  • —Update gh with: brew upgrade gh
7. GitHub Repo Accessibility▾
  • —InsomniDev requires WRITE or ADMIN access — READ is not enough. Verify your access level: gh repo view <owner/repo>
  • —Confirm the expected labels exist on the repo: gh label list --repo <owner/repo>
8. Mac Must Be Plugged In▾

InsomniDev schedules your Mac to wake automatically before each automation window, but macOS only honors scheduled wake events when the Mac is plugged in. Leaving it asleep on the charger overnight is the ideal setup (the lid can still be closed).

  • —Awake and plugged in always works.
  • —Asleep and plugged in (lid open or closed) works; macOS wakes it on schedule.
  • —Awake on battery works only if the Mac stays awake.
  • —Asleep on battery will not work; macOS won't honor wake schedules without power.
  • —Shut down completely will not work; wake-on-schedule does not reliably power on from a full shutdown.

Still stuck?

If you've worked through the checklist above and are still having trouble, send an email with the details from each section and I'll take a look.

support@insomnidev.com