lanes-sh avatar

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@lanes

Run it inside Claude Code after adding the marketplace with /plugin marketplace add lanes-sh/app.

Contents

Discovered from source

Skills 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.

CheckCommandA failure means
Platformuname -sAnything but Darwin: stop. Lanes Desktop is macOS only today. Point at the docs and offer Lanes Link instead, which runs anywhere.
macOS versionsw_vers -productVersionBelow 13 (Ventura): stop. There is no build for it.
Already installedtest -d /Applications/Lanes.app && echo presentPresent: skip step 1. Go to "Update and repair" if they asked to update, or straight to step 2.
Homebrewcommand -v brewMissing: 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

SituationWhat to run
Updatebrew 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 installbrew reinstall --cask lanes-sh/lanes/lanes
Uninstallbrew uninstall --cask lanes-sh/lanes/lanes. Board data lives outside the app and survives.
Confirm what is installedbrew list --cask --versions lanes
App will not openCheck sw_vers -productVersion against Ventura first, then reinstall. Do not delete /Applications/Lanes.app by hand; Homebrew loses track of it.

Critical gotchas

  • A 200 from 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 first lanes_list_issues will 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 5353 refuses while the app is plainly running, ask them what the Integrations panel says before debugging anything else.
  • A lanes entry in an MCP config that does not point at localhost:5353 is a different server. That is the remote Lanes Forms one. Leave it alone.
  • brew install without the chained open -a Lanes leaves a cask in /Applications and 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-mcp is available, and never rename an entry that is already there.
  • Do not run /lanes:setup-mcp before 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-sessions skill, 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-bridge and linear-lanes-bridge pull 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-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:

VariableMeaning
LANES_TERMINAL1 when Lanes spawned this shell. Unset means this section does not apply.
LANES_SESSIONThe issue ID you are working on. This is what to pass as id / issueId.
LANES_SESSION_UUIDThis 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

GroupToolPurpose
Issueslanes_list_issuesFilter 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_issueFull details by id. Does not include sessions.
lanes_create_issueRequired: title.
lanes_update_issuePatch by id; pass null to clear nullable fields.
lanes_delete_issueBy id. Permanent.
lanes_move_issueShorthand for update_issue with only step.
Sessionslanes_start_sessionRequired: issueId. Spawns Claude Code (default), Codex, or shell. Always adds a new session; returns its slot + UUID.
lanes_stop_sessionStop a session for issueId. Optional session (UUID/slot/name) to disambiguate when >1.
lanes_resume_sessionRe-attach Claude to a stopped session. Claude-only. Optional session.
lanes_delete_sessionPermanently delete a session (stops it first if running). Optional session.
lanes_get_session_statusWith issueId: bare array of every session for that issue (status under both status and runtimeStatus). Without: envelope { sessions, appliedFilters, truncated, totalAvailable } capped at 20.
Historylanes_get_issue_changesgit diff for the issue's cwd, by id.
lanes_get_issue_historyPaginated Claude conversation history, by id. Use cliSessionId to pick when an issue has multiple Claude sessions.
lanes_read_terminalLast lines (default 200, max 2000) of PTY scrollback. Optional session.
lanes_get_session_statsTokens, model breakdown, tool calls, duration, by id. Use cliSessionId to pick when an issue has multiple Claude sessions.
Metadatalanes_list_labelsUUIDs, names, colors. Call before assigning tags.
lanes_list_componentsUUIDs, names, project IDs. Call before setting componentId.
lanes_list_worktreesEvery 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_worktreeRemove 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 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:
    [
      { "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

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_issue with tags: ["bug"]. Tags must be label UUIDs from lanes_list_labels.
  • ❌ Guessing a step from what boards usually have. todo or in-progress exist only if this user added them, and a status can be renamed without its id changing. Read the step enum in the tool's schema.
  • ❌ Calling lanes_start_session with worktreeStrategy: "create" in the same call — the field lives on the issue, not the session call. Set it via create_issue / update_issue first.
  • ❌ Polling lanes_read_terminal in a tight loop. Read once, summarise, ask the user before re-polling.
  • ❌ Confusing id (issue endpoints) with issueId (session endpoints). They refer to the same thing but live under different keys.
  • ❌ Using lanes_update_issue to "clear" a field by sending "". Empty string is a value; pass null to clear.
  • ❌ Starting many sessions without componentId or cwd set. Sessions need a working directory; otherwise the PTY spawns wherever the Lanes app was launched from.
  • ❌ Passing --resume, --continue, --session-id, or --fork-session to lanes_start_session. These are rejected — use lanes_resume_session to re-attach a stopped Claude session.
  • ❌ Treating the ambiguity response from lanes_stop_session / lanes_resume_session / lanes_delete_session / lanes_read_terminal as an error. It's a normal MCP success result with _meta.sessions — pick a candidate and retry with session set.
  • ❌ Confusing cliSessionId with session. cliSessionId is the CLI's own resume token (only consumed by lanes_get_issue_history and lanes_get_session_stats); session is the Lanes ref (UUID / slot / name) used by stop / resume / delete / read_terminal.
  • ❌ Re-calling lanes_start_session because 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. Read lanes_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_issue to check whether a session started. It does not return sessions — lanes_get_session_status does.
  • ❌ Looking for only one of status / runtimeStatus on 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_changes and the board's Changes tab both show an empty diff and your work looks like it never happened. Call lanes_update_issue { id: $LANES_SESSION, branch: "<branch>" } right after git worktree add, then re-read the issue to confirm worktreeStrategy is "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.

  1. Check current state. Run claude mcp list and 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.
    • lanes whose URL is http://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 lanes entry pointing somewhere else is the separate remote Lanes Forms server; leave it alone.)

  2. If none are present, register it:

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

    --scope user writes to ~/.claude.json so it applies across all your projects.

  3. Verify registration with claude mcp list. Confirm lanes-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).

  1. Check current state. Run:
    jq -r '(.mcpServers["lanes-desktop"] // .mcpServers["lanes-local"] // .mcpServers.lanes).url // empty | select(contains("5353"))' ~/.cursor/mcp.json 2>/dev/null
    
    Non-empty output means the local server is already registered, under the current name lanes-desktop or under an older lanes-local / lanes still pointing at localhost:5353. All three work — skip to step 3 and leave the entry exactly as it is. A bare lanes entry pointing elsewhere is the separate remote Lanes Forms server; leave it alone and still add lanes-desktop below.
  2. If none are present, register it. Preferred (uses jq):
    mkdir -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.json
    
    Fallback if jq isn'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
    
  3. 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 Lanes on 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 as lanes-local, and before that as bare lanes; 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:5353 over 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

More from lanes-sh/app

All 5