Sessions are the runtime engine of Lanes. Each session is a real pseudo-terminal (PTY) running an AI coding agent, attached to an issue on your board. You can run multiple sessions in parallel, including several on the same issue, and watch them all from the board.
What Is a Session?
A session is a live terminal process, backed by a PTY, that runs an AI CLI like Claude Code, Codex CLI, or Gemini CLI. It has its own working directory, scrollback buffer, and lifecycle state. Sessions are always linked to an issue, which gives you a single place to track the task, its output, and its results.
Sessions survive if you close the detail panel or switch focus to another issue. They keep running in the background, and you can reconnect at any time by clicking the issue card.
Many Sessions Per Issue
Since v0.41, an issue can host as many sessions as the work needs. Each session gets its own slot (session-1, session-2, and so on) and an editable name. Sessions share the issue's worktree branch but run independently, with separate transcripts, status, and metrics.
A few patterns this unlocks:
- Plan, implement, review on one ticket. One session drafts the approach, the next executes it, a third audits the diff. Each stage keeps its own history instead of collapsing into one giant transcript.
- Compare two approaches. Spawn a sibling to try a different prompt, model, or cut at the same problem. Pick the diff you like, drop the other.
- Park work in parallel. A long-running investigation in one session, scratch work in another, nothing gets lost when you context-switch.
The issue stays the unit of work; the sessions become the stages of it.
Spawning a sibling session
Start a new session from inside an existing one (the + in the session selector, or Cmd+N while focused on an issue that already has a session). Lanes treats the new session as a sibling on the same issue: no second ticket, no extra setup, same worktree.
Naming sessions
Each session has an inline-editable name. Rename session-1 to plan, session-2 to implement, and session-3 to review so the selector reads as a workflow instead of a list of numbers. Names are saved per session and persist across restarts.
Session Settings on Launch
When you start a new session, the picker opens with a Session Settings flyout that puts Harness, Model, Effort, Gateway, and Flags in one place. A pill at the top of the new-session view shows the current selection at a glance (for example, Claude Code / claude-opus-4-7 / max); one click on it opens the rest.
Setting these upfront means the agent runs with the right configuration from the first message, instead of being reconfigured mid-prompt.
| Setting | What it controls |
|---|---|
| Harness | Which agent CLI to launch (Claude Code or Codex), or a bare terminal. See Harness. |
| Model | The model the CLI uses for this session. The picker lists models supported by the selected CLI, and the real tags on your daemon when a local model is active. |
| Effort | Reasoning effort or "thinking" budget where the CLI exposes it (for example, Claude Code's max setting). |
| Gateway | Which provider profile this session's requests go to. Default uses the CLI's own provider. |
| Flags | Additional CLI flags for this session only. These layer on top of the repo-wide flags from Project Settings > CLI Flags. |
The repo defaults from Settings > General (CLI) and Project Settings > CLI Flags are pre-filled. Overrides here apply to the session you're about to launch and are captured in the side panel so you can see what each session actually ran with.
Starting a Session
Select an issue on the board and look at the detail panel at the bottom of the screen. You will see two start buttons:
- Plan: Launches the agent in plan mode. It reads the issue instructions, analyzes the codebase, and proposes a plan without making changes. The issue moves to the Planning column. Use this when you want to review the approach first.
- Implement: Launches the agent in implementation mode. It begins working on the task immediately, making code changes as needed. The issue moves to the Implementation column.
Both modes send the issue's instructions as the initial prompt to the agent and respect the Session Settings flyout described above.
Starting a Bare Terminal
Press Cmd+T to open a new bare terminal session. This creates a plain terminal (not attached to an AI agent) that you can use for running tests, checking logs, or any other shell task. Bare terminals are also attached to an issue for tracking purposes, and they count as a session slot like any other.
The Session Selector and Quick Actions
Open the session selector from the detail panel header on any issue. The selector groups everything you can do on that issue in one menu:
- Sessions lists every session attached to the issue. Click one to focus it, or use the + to spawn a new sibling.
- Quick Actions lists the quick commands configured for this repo plus your general ones:
test,commit,release,fix-lint, deploy scripts, anything the project defines. Click one and it runs on the same worktree, attached to the same issue.
Spawning a new session and running a quick command now share the same surface, so you don't have to jump between panels for either action. Worktree creation is also reachable from the same menu when the issue doesn't have one yet.
The Terminal Panel
The terminal panel occupies the left side of the detail view at the bottom of the screen. It is a fully functional terminal emulator with:
- Real-time output streaming from the AI agent
- A scrollback buffer (approximately 50KB) so you can review earlier output
- Dynamic resizing: drag the divider between the terminal and the issue details panel to adjust the split
The right side of the detail view shows the Issue tab (notes and instructions) and the Meta tab (session metrics like tokens, cost, and runtime duration).
Interacting with the Terminal
While a session is running, you can interact with it directly:
- Type in the terminal: Your keystrokes are sent directly to the running process. Use this to answer agent questions, approve plans, or provide additional context.
- Drag and drop files: Drag a file from your file manager (or the Lanes file browser) onto the terminal. Lanes injects the file path as text, which is useful for pointing the agent at specific files.
Session Status Indicators
Each issue card on the board shows the current session state with a visual indicator. When an issue has multiple sessions, the card aggregates them: the most active state wins, and the indicator counts how many sessions are in that state.
| Status | Meaning |
|---|---|
| Busy | The agent is actively working: processing, writing code, or thinking. |
| Awaiting input | The agent has paused and is waiting for you to provide input or approval. |
| Stopped | The session was manually stopped. The issue remains on the board. |
| Exited | The agent process exited on its own (finished its work or encountered an end condition). |
| Error | The session encountered an error. Check the terminal output for details. |
These indicators update in real time, so you can monitor several agents at a glance from the board.
Status detection was rewritten in v0.40 and tightened again in v0.41. The orange "awaiting input" bell now gates on the status file and title-idle markers with a 5-second floor, so continuous title updates from the CLI no longer false-trigger it. If you saw flicker on earlier builds, that pattern is gone.
Resuming Claude Sessions
When you stop and restart a Claude Code session, Lanes automatically passes the --resume flag. This tells Claude Code to pick up where it left off, using the conversation history from the previous run. You do not lose context when you need to pause and restart.
To re-attach a stopped session from outside the app (for example, from an MCP-driven workflow), use the lanes_resume_session tool on the Lanes Desktop MCP server, which is the programmatic equivalent of the Resume Session button in the UI.
Session History
The detail panel includes a History tab that shows a paginated transcript of the session. This is a JSONL-based viewer that records every message exchanged between you and the agent, along with tool calls and their results. Each session has its own history, so siblings on the same issue stay independent.
Use it to review what the agent did after the fact, especially for long-running sessions or when you want to diff how two siblings approached the same problem.
Stopping Sessions
There are several ways to stop a running session:
- Stop button: Click the stop button in the detail panel toolbar. Only stops the focused session.
- Right-click > Stop Runtime: From the issue card context menu on the board. Stops every session on that issue.
- Cmd+D: Marks the issue as complete, which stops all of its sessions automatically.
- Bulk stop: Select multiple issues and use the bulk toolbar's Stop action.
Sending to Review
When you're done with planning or implementation and the work needs human review before being marked Done, press Cmd+R (or click the Send to Review button in the detail panel footer). This moves the issue to the Review column without stopping any sessions, keeping the agent's context alive in case the reviewer asks for changes.
Completing an Issue
When you mark an issue as complete (via Cmd+D, the Complete context menu item, or dragging to Done):
- Every running session on the issue is stopped.
- If the issue had a dedicated worktree, Lanes checks for uncommitted changes. If the worktree is clean, it is automatically removed. If it has uncommitted work, Lanes warns you before cleanup.
- The issue moves to the Done column.
You can always reopen a completed issue by dragging it back to an earlier column and starting a new session.