
lanes-desktop
Skills and setup commands for the Lanes desktop app: issue board, sessions, and local MCP. GitHub and Linear bridges moved to lanes-bridges in 0.7.0
- GitHub stars
- 276
Install
/plugin install lanes-desktop@lanesRun it inside Claude Code after adding the marketplace with /plugin marketplace add lanes-sh/app.
Contents
Discovered from sourceSkills 2
Install Lanes Desktop
Lanes is a native macOS app that puts every AI coding session on an issue board: each card is a task, and each task holds live agent terminals, its own git worktree, and the diff those agents produced.
Your job in this skill is to get from nothing to a running app with a project in it, and then to an agent that can drive it. Three steps, one of which is the user's rather than yours.
Homebrew is the only supported install, and it is also the update path. There is no .dmg and no direct download. If you cannot find a cask, that is the answer, not a reason to look for a binary.
Preflight
Run all four before installing. Each failure has a different answer.
| Check | Command | A failure means |
|---|---|---|
| Platform | uname -s | Anything but Darwin: stop. Lanes Desktop is macOS only today. Point at the docs and offer Lanes Link instead, which runs anywhere. |
| macOS version | sw_vers -productVersion | Below 13 (Ventura): stop. There is no build for it. |
| Already installed | test -d /Applications/Lanes.app && echo present | Present: skip step 1. Go to "Update and repair" if they asked to update, or straight to step 2. |
| Homebrew | command -v brew | Missing: install it from https://brew.sh, then come back. Do not hand-roll an install. |
1. Install it
One command. The open -a is chained on so a first install ends with the app running rather than with a cask sitting in /Applications.
brew install --cask lanes-sh/lanes/lanes && open -a Lanes
lanes-sh/lanes is a tap, so the first run also taps it. Expect a download of a few hundred megabytes; do not treat a slow first run as a hang.
Verify:
test -d /Applications/Lanes.app && pgrep -x Lanes >/dev/null && echo running
If the app installed but is not running, open -a Lanes again. macOS may hold the first launch behind a Gatekeeper prompt the user has to answer on screen.
2. Point it at your code
This step is theirs, not yours. The welcome screen needs a folder picker, and you cannot click it.
Tell them: the welcome screen offers four ways in, and the one to pick is Add a project. Choose the folder your repos live in. That becomes the default location for new sessions, and it can be changed later under Settings > General, or per issue.
Then wait. Do not go on to step 3 until they say the app is open with a project in it. The MCP server has nothing to serve before that.
3. Connect your agent
Run the slash command that ships in this same plugin:
/lanes:setup-mcp
It registers the SSE server at http://localhost:5353/sse with Claude Code and with Cursor, skips whichever is not installed, and is safe to run twice. Use it rather than writing the registration yourself. It knows the three names the server has shipped under, and it never renames an existing entry, because a server's config name is the prefix on its tool names and a rename resets the user's tool approvals.
Only if that command is unavailable, because the skills were installed without the plugin:
claude mcp add --transport sse lanes-desktop http://localhost:5353/sse --scope user
Then have them open a fresh terminal so Claude Code loads it.
Verify the endpoint:
curl -sS -m 2 -o /dev/null -w "%{http_code}\n" http://localhost:5353/sse
200 means Lanes is up and the MCP is reachable. Connection refused means either the app is not running, or the server is switched off under Settings > Integrations > Lanes MCP. Ask which before assuming a broken install.
Update and repair
| Situation | What to run |
|---|---|
| Update | brew upgrade --cask lanes-sh/lanes/lanes. The app also updates itself on launch, so this is for when someone wants it now. |
| Reinstall over a broken install | brew reinstall --cask lanes-sh/lanes/lanes |
| Uninstall | brew uninstall --cask lanes-sh/lanes/lanes. Board data lives outside the app and survives. |
| Confirm what is installed | brew list --cask --versions lanes |
| App will not open | Check sw_vers -productVersion against Ventura first, then reinstall. Do not delete /Applications/Lanes.app by hand; Homebrew loses track of it. |
Critical gotchas
- A
200from the probe says the app is up, not that a workspace exists. Someone who skipped step 2 has a reachable MCP over an empty board, and the firstlanes_list_issueswill look broken to them. - The MCP server is a toggle, and it is off until it is turned on. Settings > Integrations > Lanes MCP. Nothing in step 1 or 2 turns it on.
- The port is configurable. If
5353refuses while the app is plainly running, ask them what the Integrations panel says before debugging anything else. - A
lanesentry in an MCP config that does not point atlocalhost:5353is a different server. That is the remote Lanes Forms one. Leave it alone. brew installwithout the chainedopen -a Lanesleaves a cask in/Applicationsand nothing running, and every later check then fails for a reason that has nothing to do with the install.
Anti-patterns
- Do not go looking for a
.dmg, a GitHub release asset, or a direct download. Homebrew is the install path and the update path. - Do not register the MCP by hand when
/lanes:setup-mcpis available, and never rename an entry that is already there. - Do not run
/lanes:setup-mcpbefore the app is open. The probe will fail and you will debug an installation that is fine. - Do not create issues or start sessions as a victory lap. That is the
lanes-sessionsskill, and it is the user's call whether to go there next.
Then what
lanes-sessions, in this plugin, is the board and the sessions: creating issues, launching Claude Code against them, reading terminals.github-lanes-bridgeandlinear-lanes-bridgepull tickets in from either tracker. They ship in a separate plugin now, so install it first:/plugin install lanes-bridges@lanes.- Quickstart is the same path written for a person.
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-mcpslash command (shipped alongside this skill) or, if they have raw skills only, run:
Then restart Claude Code so the new MCP loads. Lanes itself must also be running (the desktop app must be open).claude mcp add --transport sse lanes-desktop http://localhost:5353/sse --scope user
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:
| Variable | Meaning |
|---|---|
LANES_TERMINAL | 1 when Lanes spawned this shell. Unset means this section does not apply. |
LANES_SESSION | The issue ID you are working on. This is what to pass as id / issueId. |
LANES_SESSION_UUID | This session's Lanes ref, for the session param. |
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
| Group | Tool | Purpose |
|---|---|---|
| Issues | lanes_list_issues | Filter by step / tags (any-match) / componentId / search. Defaults are scoped: at most 20, active project only, every Done status excluded. Pass limit (no upper bound), allProjects: true, or includeDone: true to widen. Filtering by a Done status includes it. Returns an envelope { issues, appliedFilters, truncated, totalAvailable }, so check truncated before concluding a search found nothing. |
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_list_worktrees | Every worktree Lanes can see: name, path, branch, and the projectPath it came from. Optional projectPath narrows it to one repository. Use it to find the path to link, or to check whether a branch already has a worktree. | |
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.sessionsarray lists each candidate as{ sessionUuid, slot, name, runtimeStatus, cli, cliSessionId, createdAt }. Pick one (ask the user if not obvious) and retry withsessionset 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. Readlanes_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_statusreturns[]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_componentsfirst and resolve names → UUIDs locally. Passing a plain name like"bug"will not match anything. stepis a status id, and the user defines the statuses. Each tool'sstepenum comes from the user's Settings > Workflows, and its description names every option asid (Label, category). The built-in ids arebacklog,planning,implementation,review,miscanddone. The user can rename them, switch them off, and add their own, such astodo. 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. Uselanes_move_issueif 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_issuesleaves every Done status out by default, not onlydone. A new issue with nosteplands inbacklog, 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_sessioncreate a fresh git worktree, the issue must already haveworktreeStrategy: "create"ANDworktreeName: "<branch>". Set them vialanes_create_issueorlanes_update_issuebefore callingstart_session. To attach an issue to a worktree that already exists (one you made yourself, mid-session), setbranchinstead — see "Link a worktree you created yourself". prompthas 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.
flagsarray shape forlanes_start_session:[ { "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"becomesENV=valueprepended to the command.planMode: trueonly takes effect whencli: "claude". It maps to--permission-mode plan.lanes_list_issuesfilter combination: filters AND together, excepttags, which is any-match (issue must have ≥1 of the listed UUIDs).update_issueto clear a field requires explicitly passingnull(or[]fortags/dependencies). Omitting a key leaves it untouched.
Common workflows
Create-and-launch a single issue
1. lanes_list_components // pick the right componentId
2. lanes_create_issue {
title, description, cwd,
componentId,
worktreeStrategy: "create",
worktreeName: "feat/short-slug"
}
3. lanes_start_session { issueId, planMode: true } // or omit planMode for implement-mode
// → returns the new slot + sessionUuid
Step 3 already tells you the slot it started; there is no separate confirmation step. If you do want to double-check, read lanes_get_session_status { issueId } and look for that slot — do not call lanes_start_session again.
Batch-launch the backlog in plan mode
1. lanes_list_issues { step: "backlog" }
2. for each issue:
lanes_start_session {
issueId,
planMode: true,
flags: [{ flag: "dangerously-skip-permissions", value: "", kind: "flag" }]
}
Then ask the user to review the resulting plans; promote each issue to implementation once plans are approved.
Investigate a stuck session
1. lanes_get_session_status { issueId } // is the PTY actually live?
2. lanes_read_terminal { issueId, lines: 500 }
3. lanes_get_issue_history { id: issueId, limit: 50 } // structured Claude transcript
4. lanes_get_session_stats { id: issueId } // tokens/tool calls/duration
Multi-session issues: step 1 returns the candidate array — pick one and pass session to step 2 (and cliSessionId to steps 3/4) to scope subsequent reads.
If a Claude session has stopped and you want to pick up where it left off, call lanes_resume_session { issueId, session? } — see the next workflow.
Resume a stopped Claude session
1. lanes_get_session_status { issueId } // see what's there
2. lanes_resume_session { issueId, session: "<slot|name|uuid>" } // session optional if only one
3. lanes_read_terminal { issueId, session: "<same>" } // verify it's live again
Only works for cli: "claude" sessions that recorded a cliSessionId. Codex/shell sessions can't be resumed — use lanes_start_session to launch a fresh one.
Mark complete
1. lanes_get_issue_changes { id } // confirm there is real work to land
2. lanes_stop_session { issueId, session? } // pass session on multi-session issues
3. lanes_move_issue { id, step: "done" }
Moving an issue over MCP never stops its sessions, whatever the user's Stop sessions on Done setting says, so step 2 is yours to do. If done is switched off, step 3 takes the active Done status from the enum instead.
Anti-patterns
- ❌ Calling
lanes_create_issuewithtags: ["bug"]. Tags must be label UUIDs fromlanes_list_labels. - ❌ Guessing a
stepfrom what boards usually have.todoorin-progressexist only if this user added them, and a status can be renamed without its id changing. Read thestepenum in the tool's schema. - ❌ Calling
lanes_start_sessionwithworktreeStrategy: "create"in the same call — the field lives on the issue, not the session call. Set it viacreate_issue/update_issuefirst. - ❌ Polling
lanes_read_terminalin a tight loop. Read once, summarise, ask the user before re-polling. - ❌ Confusing
id(issue endpoints) withissueId(session endpoints). They refer to the same thing but live under different keys. - ❌ Using
lanes_update_issueto "clear" a field by sending"". Empty string is a value; passnullto clear. - ❌ Starting many sessions without
componentIdorcwdset. Sessions need a working directory; otherwise the PTY spawns wherever the Lanes app was launched from. - ❌ Passing
--resume,--continue,--session-id, or--fork-sessiontolanes_start_session. These are rejected — uselanes_resume_sessionto re-attach a stopped Claude session. - ❌ Treating the ambiguity response from
lanes_stop_session/lanes_resume_session/lanes_delete_session/lanes_read_terminalas an error. It's a normal MCP success result with_meta.sessions— pick a candidate and retry withsessionset. - ❌ Confusing
cliSessionIdwithsession.cliSessionIdis the CLI's own resume token (only consumed bylanes_get_issue_historyandlanes_get_session_stats);sessionis the Lanes ref (UUID / slot / name) used by stop / resume / delete / read_terminal. - ❌ Re-calling
lanes_start_sessionbecause you could not find the session you just started. The launch is asynchronous and every call spawns another session. This is the single worst failure mode with these tools — it silently produces a pile of duplicate sessions on one issue. Readlanes_get_session_status { issueId }instead, and wait if it comes back empty. - ❌ Treating
"No sessions exist for issue N yet"as a cue to start a session. Inside the launch window it is the expected answer for a session that is starting normally. - ❌ Using
lanes_get_issueto check whether a session started. It does not return sessions —lanes_get_session_statusdoes. - ❌ Looking for only one of
status/runtimeStatuson a session entry and concluding the session is broken when it's absent. Both keys are present and carry the same value. - ❌ Creating a git worktree while running inside a Lanes session and never linking it. The issue keeps pointing at the main checkout, so
lanes_get_issue_changesand the board's Changes tab both show an empty diff and your work looks like it never happened. Calllanes_update_issue { id: $LANES_SESSION, branch: "<branch>" }right aftergit worktree add, then re-read the issue to confirmworktreeStrategyis"select".
Commands 1
Set up the Lanes MCP server in every installed agent client. Run the section for each client detected; skip sections for clients that aren't installed. Both clients can coexist, and this command is idempotent.
1. Detect installed clients
- Claude Code:
command -v claude(non-empty path means installed). - Cursor:
test -d ~/.cursor || test -d /Applications/Cursor.app(either is sufficient).
If neither is installed, stop and tell the user.
2. Claude Code
Skip if Claude Code wasn't detected.
-
Check current state. Run
claude mcp listand look for any of three names, since the local server has shipped under all of them:lanes-desktop— the current name.lanes-local— the previous name. Still fully supported; leave it be.laneswhose URL ishttp://localhost:5353/sse— the original name. Still supported; leave it be.
Any of the three means the local server is already registered, so skip to step 3 and don't add a duplicate. Never rename an existing entry here — Settings → Integrations → Lanes MCP has a button for that, and it carries the user's tool permissions across. (A
lanesentry pointing somewhere else is the separate remote Lanes Forms server; leave it alone.) -
If none are present, register it:
claude mcp add --transport sse lanes-desktop http://localhost:5353/sse --scope user--scope userwrites to~/.claude.jsonso it applies across all your projects. -
Verify registration with
claude mcp list. Confirmlanes-desktop(or whichever older name you already had) shows up with the SSE URL.
3. Cursor
Skip if Cursor wasn't detected. Cursor has no cursor mcp add CLI, so we edit ~/.cursor/mcp.json directly (using jq to preserve any other mcpServers entries the user has).
- Check current state. Run:
Non-empty output means the local server is already registered, under the current namejq -r '(.mcpServers["lanes-desktop"] // .mcpServers["lanes-local"] // .mcpServers.lanes).url // empty | select(contains("5353"))' ~/.cursor/mcp.json 2>/dev/nulllanes-desktopor under an olderlanes-local/lanesstill pointing atlocalhost:5353. All three work — skip to step 3 and leave the entry exactly as it is. A barelanesentry pointing elsewhere is the separate remote Lanes Forms server; leave it alone and still addlanes-desktopbelow. - If none are present, register it. Preferred (uses
jq):
Fallback ifmkdir -p ~/.cursor [ -f ~/.cursor/mcp.json ] || echo '{}' > ~/.cursor/mcp.json tmp=$(mktemp) jq '.mcpServers["lanes-desktop"] = {"url": "http://localhost:5353/sse"}' \ ~/.cursor/mcp.json > "$tmp" && mv "$tmp" ~/.cursor/mcp.jsonjqisn't installed:python3 - <<'PY' import json, pathlib p = pathlib.Path.home() / '.cursor' / 'mcp.json' p.parent.mkdir(exist_ok=True) data = json.loads(p.read_text()) if p.exists() else {} servers = data.setdefault('mcpServers', {}) # Only add when no name is registered — never rename what is already there. if not any(k in servers for k in ('lanes-desktop', 'lanes-local')): servers.setdefault('lanes-desktop', {'url': 'http://localhost:5353/sse'}) p.write_text(json.dumps(data, indent=2) + '\n') PY - Verify by re-running the step 1 check. Non-empty output means the local server is registered under one of the supported names, whichever the user had.
4. Probe the endpoint
Run once, regardless of which clients were set up:
curl -sS -m 2 -o /dev/null -w "%{http_code}\n" http://localhost:5353/sse
200→ Lanes is up; the MCP is reachable.- Connection refused / timeout → Lanes isn't running. Tell the user to launch the Lanes desktop app (
open -a Laneson macOS), then re-run this command.
5. Report
One short paragraph covering: per-client registration status (Claude Code, Cursor), whether the endpoint is live, and the restart hint. Claude Code needs a fresh terminal so the new MCP loads; Cursor needs the IDE (or cursor-agent) restarted.
Notes:
- New installs register the local server as
lanes-desktop. It previously shipped aslanes-local, and before that as barelanes; both keep working indefinitely. - This command never renames an existing entry, in any client. A server's config name is the prefix on its tool names, so renaming it resets the user's approvals. That trade-off is theirs to make: Settings → Integrations → Lanes MCP has a per-client button that does the rename and carries the Claude Code tool grants across (Codex's are nested under the server entry and move with it anyway). Point the user there if they ask. Cursor has no such button — there, renaming means removing and re-adding by hand.
- Don't overwrite an existing MCP entry without asking. The user may have customised the URL, or may be deliberately referring to the server by an older name.
- The SSE endpoint is local-only (no auth, never leaves the machine). Don't expose
localhost:5353over the network. - If the user is on a non-default port (set in Settings → Integrations → Lanes MCP), they should pass that URL instead, in both clients.
Sponsors
Details
- Marketplace
- lanes-sh/app
- Source
- plugins/lanes-desktop
- Category
- Community