1. Getting started
1.1 What is Xirp?
Xirp is a macOS desktop app for running AI coding agents across multiple projects and sessions. It gives you persistent terminals, Git worktree isolation, and an optional connection to Spotify Portal for organizational context. Reference: Xirp overview1.2 What platforms does Xirp run on?
macOS only during the beta. Reference: Getting started — Prerequisites1.3 Which coding agents are supported?
Claude Code, Codex, Gemini CLI, Pi, and Cursor. Xirp auto-detects installed CLIs during setup. Models, credentials, and permissions stay in each agent’s own native configuration — Xirp does not translate settings between agents. Reference: Settings — Coding agents1.4 Do I need Spotify Portal to use Xirp?
No. All core features — persistent terminal sessions, local projects, Git worktrees, file editing, skills, rules, and grid view — work without Portal. Connecting Portal adds catalog-based repository resolution, Workspace context, and transcript sharing. Reference: Xirp and Portal1.5 Does Xirp work with open-source Backstage?
No. Xirp integrates with the Workspaces feature in Spotify Portal.1.6 Is Xirp open source?
No — Xirp is proprietary software distributed by Spotify.1.7 Do I need an account or email to use Xirp Studio?
No. You do not need a separate Xirp account. Email is only needed if you choose to receive product updates; select No thanks to skip that prompt. Portal and your coding agents have their own sign-in. Reference: Getting started — Accept the preview terms1.8 How do I install Xirp?
Open xirp.spotify.com and select Join the beta. On the Get Xirp page, select Download for Mac, then open the installer and move Xirp to Applications. macOS may prompt a security confirmation on first open. Follow the getting-started guide to complete setup. Reference: Getting started — Install Xirp1.9 Is there a command-line tool?
Yes. Xirp installs anxirp CLI alongside the desktop app. It can import sessions from Claude and Cursor, list and message running sessions, create linked shell terminals, and upload transcripts — all from your terminal or from a coding agent.
Reference: Sessions — Command-line tool
1.10 Can I use Xirp Studio offline?
Yes, for up to seven days after its last successful online check. If you are still offline near the end of that period, Xirp reminds you to reconnect. If the period expires, connect to the internet and select Try again to continue. Coding agents and Portal features may still need an internet connection.2. Projects and sessions
2.1 What is the difference between a project and a session?
A project is a local folder registered in Xirp — it acts as the working directory. A session is a persistent terminal running a coding agent inside a project. One project can have many sessions running in parallel. Reference: Projects · Sessions2.2 Can I run multiple agents at the same time?
Yes. You can run sessions with different agents across different projects, or multiple sessions within the same project using separate Git worktrees. Use grid view (Cmd+G) to see them all at once. Reference: Sessions — Grid view2.3 What happens when I close the app — do I lose my sessions?
No. Sessions are persistent and survive app close and reopen. You can pick up where you left off. Reference: Sessions2.4 What is the difference between a session and a worktree?
A session is a running agent conversation. A worktree is a separate Git checkout that gives the session its own branch and working directory. Closing a session does not delete its worktree, and deleting a worktree does not close the session — they are managed independently. Reference: Sessions — Worktrees for parallel work2.5 Does Xirp upload my code to Portal?
No. Registering a project or connecting to Portal does not upload any local files. Code stays on your Mac. The only thing that can be uploaded is a session transcript, and that requires a manual action. Reference: Connecting to Portal — Security and access2.6 Can I see a summary of my weekly activity?
Yes. Open the Weekly Rewind from the header to see sessions started, PRs merged, lines changed, cost, and an activity heatmap. On Friday afternoons, Xirp can nudge you when a new summary is ready; turn the reminder on or off under Settings.3. Portal and Workspaces
3.1 What does connecting Portal add?
It adds the ability to launch sessions from catalog entities or Workspaces, resolve repos from catalog metadata, give agents access to Workspace context (wiki pages, records, resources, members, prior sessions) via MCP, and upload session transcripts for teammates. Reference: Xirp and Portal — What Portal adds3.2 How do I connect Xirp to Portal?
Either start from Portal (Workspaces > Get Xirp) or from Xirp (enter your full Portal URL includinghttps:// and sign in through the browser). Both flows end with the same authorized connection.
Reference: Connecting to Portal
3.3 Why can’t I see a Workspace?
You need to be an invited member of that Workspace. Connecting Xirp to Portal does not automatically grant membership — a Workspace owner or Portal administrator must add you. Reference: Connecting to Portal — Troubleshooting3.4 Can I use Workspace context without Xirp?
Yes. Workspace context is available via MCP, so any MCP-compatible client can query it. Xirp provides the integrated launch and upload workflow, but it is not the only way to access Workspace tools. Reference: Xirp and Portal — Build once, use anywhere4. Security and privacy
4.1 Where is my data stored?
Xirp stores its local state under$XIRP_HOME (defaults to ~/.xirp). In the desktop app, this is an app-specific data directory per edition, with the embedded database under $XIRP_HOME/db. Claude Code session history remains in Claude Code’s own local storage (~/.claude/projects) — Xirp reads but does not write to it. Portal OAuth tokens are stored in your operating system’s secure credential store.
If the local database cannot start, Xirp offers to restore from a saved backup. You can also choose Restore from Backup from the app menu to recover manually.
4.2 Does registering a project upload my files?
No. Projects are local references to folders on your Mac. Nothing is sent to Portal by registering a project. Reference: Projects4.3 What is included in a transcript upload?
Transcripts include the full conversation, tool calls, file changes, agent reasoning, and file paths. They can contain code excerpts and any information the agent processed during the session. Reference: Launching sessions — Transcript sharing4.4 Does Xirp redact secrets from transcripts?
No. Xirp does not scrub or redact credentials, personal data, or sensitive content before upload. You must review the transcript before uploading and avoid uploading sessions that contain secrets, credentials, customer data, or restricted source content. Reference: Launching sessions — Transcript sharing4.5 What does Xirp send in usage telemetry?
Optional usage telemetry reports activity such as app starts, session activity, and availability check outcomes. It uses a random identifier for your installation, along with timestamps, app version, and platform. It does not include your email, email domain, prompts, code, file paths, or free text. An email you enter for product updates is not linked to usage telemetry. Usage telemetry is enabled by default. You can turn it off in Settings > Advanced > About; this stops optional collection and delivery and discards queued events. Administrators can also setCHIRP_TELEMETRY=0 to force it off. Required availability checks still use the installation’s random identifier when usage telemetry is off.
5. Beta limitations
5.1 Can I deploy Xirp on a server or connect to remote sessions via SSH?
Not currently — Xirp runs locally on your Mac. There is no server deployment or SSH session hosting mode today.5.2 What is not supported yet?
- Windows and Linux
- User-owned GitHub Apps (only org-level installations)
- Automatic monorepo onboarding
- Automatic transcript upload (currently manual)
- Workspace-launched sessions require a catalog component with a resolvable source repository