Troubleshooting
Common issues during early access, with concrete fixes.
The app won’t open
Section titled “The app won’t open”macOS Gatekeeper is blocking an unidentified developer. Right-click the Octopush app in Applications and choose Open, then confirm. If there’s no Open option, go to System Settings ▸ Privacy & Security, scroll down, and click Open Anyway next to the Octopush notice. You only need to do this once.
The model doesn’t respond
Section titled “The model doesn’t respond”No provider or API key is configured. Open Settings (⌘,) ▸ Integrations and add a key for Anthropic, OpenAI, or DeepSeek — or point Octopush at a local Ollama instance. Make sure at least one provider is active.
The terminal won’t start
Section titled “The terminal won’t start”Run mode depends on a PTY daemon. If a terminal session fails to open, close and reopen the workspace, or restart Octopush to relaunch the daemon. Existing sessions are meant to survive restarts, so you shouldn’t lose your work.
The diff is empty
Section titled “The diff is empty”Review shows changes against git. An empty diff means nothing has changed yet, or your changes are already committed. Make an edit (in Run, Review, or by an agent in Talk) and the diff will populate.
A Direct pipeline is paused
Section titled “A Direct pipeline is paused”Two common reasons:
- A checkpoint is awaiting approval. Direct pipelines can gate on checkpoints — review the stage and approve it to continue.
- A transient halt. If a stage stopped unexpectedly, use Resume to pick it back up.
[screenshot: Direct pipeline paused at a checkpoint with a Resume action]
I hit the context limit
Section titled “I hit the context limit”A conversation reached the model’s context window. Start a new conversation in Talk to reset context. For long-running work, consider breaking the task into a fresh workspace.
How do I update Octopush?
Section titled “How do I update Octopush?”Download the latest .dmg from the releases page and replace the app in Applications. Your projects, workspaces, and settings persist across updates.
How do I report a bug?
Section titled “How do I report a bug?”Open an issue on GitHub. Include your Octopush version (v0.2.12), your Mac’s chip (Apple Silicon or Intel), and steps to reproduce.
How do I reset my configuration?
Section titled “How do I reset my configuration?”If settings get into a bad state, open Settings (⌘,) and reconfigure your providers and budgets. Re-adding a provider key under Integrations resolves most authentication problems.