Sessions

Sessions

A session is a running instance of an agent working inside a project. Each session gets its own git worktree and branch, providing full isolation from your main branch and from other sessions.

Creating a Session

Select a project, then press Mod+S or click New Session. Choose an agent and Taskeract fetches the latest remote refs, creates a git worktree branched from origin/{development_branch}, launches the agent in an embedded terminal, and begins streaming output. The development branch is read from your project configuration, or auto-detected from remotes if not set.

If the project is not in a git repository, worktree isolation is not available and you will be limited to a single session.

Session Naming

Each session is assigned a generated branch name like feature/swift-falcon. The suffix (e.g., swift-falcon) is used as the default session title in the sidebar and the session header. To rename a session, hover over the title in the session header and click the pencil icon. For web app projects, the same suffix is also used as the session's .tact subdomain.

Embedded Terminals

Each agent runs in a full embedded terminal with PTY support. This means 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.

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.

In practice, some agents handle resume better than others, and very long sessions may lose earlier context on reload. This is a limitation of the agent's own session management, not something Taskeract can control. The History tab is your safety net here — it captures a complete, timestamped record of every line of terminal output regardless of what the agent remembers. If an agent loses track of earlier work, you can always reference the History tab to see exactly what happened.

For best results, start a new session when you move on to a new task. Shorter, focused sessions tend to resume more reliably than very long ones, and each session gets its own isolated worktree anyway, so there's no cost to starting fresh.

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.

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.

Guest Agents

When an agent is stuck or you want a second opinion, you can launch additional agents inside the same session's worktree. Guest agents see the same code and branch as the primary agent but run independently in their own terminal tab.

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's worktree — 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, you'll see a warning naming both branches.

Deletion is never blocked — warnings are informational so you can make an informed choice. When you confirm, the session is soft-deleted: its worktree is removed and the branch is cleaned up locally and on the remote, but 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 a History button to view its terminal output without restoring. The history view includes full search (/) and copy (v + y) support.

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. This action cannot be undone.