Skip to content
Zep

Troubleshooting

“Apple cannot check it for malicious software”

You downloaded Zep directly (not via Homebrew) and macOS blocked the launch.

Fix: right-click Zep.app in Applications and choose Open. Confirm in the dialog. macOS remembers your choice after the first launch.

If you’d rather use the command line:

Terminal window
xattr -d com.apple.quarantine /Applications/Zep.app

Homebrew installs don’t hit this — brew strips the quarantine attribute automatically.

  • Full-screen apps hide the menu bar. Exit full-screen and the icon will come back.
  • Too many menu bar icons. macOS hides icons that don’t fit. Install Bartender or remove other icons.
  • Launched with --no-tray. Relaunch without the flag.

”Zep is already running”

You launched Zep while another copy was already running. Zep is single-writer per data directory.

  • Click the lightning-bolt icon in your menu bar to open the existing instance’s UI.
  • If you don’t see the icon, the other Zep is running without tray support. Quit it from Activity Monitor (search “zep”) and relaunch.

Port conflict: “address already in use”

Something else is bound to 127.0.0.1:8550. Two options:

  1. Run Zep on a different port: zep --port 8552
  2. Find what’s using 8550: lsof -i :8550 and stop it.

Slack OAuth loops or fails

  • Check that your browser didn’t block a popup or third-party cookie during the OAuth dance.
  • Disconnect and reconnect from Settings → Integrations → Slack.
  • If the workspace requires admin approval, ask your workspace admin to approve the Anthropic MCP Slack app.

GitLab connection works but MRs don’t load

  • The OAuth scope needs api read access. Reconnect if you granted a narrower scope.
  • Self-hosted GitLab: confirm the base URL does not include a trailing slash.

”Claude CLI not found”

Zep shells out to the claude command. Install it from claude.ai/download and run claude auth.

GUI-launched apps on macOS don’t inherit your shell’s PATH. If claude is installed via brew or a custom location, Zep might not find it. Two fixes:

  • Relaunch Zep from the Terminal: open /Applications/Zep.app
  • Symlink claude into /usr/local/bin/: sudo ln -s $(which claude) /usr/local/bin/claude

Still stuck

Open an issue at github.com/example/z. Include:

  • macOS version (sw_vers)
  • Zep version (zep --version)
  • Install method (Homebrew or direct download)
  • Log output from ~/.zep/zep.log