Repository navigation
Start a Claude on a Linear issue from another app: POST /api/linear/start and POST /api/select - #61
Merged
Merged
Conversation
Another local app (todo-hub) starts Claude on a Linear issue's branch with a prompt, the way reviews prepare does, then asks the UI to select the pane. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… a prompt and links the issue Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ee is 502; tests fail instead of hang Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…fresh Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…n the unit of at and a second request Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… spec matches the code Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…computing Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…, not "focused" The route reports that pane; it does not focus it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… open, the spawn_claude tool, prepare and Linear start use it The four copies of the pane listing before place_in_rail are now one helper. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Linear start shared as two copies Each route keeps one BranchSpawns and its own owner step, worktree step, window fields and answer. Prepare's unresolved session is now 502, as Linear start's: the worktree exists by then, so git failed in periscope. The queue shows any error's detail and does not branch on 409. Prepare's pid-less branch was dead (stamp_new_window always mints a pid) and is gone, with its test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and the link after a placement failure Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The routes are plain local HTTP; nothing in periscope depends on a particular caller. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rompt fails to load is SpawnFailed As an argument, tmux read a leading `-` as flags and refused text over ~16 KB, and tmux() dropped the error: the Enter then submitted an empty composer. spawn_claude_with_prompt kills its new window before it raises, so the routes answer 502 with no Claude left behind; /api/send answers 500 and sends no keys. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ing, attached or not The route only reports the pane, and /api/select needs only a live pane, so a Claude started by hand or spawned a moment ago is reported, not given a twin in the same worktree. The match uses the realpath'd repo against repo_key, so a same-named repo elsewhere does not count. reviews.claude_on_branch holds the agent-and-branch match; owner_for adds prepare's channel and label filter to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… branch) Each route had its own in-flight set and recent-spawn record, keyed on two repo forms, so a prepare and a Linear start on one branch within ~20 s could start two Claudes. branch_spawn now holds one guard as module state, and refuse_recent_spawn(key, owner) replaces the forget/refuse pair: only a channel-attached owner ends the record, because Linear start counts its own Claude before it attaches. The in-flight 409 reads "a Claude is already starting on this branch"; the placement log names the worktree. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…r two ticks old After an idle stretch the blob from before it stayed until the first new build ended, so a Linear start in that second read hours-old windows. _broadcast records when it sent the blob. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed session and pid when anchored, none in same mode Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ores; a test pins a request whose pane shows one state late Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…anch, the shared guard, what 400 means, the stdin load, the full Changes list Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…inear start names it claude, not owner An owner is a channel-attached Claude (reviews.owner_for). Linear start passes any Claude on the branch, so the parameter and its variable are named claude, and the function name says that it also clears the record. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lls its window and is 502 A subprocess.TimeoutExpired escaped spawn_claude_with_prompt's handler: the window stayed with an empty composer and the route answered a bare 500. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…mux socket; the fork path logs a failed load deliver_input inlined its own load-buffer with bare tmux and no error check. Its send-keys and paste-buffer now use _tmux_argv too, so the paste reads the server the load wrote. tmux_input._fork_fallback logs the RuntimeError, because a raise would end /ws/pane's drain task. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ast gap between broadcasts, at least two ticks The limit was two ticks of wall time, but a broadcast lands every build plus a tick, and a loaded build takes 3-13 s, so most Linear starts there ran a second build_state. The subscriber condition is gone: with no tab the hub stops, so the blob ages out by itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, so a retry right after a 502 spawns Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s, and 409 only before that Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n a failure or timeout, so the fork path logs them; a spawn logs a cleanup kill that fails or times out and still raises SpawnFailed Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…swers 500 when the load fails, so every load goes through load_buffer Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
/api/paste-image answers a failure as FastAPI's {detail}; read it the way apiCall does.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pi/paste-image's paste go through _tmux_checked tmux() drops a non-zero exit and lets TimeoutExpired out, so a paste into a window that closed answered ok and nothing reached the pane. Now a paste or send-keys that tmux refuses or times out on makes the spawn kill its window and raise SpawnFailed, and makes /api/send and /api/paste-image answer 500 with the tmux error. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ked and logs its RuntimeError; channels.py drops its subprocess import The kill caught _tmux_mutate's TimeoutExpired itself and rebuilt _tmux_checked's "timed out after N s" text. The kill no longer kicks the state hub: the next steady tick, a second later, drops the window. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd drops input that tmux refused or timed out on Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… -p; the spawn, /api/send and /api/paste-image use it, deliver_input keeps its raw paste Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd the cleanup-kill warning says the Claude stays after a failed prompt Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Another app on this Mac can now start work on a Linear issue in one call: periscope makes the worktree for the issue's branch, starts Claude with a prompt and links the issue to the card. A second call asks the dashboard to select that pane. Both are plain local HTTP routes, like
/api/open; periscope depends on no particular caller, and nothing changes when no app uses them. The PR also moves the spawn path that prepare and the new route share into one module.POST /api/linear/start(routes/linear.py){repo, branch, ticket, title, prompt}.repois a main checkout, asGET /api/open/cataloglists it.worktree_spawn.spawn_worktree), starts Claude with the prompt in the repo's default track, stampslinked_linearandlinked_linear_title, and places the pane in the rail. It answers{mode: "spawned", pid, path, reused}.{mode: "existing", pid}. Any Claude window in the same repo (repo_key, the real path) counts, with or without a channel, through the newreviews.claude_on_branch. That session can be busy, so the route never pastes into it.state_hub.current_windows()returns the last blob while it is younger than twice the hub's last gap between broadcasts (at least two ticks); otherwise it builds a new one. The hub computes nothing without a subscriber, and closing the app's window leaves the server running, so the last blob ages out.existingwith the first pid once the new Claude shows in the windows (a tick or two), and 409 only before that.spawn_worktreerefuses the request: a bad branch, a path that is not a git repo, or a failedgit worktree add(as/api/opendoes). 502 for a git failure after the worktree exists, or for a failed spawn, including a prompt that tmux could not load.POST /api/select{pid}puts{pid, at}in every state blob asselect, and kicks the hub. Each tab applies it once, while it is less than 30 s old and the pane is live, throughalertFeed.selectPane(static/src/select.js).open -b com.tom.periscope.app.One spawn path for prepare and Linear start
branch_spawnholds one guard that both routes share, keyed on (repo label, branch): the in-flight guard, the 60 s recent-spawn guard, and the spawn (session, Claude, rail).refuse_or_clear_recent_spawn(key, claude)refuses a spawn when no Claude is on the branch, and clears the record only for a channel-attached Claude, so Linear start seeing its own unattached Claude does not let a prepare start a twin. Each route keeps its own owner step, worktree step, window fields and answer.open_ops.place_session_in_railreplaces three copies of "the session's stamped panes, else the pid": the ⌘K open, thespawn_claudetool and prepare. Linear start uses it too.tmux.load_bufferloads text over stdin (load-buffer -). The oldset-bufferread a prompt that starts with-as flags and refused one over ~16 KB, and the error was dropped, so Claude got an empty input.tmux.bracketed_paste(target, text)loads a buffer of its own and pastes it with-d -p; the spawn,/api/sendand/api/paste-imageuse it, so load and paste cannot drift apart.deliver_inputpastes raw terminal input without-p, so it callsload_bufferitself. Each step (load, paste, and thesend-keysthat submits) goes throughtmux._tmux_checked, which raises oneRuntimeErrorwhen tmux refuses it or times out. So a failed load, paste or Enter isSpawnFailedin a spawn (the new window is killed; a kill that fails is logged), a 500 in/api/sendand/api/paste-image, or a logged warning in the typing path. Every user of/api/send's_send_to_targetnow reports a refused key as a failure:/api/send-bulkshowsok: falsefor that target, and the permission and reply buttons and the model/effort switch answer 500. A failed image paste prints the route's message in the terminal.ReviewsQueue.jsx, showsdetailfor any status.if not spawned["pid"]branch is gone.stamp_new_windowalways mints a pid.state_hub.last_windows()replaces the private_windows()inroutes/reviews.py.time.monotonicany more.Assumptions to challenge
git rev-parsefailed has arepo_keywithout realpath, so Linear start does not count it.spawn_worktreechecks only local branches. A branch that is only on origin (for example after cleanup deleted the local one) gets a new fork from the default branch. This is existing behavior, but Linear's branch names make the case more likely.claudecommand line and its consent Enter still run through plaintmux(), so a timeout there escapesSpawnFailedas a bare 500._tmux_mutatecan still raiseTimeoutExpiredfor its other callers. Both are older than this PR.Test plan
bin/checkuv run pytest -q: 2254 pass. New:tests/routes/test_linear.py, the select andcurrent_windowstests (the freshness rule),place_session_in_rail, prepare's 502,tmux.load_bufferandbracketed_paste(a leading-, 20 KB, a failure and a timeout;deliver_input's paste and keys; each spawn step (load, paste, Enter) refused and timed out; the spawn's cleanup kill;/api/send's paste and keys;/api/paste-image), the shared guard, a retry after a failed spawn, and the owner test (unattached Claude, same-name repo, trailing slash).npm test: 1484 pass. New:select.test.js, with a request whose pane shows one state late.static/distrebuilt and fresh-, made the worktree. Claude got the prompt intact and answered it, and the card showed the Linear link.existingwith the same pid. The Claude there had no attached channel (on the dev server it attaches to prod), so this checks the new owner test./api/selectanswered{ok: true}. An earlier run, before the review fixes, showed the dev UI selecting the pane and a dead pid changing nothing.Spec:
docs/superpowers/specs/2026-11-15-linear-start-design.md. Plan:docs/superpowers/plans/2026-11-15-linear-start.md(its code blocks predate the review fixes).🤖 Generated with Claude Code