Sessions

Sessions

A session is a running instance of an agent working inside a project. Branch strategies decide whether that session creates a new branch-backed worktree, reuses an existing branch, opens a disposable inspection workspace, or runs headless without an execution cwd.

Creating a Session

Press Mod+S from anywhere to open the New Session wizard. Pick a project, choose an agent, then optionally attach an issue, pull request, or branch. In the context step, choose a branch strategy to preview whether Taskeract will create a branch, reuse a source branch, launch a disposable workspace, or stay headless. When a terminal-backed session starts, a toast tells you to press Mod+I to inject the attached context into the agent’s prompt.

When you confirm, Taskeract resolves the selected branch strategy. Depending on the workflow, it may fetch remote refs, create a new branch-backed worktree from origin/{development_branch}, attach a workspace to a pull request or existing branch, provision a disposable inspection checkout, or start the session without an execution workspace. Reuse-style launches keep the one-session-per-branch rule: if an active branch-owning session already owns that branch, Taskeract switches back to it instead of creating another one. If any session already has that branch open, Taskeract also blocks starting a second inspection workspace on the same branch until detached inspection workspaces exist. The development and production branches come from project configuration or remote auto-detection when not set explicitly.

You can also create a session from a pull request in the sidebar, from an issue in the Issues view, or from a remote branch in the Git History viewer. These shortcuts pre-select the workflow source; the active strategy still decides whether Taskeract reuses that branch, creates a disposable inspection workspace, or stays headless.

If the project is not in a git repository, branch-backed and inspection strategies are unavailable. Taskeract falls back to shared-path or headless behavior, and only one workspace-backed session can be active at a time.

On Pro plans, each agent in the picker has a shield icon you can click to start the session in sandbox mode, restricting the agent to only the project's files and approved network destinations.

Session Naming

Branch-creating sessions are assigned generated branch names like feature/swift-falcon. Reused branch strategies keep the source branch name instead. The suffix (for example swift-falcon) is used as the default session title in the sidebar and the session header when a branch-backed workspace exists. Headless workflows rely on the session title or workflow context instead. To rename a session, hover over the title in the session header and click the pencil icon.

Embedded Terminals

Workspace-backed sessions run in a full embedded terminal with PTY support. Agents render exactly as they would in your regular terminal — including colors, TUI interfaces, and interactive prompts. Terminal scrollback is preserved per session and restored when switching tabs. A separate History tab captures every line of output as clean, structured text — including content lost to screen clears and progress bar overwrites — so nothing is ever lost. Headless workflows skip terminal provisioning entirely.

Resuming Sessions

Sessions persist across application restarts. When you reopen a session, Taskeract uses the agent's own native resume capability to restore its conversation state. How much context the agent retains depends entirely on the agent — Taskeract passes the session identifier through and the agent handles the rest.

How much context an agent retains on resume depends on the agent itself. For best results, start a new session when you move on to a new task. The History tab captures a complete record of terminal output regardless of what the agent remembers.

Permissions

When an agent requests permission (e.g., to write files or run commands), the session's status indicator turns yellow. The system tray icon also shows a yellow dot so you can tell at a glance that a session needs attention, even when Taskeract is in the background.

External Editor

The session toolbar shows an editor button (code icon) when a supported editor is detected on your system and the active strategy provides an execution workspace. Click it to open the session's working directory in your default editor. Shift+click the button to pick a different editor — your choice becomes the new default. Supported editors include VS Code, Cursor, Windsurf, Zed, IntelliJ IDEA, WebStorm, Sublime Text, Neovide, Neovim, Vim, and Emacs. You can also open the editor via Jump Mode (Mod+G then =).

Stopping Sessions

Right-click an idle session and choose Stop Session to terminate the agent without deleting the session. The worktree, branch, and scrollback are preserved. Click the session again to relaunch the agent.

Stop is only available when the agent is idle or in an error state — it is disabled while the agent is actively working or waiting for a permission response.

Terminal & Logs

Embedded Agent Terminals

Workspace-backed agent sessions run inside embedded terminal emulators with full PTY support. This means you get the same experience as running agents in your regular terminal — colors, cursor movement, TUI rendering, and interactive prompts all work as expected. Scrollback is preserved per session and restored instantly when switching between tabs. Selecting text with the mouse automatically copies it to the clipboard -- the selection clears and a brief confirmation appears so you know it worked.

History Tab

Terminal sessions have a History tab that captures every line of terminal output as ANSI-stripped, timestamped text. Unlike the live terminal view, the History tab preserves content that would otherwise be lost to screen clears, progress bar overwrites, and TUI redraws. History is persisted to disk, so it survives application restarts and is available even after a session's PTY has been killed.

