Pull requests that know their session
Every PR carries the sessions that made it, and a review, a red check or a conflict wakes the agent that owns it.
When an agent wrote the change, the reasoning lives in a transcript, not the PR description. And once the PR is open, the agent is gone: a red check or a request for changes waits for a human to open a new session, explain the context again and ask for a fix. In codecast every pull request page carries the sessions that made it, and one of them can be the PR's shepherd: the session that owns it until it merges, woken whenever GitHub has news it can act on.
The PR page
The page reads like a status report: title and branch, the Shepherd line, linked sessions and tasks, then Checks, Review, Merge, Open comments and Diff, each a link to where you would go next. Four tabs (Conversation, Files, Commits, Checks) sit on the keys 1 to 4; r opens your review, n and p walk open threads. Whatever you do here (review, merge, close, request a reviewer) goes to GitHub, and the page updates from GitHub's answer, so the two never disagree.
The PR also follows its shepherd: the session's inbox card and the bar above its composer show a chip, #482 and one word for what it waits on, green when nothing blocks it, yellow or orange when it waits on a person or CI, red when something broke.
How a PR finds its sessions
Sessions attach on their own, three ways:
- Sessions on the branch. Everything that worked on the head branch is linked, and the most recent is proposed as shepherd, paused until you turn it on.
- A trailer on every agent commit. Each agent commit names its session, so the Commits tab shows a session pill on every commit.
- Task ids in the text. A task id like
ct-4102in the title, body or branch links the task.
The shepherd
With no shepherd yet, the header offers Assign a shepherd session. Once bound, the line shows the session, where things stand ("fixing failed checks", "ready to merge") and a switch reading Wakes on changes or Paused; hover for when it last woke and why. Usually the agent sets this up itself: it opens the PR with a description linking its session, binds itself, and goes quiet until there is news it can act on:
| Event | Effect |
|---|---|
| A check fails | wakes |
| A person requests changes, or leaves a review with a body | wakes |
| A person comments on a line | wakes |
| The branch no longer merges cleanly | wakes |
| Branch falls behind its base; checks go green; new commits; a review is requested | recorded, no wake |
| Anything from a bot, or from the PR's own author | ignored |
Each wake is a new turn in the session, with a briefing rebuilt from where the PR stands now, worst news first. A busy session is not interrupted; reasons collect until it is free. The briefing says to fix, answer and push in one pass, reply on every thread, not rebase just because the branch is behind, and not to merge unless a human asked. A merge or close retires the shepherd.
Held notes, sent as one review
In the Files tab a note on a line can Post now or Start a review, which holds it. Held notes are dashed and yours alone: nothing reaches GitHub and no session wakes. The Review button counts them (Review · 2). Press r and Finish your review lists them, takes a summary and a verdict (Comment, Approve, Request changes), and sends one GitHub review under your account, since a verdict never goes out as the app. The shepherd gets the whole review as one message, so it wakes once with every note in hand.
Send to session is the other way out: the notes go to the shepherd (or a linked session you pick), nothing goes to GitHub, and the notes stay held, so the agent can fix first and you send or Discard the batch after. On your own PR the verdicts are disabled, as GitHub takes only a comment from you. An answered note links to the agent's reply.



