Skip to main content
This guide takes you from downloading Xirp to a running Coding Agent session.

Prerequisites

Before you begin, you need:
  • A Mac
  • At least one supported Coding Agent account: Claude Code, Codex, Gemini CLI, Pi, or Cursor
  • An internet connection for initial setup
You do not need a separate Xirp account. A Portal instance is optional. You can run general sessions and work with local projects without connecting Portal. A local Git repository is required only for Git and worktree features. Xirp checks your Mac when it starts and provides guidance when required software, such as tmux or the GitHub CLI (gh), is missing.

1. Install Xirp

  1. Open xirp.spotify.com and select Join the beta.
  2. On the Get Xirp page, select Download for Mac.
  3. Open the downloaded installer and move Xirp to Applications when prompted.
  4. Start Xirp.
macOS may ask you to confirm that you want to open an app downloaded from the internet. Review the prompt and select Open.

2. Accept the preview terms

On first launch, review the linked Xirp Preview Terms, select the acceptance checkbox, and select Continue. You can also review the Backstage Privacy Policy. On Stay in the loop, you can choose to receive product updates by entering your email and selecting the marketing checkbox. To skip this, select No thanks. You do not need to enter an email to continue.

3. Complete first-run setup

If you have no projects, Xirp opens Projects and offers to import existing projects. Importing at least one project completes setup. If you skip the import, a guided tour helps you choose a project and start a task. You can also finish setup without starting a task. You can replay the tour later from Settings > Application > Welcome tour. Coding agent selection, session hooks, and layout preferences are also available in Settings.

4. Add a project

A project points Xirp to a folder on your Mac. Open the Projects tab in the sessions panel, then either:
  • Add a single project to register one repository or folder.
  • Import a workspace to scan a parent folder and add several repositories.
The empty Projects page See Projects for project shapes, Git worktrees, files, skills, and rules.

5. Start a session

  1. Open the project.
  2. Select New session or use the goal box on the project overview.
  3. Describe a specific outcome.
  4. Choose a coding agent and whether to use the main checkout or a new worktree.
  5. Select Start.
Starting a session with a goal The agent starts in a persistent terminal. You can leave the page, open another session, or close and reopen Xirp without ending the underlying session.
Agent models, credentials, reasoning settings, permissions, and sandbox behavior remain owned by each agent’s native configuration.

6. Optional: Connect to Portal

Spotify Portal adds shared Workspace context and session sharing to Xirp. Follow Connect Xirp to Portal to connect your team’s instance. If your team doesn’t have Portal yet, request a Portal trial.

Troubleshooting

Xirp reports missing tools

Open Settings > Doctor to see which checks failed and follow the offered fix for each. You can also install missing tools such as tmux and gh manually, then quit and reopen the app. Use each tool’s official installer and public documentation when available.

A Coding Agent is unavailable or does not start

Open Settings > Coding Agents and check whether the Coding Agent is available. Install it if needed, confirm that you can sign in through its native CLI, and restart Xirp. Use the Coding Agent’s official installer and documentation. You can also run Settings > Doctor for a diagnostic check.

Worktree options are missing

Worktrees require a project containing one Git repository. GitHub pull request status and other Git features may also be unavailable in non-Git projects.

Session statuses or notifications are not updating

Open Settings > Notifications and confirm that session hooks are enabled. The notification center (bell icon in the header) shows recent notifications and lets you dismiss or snooze them.

Portal upload is missing or fails

Confirm that Xirp is connected to Portal and that you have access to the target Workspace, then try the upload again.

Next steps