Skip to main content
A session is a persistent terminal running a coding agent. It can belong to a project and worktree, or run as a general session without project context.

Create a session

Select the + button at the top of the sessions panel to choose a project or a general session. Project picker for a new session The full session form lets you:
  • Describe the goal
  • Select a coding agent (Claude Code, Codex, Gemini CLI, Pi, or Cursor)
  • Use the main checkout or create a new Git worktree
  • Attach screenshots to the initial prompt
  • Override supported per-session agent options
  • Start in the foreground or background
New session form Write a goal that describes the intended outcome, relevant constraints, and how you will recognize completion. Xirp sends the goal to the selected agent as its initial prompt.

Work with the terminal

The session page is a full interactive terminal. The toolbar shows the project, session, branch, context-window use, worktree, selected agent, and session controls. A completed coding-agent response in a Xirp terminal You can:
  • Type and respond exactly as in the native coding-agent CLI
  • Change to another installed coding agent during a session
  • Open the worktree in an external terminal or editor
  • Browse files and review Git changes without leaving the session
  • Open an inline code review panel for diffs
  • Open a browser panel (Cmd+Shift+B) alongside the terminal and annotate page elements to send comments to the agent
  • Use voice input (Cmd+J) to dictate prompts
  • Review agent responses passage by passage and send selected passages back as a follow-up
  • Copy an agent response with the hover action
  • Insert a saved prompt from the prompt palette (Cmd+Shift+;)
  • Split the terminal into multiple panes to run commands side-by-side
  • Fork a conversation to explore another approach
  • Open a linked shell in the same worktree, or create one from the CLI with xirp session new-terminal
  • Open a standalone project terminal without starting a coding agent (Ctrl+Shift+T)
  • Cmd+click a file path in terminal output to open it in the built-in editor
  • Take a screenshot of the current window to your clipboard (Cmd+Shift+X)
  • Stop or close a session
Agent permission bypasses and autonomous modes can allow file changes, shell commands, and network calls without confirmation. Use the native agent’s sandbox and permission controls, and prefer disposable worktrees for risky tasks.

Session status

With session hooks enabled, Xirp distinguishes common states:
  • Working: the agent is processing the task.
  • Idle: the agent is ready for input.
  • Waiting: the agent needs a response or permission decision.
  • Queued: the session is waiting for a parent session to complete.
  • Completed: the session finished successfully.
  • Failed: the underlying process ended with an error.
Status indicators appear in the minimap and project overview. Notifications can alert you when a background session needs attention.

Workflow status

Sessions can also carry a workflow status — backlog, in progress, in review, done, or blocked — to track where a task sits in your development cycle. You can group and sort sessions by workflow status. Turn this on under Settings > Sessions > Workflow.

Use worktrees for parallel work

A new-worktree session receives its own Git branch and checkout. Use one worktree per independent task when several sessions may change the same repository. Before deleting a worktree, review uncommitted changes and confirm whether Xirp should also remove its branch. Closing a session and deleting a worktree are separate actions.

Grid view

Grid view places multiple live terminals in one window. Open it with Cmd+G, then add sessions from the minimap. A session in grid view You can resize the grid, focus a pane, maximize a session, group sessions by theme, and filter by project. Each pane remains interactive.

Find and navigate sessions

  • Select a minimap card to focus a session.
  • Press Cmd+Left or Cmd+Right to move between sessions.
  • Press Cmd+Shift+K to open the recent-session switcher.
  • Press Cmd+K to search projects, sessions, views, and actions.
  • Press Cmd+/ to see all shortcuts.

Saved prompts

Save prompts you use often and recall them from a searchable palette (Cmd+Shift+;). Select a prompt to insert it into the active session. Prompts can be global or scoped to a project.

Upload a session to Portal

Any session can be uploaded to a connected Portal Workspace. The upload button on the session toolbar names the workspace it sends to. A menu beside it lets you pick a different workspace or create a new one. Uploading shares the transcript with authorized Workspace members and makes it available as context for future sessions. Review the transcript before uploading. Workspace permissions control who can access it. See Launch and share Xirp sessions.

Command-line tool

Xirp installs an xirp command alongside the desktop app. From your terminal or from a coding agent you can:
  • Import sessions from Claude and Cursor into Xirp
  • List and message running sessions
  • Create a linked shell terminal for an existing session (xirp session new-terminal)
  • Upload transcripts to a Portal Workspace
Run xirp --help for the full command reference.