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 Claude, Codex, or Gemini
  • 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
  • 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.
  • Finished or failed: the underlying process ended.
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

Sessions associated with a Portal Workspace can be uploaded manually. 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.