> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Xirp and Portal

> Add organizational context, catalog-based launches, shared knowledge, and session continuity to Xirp with Spotify Portal.

Xirp gives every developer a focused desktop workspace for Coding Agent sessions. Spotify Portal adds the organizational context around the code: what a system does, how it fits together, why decisions were made, and what previous sessions learned.

<Note>
  Portal is optional. Xirp's terminals, Coding Agents, local projects, Git
  worktrees, pull request monitoring, skills, and rules work without a Portal
  connection. Portal features apply when you connect an instance and launch a
  session from its Software Catalog or a Workspace.
</Note>

## Start with code or start with context

<Columns cols={2}>
  <Card title="Use Xirp directly" icon="code-branch" href="/docs/xirp/projects">
    Add an existing checkout through Xirp, or clone a repository URL with Git
    and add the resulting local folder. You get the complete local session,
    terminal, Git, and worktree workflow.
  </Card>

  <Card title="Launch from Portal" icon="diagram-project" href="/docs/xirp/workspaces/launching-sessions">
    Select a Software Catalog entity or Workspace. Xirp resolves the repository,
    prepares the local project, and connects eligible sessions to Portal context
    through MCP.
  </Card>
</Columns>

The Coding Agent and local development workflow are the same in both cases. Portal adds a shared context layer.

## Compare the experience

| Capability                                            |                    Xirp with Portal                    |                   Xirp without Portal                  |
| ----------------------------------------------------- | :----------------------------------------------------: | :----------------------------------------------------: |
| Persistent terminal and Coding Agent sessions         | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Local projects and general sessions                   | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Git worktree management                               | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Pull request monitoring for supported Git remotes     | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Local skills, rules, and repository instructions      | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Local session history                                 | <Icon icon="check" color="#34baa2" aria-label="Yes" /> | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |
| Launch from a Software Catalog entity or Workspace    | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |
| Resolve and clone a repository from catalog metadata  | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |
| Workspace wiki pages, records, resources, and members | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |
| Software Catalog entity metadata                      | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |
| Shared Workspace session transcript history           | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |
| Portal Workspace MCP tools                            | <Icon icon="check" color="#34baa2" aria-label="Yes" /> |  <Icon icon="xmark" color="#8f9198" aria-label="No" /> |

You can configure other MCP servers independently of Portal. The comparison above refers specifically to Portal's Workspace context and tools.

## What Portal adds to a session

<CardGroup cols={2}>
  <Card title="Repository discovery" icon="magnifying-glass">
    Portal maps a catalog entity such as `component:default/my-service` to its
    repository through the `backstage.io/source-location` annotation. Xirp can
    match an existing local project or prepare the repository automatically.
  </Card>

  <Card title="Context before coding" icon="brain">
    A Workspace-launched session is instructed to load the project overview
    before starting work, including wiki pages, resources, records, catalog
    entities, and members.
  </Card>

  <Card title="Knowledge on demand" icon="book-open">
    The Coding Agent can use Portal MCP tools to retrieve deeper details when
    needed instead of placing every document into the initial prompt.
  </Card>

  <Card title="Shared continuity" icon="clock-rotate-left">
    Upload an eligible session transcript to its Workspace. Teammates and future
    sessions can use that history instead of rediscovering the same context.
  </Card>
</CardGroup>

Portal context remains associated with a Portal-launched session when you resume or fork it. Directly created Xirp sessions remain local and do not automatically gain Workspace context merely because Portal is connected.

## Build context once, use it across agents

A Workspace brings together catalog entities, wiki pages, technical records, links, documents, ownership, and previous session transcripts. That context is permission-aware and available through MCP. Xirp provides the integrated launch and upload workflow, while other MCP-compatible clients can also use Workspace tools.

<img src="https://mintcdn.com/spotify-89f50c35/Au6-kNeho5Rk8Vno/xirp/assets/workspace-overview-with-resource.webp?fit=max&auto=format&n=Au6-kNeho5Rk8Vno&q=85&s=ad1e91b99f1882dc6852860b6fc1fcb1" alt="A Portal Workspace with shared project context" width="1800" height="1200" data-path="xirp/assets/workspace-overview-with-resource.webp" />

## Add Portal to Xirp

<CardGroup cols={2}>
  <Card title="Try Spotify Portal" icon="rocket" href="https://backstage.spotify.com/contact-us/try-portal/">
    Request access to Spotify Portal and explore shared context for your
    engineering organization.
  </Card>

  <Card title="Learn about Portal" icon="circle-info" href="/docs/portal/">
    Explore Portal's Software Catalog, developer experience, governance, and
    platform capabilities.
  </Card>

  <Card title="Connect Xirp" icon="link" href="/docs/xirp/connecting-to-portal">
    Connect an existing Portal instance to Xirp through OAuth.
  </Card>

  <Card title="Use Workspaces" icon="users" href="/docs/xirp/workspaces">
    Create shared context, launch informed sessions, and preserve useful session
    history.
  </Card>
</CardGroup>