lanes-sh/app/lanes-sessions

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-desktop:setup-mcp slash command (shipped alongside this skill) or, if they have raw skills only, run:

`` claude mcp add --transport sse lanes-desktop 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).

Working inside a Lanes session

Everything else here assumes you are driving the board from outside. When Lanes launched you, three environment variables say so:

Read them with echo $LANES_SESSION. If LANES_TERMINAL is unset you are an ordinary Claude Code session with no issue to report against, so skip to the tool inventory.

Link every worktree you create

Every `git worktree add` you run is followed by `lanes_update_issue { id: $LANES_SESSION, branch: "<branch>" }`. Not conditionally, not once you are finished. A worktree Lanes did not create is a worktree the issue does not know about, and until you link it the Changes tab and lanes_get_issue_changes both show an empty diff, so your work reads as never having happened.

Setting branch is the whole job. Lanes finds the worktree that branch is checked out in and fills worktreeStrategy, worktreePath and worktreeName from it, so do not set those three yourself.

Then check it took:

lanes_get_issue { id: $LANES_SESSION }

worktreeStrategy should be "select" and worktreePath should be the folder you are working in. If worktreeStrategy came back "none", Lanes could not find a worktree for that branch. Call lanes_list_worktrees, find your folder in the list, and pass its path:

lanes_update_issue { id: $LANES_SESSION, worktreePath: "<path from the list>" }

If your folder is not in that list either, you are in a repository Lanes has no working folder linked for, and there is nothing to link the issue to. Say so rather than retrying.

When Lanes started you inside a worktree it made, lanes_get_issue already reports "create" or "select" and there is nothing to do. Checking costs one call and is worth it before you assume.

Linking is not the same as asking for a worktree. worktreeStrategy: "create" only affects the next session on the issue and never relocates a running agent, so setting it mid-session will not move you.

Tool inventory

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 worktree add, and if the issue has no usable cwd Lanes opens a folder picker and waits on the user indefinitely. Read lanes_get_session_status { issueId }, or ask the user to look at the Lanes window.
• An empty session list is not proof the start failed. In the window before the session registers, lanes_get_session_status returns [] and the session-aware tools return "No sessions exist for issue N yet". Both are expected. Wait and re-read.

Never re-issue lanes_start_session to check on a previous one. That is how you end up with five identical sessions on one issue.

cliSessionId (the CLI's own resume token — for Claude, the --resume <uuid> value) is distinct from session_uuid (the Lanes ref used in session). lanes_get_issue_history and lanes_get_session_stats disambiguate via cliSessionId; everything else uses session. Don't conflate them.

Critical gotchas

• Labels and components are UUIDs, not names. Always call lanes_list_labels / lanes_list_components first and resolve names → UUIDs locally. Passing a plain name like "bug" will not match anything.
• `step` is a status id, and the user defines the statuses. Each tool's step enum comes from the user's Settings > Workflows, and its description names every option as id (Label, category). The built-in ids are backlog, planning, implementation, review, misc and done. The user can rename them, switch them off, and add their own, such as todo. A renamed status keeps its id, so match on the id, never the label. Create, update and move take active statuses only, and the error for anything else lists the ones that are. Use lanes_move_issue if you only want to change the step.
• Each status is Not started, In progress or Done. Moving an issue into any Done status finishes it, and lanes_list_issues leaves every Done status out by default, not only done. A new issue with no step lands in backlog, or in the first active Not started status while Backlog is switched off.
• Worktree auto-create requires two fields, set in advance. To make lanes_start_session create a fresh git worktree, the issue must already have worktreeStrategy: "create" AND worktreeName: "<branch>". Set them via lanes_create_issue or lanes_update_issue before calling start_session. To attach an issue to a worktree that already exists (one you made yourself, mid-session), set branch instead — see "Link a worktree you created yourself".
• `prompt` has three modes:
• Omitted → uses the issue's description (falling back to title).
• "" (empty string) → starts the session with no prompt at all.
• "text" → overrides the description for this session only.
• `flags` array shape for lanes_start_session:

``json [ { "flag": "dangerously-skip-permissions", "value": "", "kind": "flag" }, { "flag": "ANTHROPIC_MODEL", "value": "claude-opus-4-7", "kind": "env" } ] ` kind: "flag" becomes --flag-name value; kind: "env" becomes ENV=value` prepended to the command.

• `planMode: true` only takes effect when cli: "claude". It maps to --permission-mode plan.
• `lanes_list_issues` filter combination: filters AND together, except tags, which is any-match (issue must have ≥1 of the listed UUIDs).
• `update_issue` to clear a field requires explicitly passing null (or [] for tags/dependencies). Omitting a key leaves it untouched.

Common workflows

Create-and-launch a single issue