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 in the header 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
  • Use voice input (Cmd+J) to dictate prompts
  • Fork a conversation to explore another approach
  • Open a linked shell in the same worktree
  • 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.

​
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.

​
Upload a session to Portal

Any session can be uploaded to a connected Portal Workspace. Use the upload action to choose a target Workspace, or create a new Workspace directly from the upload flow. 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.