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, and Gemini. 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: Getting started — Choose a default coding agent1.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 How do I install Xirp?
Download the app from xirp.spotify.com, drag it to Applications, and launch. macOS may prompt a security confirmation on first open. You can create a Spotify Technology account directly inside the app. Reference: Getting started — Install and sign in2. 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 access3. 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 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.2 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.3 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 sharing5. Beta limitations
5.1 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