/lanes-sessions

name: lanes-sessions
description: Use when managing Lanes issues or driving Claude Code sessions through the lanes_* MCP tools — creating issues, starting/stopping/inspecting sessions, batch-launching work across worktrees, reading terminal output, attaching labels and components by UUID, or moving issues across the backlog/todo/in-progress/done columns. Skill applies whenever a request mentions "Lanes", "lanes board", "lanes issue", "lanes session", or any lanes_* tool name.

Lanes sessions

Lanes is a desktop app that puts every AI coding session on an issue board. It exposes a local MCP server (SSE on `http://localhost:5353/sse`) with a set of `lanes_`-prefixed tools for issue CRUD, session orchestration, history, and metadata lookups.

A single issue can host **multiple concurrent CLI sessions** (Claude, Codex, shell). Session-targeting tools take an optional `session` ref (UUID, auto-assigned slot, or name) to pick which one — see the "Multi-session model" section below.

Use this skill whenever the user wants to look at, create, or run work on the Lanes board through chat.

Verify the MCP is connected

Before doing anything, sanity-check that the Lanes MCP is reachable:

• Call `lanes_list_components`. If it returns an array (possibly empty), you're good.
• If the tool isn't available at all, the MCP isn't installed. Tell the user to run the `/lanes:setup-mcp` slash command (shipped alongside this skill) or, if they have raw skills only, run:

  claude mcp add --transport sse lanes-local http://localhost:5353/sse --scope user

Then restart Claude Code so the new MCP loads. Lanes itself must also be running (the desktop app must be open).

Tool inventory

| Group | Tool | Purpose | |---|---|---| | Issues | `lanes_list_issues` | Filter by `step` / `tags` (any-match) / `componentId` / `search`. | | | `lanes_get_issue` | Full details by `id`. Does **not** include sessions. | | | `lanes_create_issue` | Required: `title`. | | | `lanes_update_issue` | Patch by `id`; pass `null` to clear nullable fields. | | | `lanes_delete_issue` | By `id`. Permanent. | | | `lanes_move_issue` | Shorthand for `update_issue` with only `step`. | | Sessions | `lanes_start_session` | Required: `issueId`. Spawns Claude Code (default), Codex, or `shell`. **Always adds a new session**; returns its slot + UUID. | | | `lanes_stop_session` | Stop a session for `issueId`. Optional `session` (UUID/slot/name) to disambiguate when >1. | | | `lanes_resume_session` | Re-attach Claude to a stopped session. **Claude-only.** Optional `session`. | | | `lanes_delete_session` | Permanently delete a session (stops it first if running). Optional `session`. | | | `lanes_get_session_status` | With `issueId`: bare array of every session for that issue (status under both `status` and `runtimeStatus`). Without: envelope `{ sessions, appliedFilters, truncated, totalAvailable }` capped at 20. | | History | `lanes_get_issue_changes` | `git diff` for the issue's cwd, by `id`. | | | `lanes_get_issue_history` | Paginated Claude conversation history, by `id`. Use `cliSessionId` to pick when an issue has multiple Claude sessions. | | | `lanes_read_terminal` | Last `lines` (default 200, max 2000) of PTY scrollback. Optional `session`. | | | `lanes_get_session_stats` | Tokens, model breakdown, tool calls, duration, by `id`. Use `cliSessionId` to pick when an issue has multiple Claude sessions. | | Metadata | `lanes_list_labels` | UUIDs, names, colors. Call before assigning `tags`. | | | `lanes_list_components` | UUIDs, names, project IDs. Call before setting `componentId`. | | | `lanes_delete_worktree` | Remove a git worktree on disk by `projectPath` + `name`. |

Note the parameter-name inconsistency: issue endpoints take `id`, session endpoints take `issueId`. Don't mix them. Session-targeting tools additionally accept an optional `session` ref (UUID, slot, or name — case-insensitive).

Multi-session model

An issue can host any number of concurrent CLI sessions. Each session is addressable three ways:

• **`session_uuid`** — Lanes' internal stable ID.
• **`slot`** — auto-assigned ordinal at spawn (`"1"`, `"2"`, …, lowest free integer).
• **`name`** — optional user-editable label.

Session-aware tools (`lanes_stop_session`, `lanes_resume_session`, `lanes_delete_session`, `lanes_read_terminal`) take `session: string` resolved in that order, case-insensitive. When `session` is omitted:

• **One session for the issue** → tool proceeds against it. Happy path is unchanged.
• **Multiple sessions** → tool returns an **MCP success result** (not an error) whose text starts `"Issue N has multiple sessions…"` and whose `_meta.sessions` array lists each candidate as `{ sessionUuid, slot, name, runtimeStatus, cli, cliSessionId, createdAt }`. Pick one (ask the user if not obvious) and retry with `session` set to its slot, name, or UUID.

`lanes_get_session_status` is the read side and takes **no** `session` param. With `issueId` it returns a bare array of *every* session for that issue; each entry carries the runtime status under both `status` and `runtimeStatus` (same value, two keys). Filter that array yourself by slot / UUID.

`lanes_start_session` **always creates a new session.** It is never a way to re-attach or to "make sure" one is running — each call adds another slot. To re-attach, use `lanes_resume_session`.

`lanes_resume_session` is the **only** way to re-attach a stopped Claude session. Do **not** pass `--resume`, `--continue`, `--session-id`, or `--fork-session` to `lanes_start_session` — those flags are hard-rejected. Codex and shell sessions have no resume semantics; start fresh.

Starting is asynchronous

`lanes_start_session` hands the launch to the Lanes app and waits up to ~10s for the new session to register, then returns its slot and UUID. Two things follow:

• **A response that says it could not confirm is not a failure.** The launch may still be in flight — worktree creation runs a real `git worktr