The History tab supports the same vim-style keybindings as the Changes and Logs views: j/k to navigate, v for visual selection, and y or Space to yank selected lines to the clipboard.

The top of the History tab also includes recovery controls. Use Create Checkpoint to save a durable restore point, Restore to roll the current session back to an earlier checkpoint, or Fork to start a new child session from one. If the shared branch is rewritten or disappears upstream, Taskeract shows a recovery prompt in the session header and a Create Recovery Branch action in the History panel so you can move the session onto a new publish branch without touching the old branch in place.

The same publish recovery flow is available from the keyboard. Press Mod+P or Mod+M while the session is in a rewritten or branch-gone state and Taskeract opens the recovery dialog instead of attempting an unsafe push or merge.

Shell Access

Sessions with an execution workspace have a terminal icon that opens an embedded shell in the session's worktree. Click it multiple times to open additional shells. You can also press Mod+` or use jump mode 0 to open a new shell from the keyboard. Shift-click the icon to choose a different shell program. Headless workflows do not expose shell access. See Shell Terminals for details.

Logs View

For projects with startup commands configured, the Logs tab shows their output. Logs can be viewed per command (separate tabs) or combined into a single stream. You can navigate the logs using the keyboard and copy items to the clipboard.

When a command fails to start or exits unexpectedly, the failure appears as a highlighted line in the logs. An error badge also appears in the session header — clicking it jumps straight to the failed command's output, and Shift-clicking it retries all failed init commands. Clearing the logs dismisses the badge.

Image Pasting

Paste images from your clipboard directly into agent terminals. Agents that support image input — like Claude Code — will see the image alongside your text prompt and can reference it in their response.

Pasting Images

Press Mod+V or use your system paste shortcut while the terminal is focused. If the clipboard contains an image, a thumbnail preview appears in the bottom-right corner of the terminal. Multiple images stack vertically. Each preview shows the image dimensions and a close button to remove it before sending.

Image Viewer

Click any thumbnail to open a full-screen lightbox. Use the arrow keys or on-screen navigation to move between images. Press Escape to close. The lightbox shows the current image index (e.g., “1 / 2”) so you can keep track of multiple pastes.

Guest Agents

When an agent is stuck or you want a second opinion, you can launch additional agents inside the same session workspace. Guest agents see the same code and branch context as the primary agent but run independently in their own terminal tab. Guest agents are available only for strategies that provide an execution workspace.

To launch a guest agent, click the guest agent button (layers icon) to the left of the tab bar in the session view, or click the + button in the terminal tab bar. Select any available terminal agent from the dropdown. The guest agent starts fresh in the session workspace — it does not resume from the primary agent's conversation.

Each guest agent gets its own tab in the terminal area. Switch between the primary agent and guests by clicking their tabs. Close a guest tab with the × button to terminate it and remove the tab. When a guest agent exits on its own, its tab shows (exited) and you can press any key to relaunch it.

Guest agent tabs survive application restarts in an “exited” state. Stop Session terminates the primary agent and all guests. Delete removes everything. The sidebar shows a +N badge when a session has active guest agents, and the session's status indicator reflects the highest-priority state across the primary and all guests.

Deleting Sessions

Right-click a session in the sidebar and choose Delete. Taskeract performs a safety check before deleting:

• If the session's worktree has uncommitted changes, you'll see a warning with the number of affected files.
• If the session's branch has not been merged into the base branch and there is no open pull request, you choose whether to also remove the remote branch or keep it.
• If the session has an open pull request, the remote branch is automatically preserved so the PR remains valid.
• If the branch has already been merged, the remote branch is automatically cleaned up.

Deletion is never blocked — warnings are informational so you can make an informed choice. When you confirm, the session is soft-deleted: its worktree and local branch are removed, and the session record is preserved so it can be restored later.

Restoring Sessions

Soft-deleted sessions can be restored from the Deleted tab in Project Properties. Each deleted session shows its title, agent type, branch name with a status badge (local, remote, or gone), and any associated pull request.

Each deleted session has History and Recording buttons so you can inspect its terminal output or replay the full recording without restoring it. The history view includes full search (/) and copy (v + y) support, and the recording view supports Continue From Here to create a new child session from the selected point.

Click Restore to bring a session back. Taskeract recreates the worktree from the existing branch — whether it still exists locally, only on the remote, or needs to be created fresh — and the session reappears in the sidebar.

Permanent Deletion

From the same Deleted tab, click Delete Forever to permanently remove a session. This deletes the database record and all associated messages, and removes any remaining local or remote branches. If the branch has not been merged and there is no open pull request, you choose whether to remove the remote branch or keep it. This action cannot be undone.