Skip to content

Start a Claude on a Linear issue from another app: POST /api/linear/start and POST /api/select - #61

Merged
tdody merged 40 commits into
mainfrom
thibaultdody/start-in-periscope
Nov 16, 2026
Merged

tdody merged 40 commits into
mainfrom
thibaultdody/start-in-periscope

Conversation

@tdody

@tdody tdody commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

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)

  • It takes {repo, branch, ticket, title, prompt}. repo is a main checkout, as GET /api/open/catalog lists it.
  • It makes or reuses the worktree (worktree_spawn.spawn_worktree), starts Claude with the prompt in the repo's default track, stamps linked_linear and linked_linear_title, and places the pane in the rail. It answers {mode: "spawned", pid, path, reused}.
  • A Claude already on the branch is reported, not prompted: {mode: "existing", pid}. Any Claude window in the same repo (repo_key, the real path) counts, with or without a channel, through the new reviews.claude_on_branch. That session can be busy, so the route never pastes into it.
  • It reads fresh windows. 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.
  • A second start answers existing with the first pid once the new Claude shows in the windows (a tick or two), and 409 only before that.
  • Errors: 409 for a start in flight, or for a spawn less than 60 s old whose Claude does not show yet. 400 when spawn_worktree refuses the request: a bad branch, a path that is not a git repo, or a failed git worktree add (as /api/open does). 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 as select, and kicks the hub. Each tab applies it once, while it is less than 30 s old and the pane is live, through alertFeed.selectPane (static/src/select.js).
  • Bringing periscope to the front is the caller's job, for example open -b com.tom.periscope.app.

One spawn path for prepare and Linear start

  • branch_spawn holds 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_rail replaces three copies of "the session's stamped panes, else the pid": the ⌘K open, the spawn_claude tool and prepare. Linear start uses it too.
  • tmux.load_buffer loads text over stdin (load-buffer -). The old set-buffer read 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/send and /api/paste-image use it, so load and paste cannot drift apart. deliver_input pastes raw terminal input without -p, so it calls load_buffer itself. Each step (load, paste, and the send-keys that submits) goes through tmux._tmux_checked, which raises one RuntimeError when tmux refuses it or times out. So a failed load, paste or Enter is SpawnFailed in a spawn (the new window is killed; a kill that fails is logged), a 500 in /api/send and /api/paste-image, or a logged warning in the typing path. Every user of /api/send's _send_to_target now reports a refused key as a failure: /api/send-bulk shows ok: false for 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.
  • Two changes in prepare:
    • A session that git cannot read is now 502, not 409. Its only caller, ReviewsQueue.jsx, shows detail for any status.
    • The if not spawned["pid"] branch is gone. stamp_new_window always mints a pid.
  • Window fields are now written after the rail placement, as the ⌘K PR open already does.
  • state_hub.last_windows() replaces the private _windows() in routes/reviews.py.
  • Tests: the concurrent-start tests fail instead of hang, and no test patches the global time.monotonic any more.

Assumptions to challenge

  • Any Claude window on the branch in the same repo counts for Linear start. Prepare still needs a channel-attached owner, because it delivers the prompt.
  • The shared guard keys on the repo label. Two repos with the same folder name and the same branch share it: a start in one can get a 409 for up to 60 s after a spawn in the other.
  • A window whose git rev-parse failed has a repo_key without realpath, so Linear start does not count it.
  • spawn_worktree checks 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.
  • Only the last select request matters. Two quick requests keep the last one.
  • The spawn's claude command line and its consent Enter still run through plain tmux(), so a timeout there escapes SpawnFailed as a bare 500. _tmux_mutate can still raise TimeoutExpired for its other callers. Both are older than this PR.
  • A start can take about 130 s on a large repo: fetch 30 s, worktree add 30 s, reset 60 s, then Claude's screen. Periscope keeps going after a caller stops waiting.

Test plan

  • bin/check
  • uv run pytest -q: 2254 pass. New: tests/routes/test_linear.py, the select and current_windows tests (the freshness rule), place_session_in_rail, prepare's 502, tmux.load_buffer and bracketed_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/dist rebuilt and fresh
  • Dev backend on :17375, at the final head:
    • A real start on a throwaway branch, with a prompt that starts with -, made the worktree. Claude got the prompt intact and answered it, and the card showed the Linear link.
    • A second start answered existing with 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/select answered {ok: true}. An earlier run, before the review fixes, showed the dev UI selecting the pane and a dead pid changing nothing.
    • I removed the window, the worktree and the branch afterwards.
  • CI

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

tdody and others added 16 commits November 15, 2026 21:08
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>
tdody and others added 13 commits November 16, 2026 10:15
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>
tdody and others added 11 commits November 16, 2026 11:52
…, 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>
@tdody
tdody requested a review from tomplex November 16, 2026 18:39
@tdody
tdody merged commit 65e328a into main Nov 16, 2026
2 checks passed
@tdody
tdody deleted the thibaultdody/start-in-periscope branch November 16, 2026 19:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant