GitHub

The GitHub view shows every repository your GitHub account can reach and every open pull request and issue across them, plus the latest GitHub Actions runs, on desktop and on your phone. You can read a pull request (description, checks and their logs, conversation, changed files and diff), approve it, request changes, comment, merge it, close it, re-run its failed checks, and hand it to an agent in one tap. You can do the same for an issue (comment, close, reopen, assign yourself, work on it with an agent) and for a workflow run (read job logs, re-run, cancel). The agent hand-off is the part a browser tab cannot do: Clusto checks the pull request out, or creates an issue worktree, in your local project and opens a chat there.

Open it from GitHub in the left nav (route /github). The entry is hidden in the Simple navigation profile (see Appearance), and it shows a badge with the number of pull requests waiting for your review. It is free on every plan.

Early access

The GitHub view ships behind the github.view release flag, which is off by default. Turn it on in Settings -> Labs (the Early access switch, or the flag itself). The flag is cluster-shared, so one change covers every device connected to the cluster. See Feature Flags.

Set up

Everything that talks to GitHub runs on one host node that holds your token, so the view works the same from a phone as from a desktop, and the token never leaves that node. Configure it once in Settings -> GitHub; the account list is shared across the cluster.

1. Open Settings -> GitHub and add an account.
2. Fill in the fields:

Field	Meaning
Name	A label shown in the app.
Host node	The node that polls GitHub and holds the token (see Security).
Poll interval	Seconds between polls. Default 60, allowed 15 to 3600.
Default merge method	Preselected in the merge dialog: merge commit, squash (default) or rebase.
GitHub token	Paste a personal access token. It is saved to the host node only.

3. Instead of pasting a token you can press Import from gh CLI. The host node runs gh auth token for the OS user you pick (default: the node's default session user), stores the result like a pasted token, and never logs it. The gh CLI must be installed and signed in (gh auth login) on the host node.

Clusto asks GitHub which account the token belongs to when you save it and shows authenticates as <login>. That login decides what "mine" means in the view: the Needs my review, Mine and Assigned buckets and the notifications all key off it.

If you add more than one account, the view shows an account picker.

Use your Clusto account's GitHub sign-in

Instead of pasting a token you can reuse the GitHub account linked to your Clusto account. This works on every plan.

1. Sign in to your Clusto account in the app (Settings -> Account).
2. In Settings -> GitHub, press Use my Clusto GitHub sign-in.
3. The first time, GitHub is not yet linked with repository access, so Clusto opens clusto.app/account/connect-github in your browser. Sign in there if asked, press Connect GitHub, and grant the repo and read:org scopes. Then return to the app and press Use my Clusto GitHub sign-in again.
4. Clusto asks your Clusto account for the GitHub token and sends it write-only to the host node, exactly like a pasted token. This device never keeps it.

Things to know:

• The GitHub account must have the same email as your Clusto account. If it does not, the link fails; use a personal access token instead.
• Organisations that restrict third-party apps hide their repositories from the Clusto OAuth app until it is approved, and GitHub gives no error for it, so they are simply missing from the list. On GitHub open Settings > Applications > Authorized OAuth Apps > Clusto and press Grant next to the organisation (Request if you are not an owner), then refresh the GitHub view. The Missing an organisation's repositories? panel under the Repositories tab and in Settings > GitHub links straight there, as does the F1 command GitHub: grant organisation access. An imported gh token is the GitHub CLI app instead, which most organisations already allow.
• The token is stored encrypted in your Clusto account. See Account Cloud Sync. Unlinking GitHub or revoking the app on GitHub makes the next attempt ask you to connect again.
• This token is an OAuth token with the repo scope, so it covers every repository your GitHub account can reach, not one owner. The fine-grained permission list below applies to pasted tokens only.

Security: where the token lives

A GitHub token can write to every repository it covers, so whoever can read it can approve and merge as you. So:

• The host node must be a node your agents cannot read. Never use the machine the agents run on. The token is stored on the host node only. It is write-only: Clusto never sends it back to any client, never replicates it to other nodes and never logs it.

• Use a fine-grained personal access token with these repository permissions: Pull requests read and write, Contents read and write (write to merge, and for the factory to push), Checks read, Commit statuses read, Issues read and write (read to list issues, write to comment, close, reopen and assign), Actions read and write (read for job logs and runs, write for re-running and cancelling), and Metadata read. Leave Workflows off. Create token on GitHub, under the token field, opens GitHub's new-token page with these permissions, a name and a one-year expiry filled in; for a Factory account it also sets the resource owner to the account's organization. Review the page, pick the repositories, generate the token and paste it back. A fine-grained token covers one owner at a time (your user or one organisation); use a classic token with the repo scope if you want one token across several owners. A Factory account works only inside its organization; the software factory can also start items on its own from open issues that carry the repository's intake_label (GitHub only).

• Every action you take on a pull request, issue or workflow run is written to the host node's audit log (github_action) with the account, repository, number (the workflow run id for runs) and action. The action kinds are:

  Target	Kinds
  Pull request	approve, request_changes, comment, merge, close, reopen, mark_ready, rerun_failed_checks
  Issue	issue_comment, issue_close, issue_reopen, issue_assign_me
  Workflow run	run_rerun_failed, run_rerun, run_cancel

  Each entry also records whether the action succeeded (ok=true or ok=false).

If the host node is offline the view shows the last data it has, marks it read only, and hides the actions. No other node polls GitHub, because only the host has the token.

Overview

The Overview tab is the first tab and the one the view opens on. It is an at-a-glance dashboard of widgets. Every widget shows its first 5 items and has a View all button that opens the matching tab with the right filter already applied.

Widget	Shows	Default
Review requested	Pull requests waiting for your review.	On
Failing workflows	The latest finished run of each workflow and branch that failed. Pull request runs are left out, because they show on their pull requests.	On
My pull requests	Open pull requests you opened.	On
Issues assigned to me	Open issues assigned to you.	On
Running workflows	Workflow runs that are queued or running.	Off
Repositories	Your repositories.	Off

Press Customize to choose which widgets show, reorder them and set each one to half or full width (the width applies on wide screens; on a narrow window and on a phone the widgets stack). The layout is a synced preference: it is saved with your account settings and follows you to your other devices (see Cloud Sync). The palette has GitHub: customize the overview for the same dialog.

Pull requests

The Pull requests tab lists every open pull request. On desktop it is a list beside the detail pane (drag the divider to resize); on a phone a selected pull request replaces the list and Back returns to it. Pull request and issue buckets, filters, the runs filter and repository search are remembered on this device and reset when you switch GitHub account.

The bucket chips above the list show a count each:

Bucket	Shows
Needs my review	Pull requests where you are a requested reviewer.
Mine	Pull requests you wrote.
Assigned	Pull requests assigned to you.
Team	Pull requests written by, or waiting on a review from, your teammates. Team plan only; see below.
All	Every open pull request in the visible repositories.

The personal buckets need the token's login. Until the host has a token, the view falls back to All.

Team pull request board

The Team bucket appears only when you are signed in to a Clusto account that holds a seat on an active Team plan. It lists open pull requests that a teammate wrote or was asked to review, so a team sees what is moving across the whole group in one place.

• A teammate counts once they have linked GitHub to their Clusto account (see above). Until then the bucket says that teammates appear after they connect GitHub.
• Matching is by GitHub user id, which survives a login rename. Your own pull requests stay in Mine, not Team.
• Teammates see only your display name and GitHub user id; no email or token leaves the server. The list is fetched once per sign-in and needs no extra GitHub requests.
• Without a Team plan the bucket is hidden, and the other buckets work as before.

Narrow the list with the search box (title, repository, author, branch or number), the owner picker (organization or user), the repository picker (type in its search box to find a repository; it lists only the chosen owner's), the drafts picker (With drafts, Hide drafts, Drafts only) and the Failing toggle, which keeps only pull requests whose checks failed. Each row shows the repository and number, author, how recently it changed, a checks chip, a Draft badge, the review decision (Approved or Changes requested) and Review requested when it waits on you.

Pull request detail

Open a pull request to see:

• Description - the body, rendered as safe Markdown.
• Checks - every check run on the head commit with failed ones first, then running, then passed. For a GitHub Actions job, Log shows the tail of its log (the last 64 KiB; open GitHub for the rest). The external-link button opens the check on GitHub.
• Conversation - reviews and comments in time order, with each review's verdict. Empty plain reviews are left out.
• Files - the changed files with a per-file diff. Very large pull requests are cut to size caps and say so, with a link to the rest on GitHub.

The header shows the state (Open, Draft, Closed, Merged), the review decision and a Conflict badge when the branch cannot merge cleanly.

Actions

The action bar appears when the host is online and has a token. Every action asks for confirmation or a message first.

Action	What it does
Approve	Submits an approving review, with an optional note.
Request changes	Submits a review that blocks the merge. A message is required.
Comment	Posts a conversation comment (Markdown).
Merge	Merges with the method you pick (the account's default is preselected). Clusto sends the head commit it just read, so a push that lands while the dialog is open makes GitHub refuse instead of merging unreviewed code.
Ready for review	Takes a draft out of draft state. Only shown on drafts.
Re-run failed	Re-runs the failed jobs of every GitHub Actions workflow run behind a failed check. Only shown when an Actions job failed.
Close / Reopen	Closes an open pull request or reopens a closed one (not a merged one).

Review and comment bodies are limited to 64 KiB. If GitHub refuses an action (for example the branch is protected or has conflicts) the reason is shown and nothing changes.

Issues

The Issues tab lists the open issues of your visible repositories (pull requests are left out, although GitHub counts them as issues). Like the pull request list it is a list beside a detail pane on desktop and a stacked page on a phone.

Bucket	Shows
Assigned to me	Issues assigned to your login.
Mine	Issues you opened.
All	Every open issue in the visible repositories.

Narrow the list with the search box (title, label, author, repository or number) and the owner and repository pickers. A row shows the repository and number, title, labels, author, comment count, how recently it changed and an Assigned to me badge. Issues of repositories that are neither pinned, busy nor recently pushed are read less often; see Polling and rate limits.

Open an issue to read its description (safe Markdown) and its comments. The action bar offers:

Action	What it does
Work on with agent	Opens the agent dialog (below). Only on open issues.
Comment	Posts a comment (Markdown, up to 64 KiB).
Assign me	Adds your login to the assignees. Hidden when you are already assigned.
Close	Closes the issue after a confirmation.
Reopen	Reopens a closed issue.

Work on an issue with an agent

Pick a local project (linked projects first, as for pull requests). Clusto then, on that project's node:

1. Fetches the repository's default branch from origin, then creates a worktree worktrees/issue-<number> on branch wt/issue-<number>, starting at the freshly fetched origin/<default branch>. A failed fetch is an error and no worktree is created, so the agent never starts from a stale base. See Worktrees.
2. Starts a chat on that node with the worktree attached, using the agent and model of your last chat, and sends the brief as the first message: issue title, link, author, labels, the start of the description and the latest three comments.

The brief asks the agent to read the code first, make the change with tests and commit on the checked-out branch. It tells the agent not to push, open a pull request or comment on GitHub, so you review before anything leaves your machine. If worktrees/issue-<number> already exists the hand-off stops with git's error; remove or reuse that worktree first.

Actions

The Actions tab lists the latest GitHub Actions workflow runs (up to ten per repository) of your visible, active repositories, newest first. A row shows the state, workflow name, run title, repository, branch, event, who started it, how recently, the attempt number when it was re-run, and chips for the pull requests the run belongs to.

Filters: search (workflow, title, branch, repository), the owner and repository pickers, Failing (completed runs that failed) and Mine (runs you started; needs the token's login).

Open a run to see its jobs, failed ones first, then running, then the rest. Each job has a Log button that shows the tail of its log (the last 64 KiB) and a button that opens the job on GitHub. The action bar offers:

Action	What it does
Re-run failed	Re-runs only the failed jobs. Shown on a finished run with a failed job.
Re-run all	Re-runs every job. Shown on a finished run.
Cancel	Cancels a queued or running run after a confirmation.
Pull request #n	Jumps to a pull request the run belongs to.

Re-run and cancel need Actions write access, and are hidden while the host is offline or has no token.

Repositories

The Repositories tab lists every repository the token can see, user and organisation, with a search box. Pinned repositories come first, then the most recently pushed. A row shows the description, last push, an open pull request count, the default branch's check state, and Private, Archived and Fork marks.

• Pin keeps a repository at the top and always counts it as active for polling.
• Hide removes it from the view and stops polling its pull requests. Hiding also unpins. Unhide it under Settings -> GitHub -> Hidden repositories.
• Tapping the open pull request count jumps to the Pull requests tab filtered to that repository.
• Linked projects - each node reports which of its Clusto projects have a github.com remote matching the repository. Those projects appear as chips on the row (and in the agent dialog); tap one to open the project in the Files view. The agent dialog preselects the project you last started from for that repository, else the first linked one.

Review with an agent, Fix failing CI

Two buttons on an open pull request hand it to an agent:

• Review with agent - available on every open pull request.
• Fix failing CI - available when at least one check failed.

Pick a local project (the ones that check out this repository are listed first; any project works if its origin is the same repository). Clusto then, on that project's node:

1. Fetches the pull request head from origin and checks it out in a new worktree worktrees/pr-<number> on branch wt/pr-<number>. If the worktree already exists it moves to the latest head (git refuses if local edits conflict). Nothing is pushed.
2. For Fix failing CI, reads the tail of the log of each failed Actions job.
3. Starts a chat on that node with the worktree attached, using the agent and model of your last chat, and sends the brief as the first message: pull request title, link, author, branch, size and the start of the description, then either the review instructions or the failing check names and log tails.

The review brief tells the agent not to push, comment on GitHub or merge. The fix brief asks for a commit on the checked-out branch and tells it not to push, so you review and push. Change the default agent in Settings -> Chats.

Notifications

The host node records three alert kinds in the durable notification log (see Background Notifications):

Kind	When
github_review_requested	Your login newly appears among a pull request's requested reviewers.
github_checks_failed	Checks on a pull request you wrote turn failed (once per head commit).
github_pull_update	A pull request you wrote is approved, merged or closed.

Each kind has its own switch under Settings -> Notifications -> GitHub and is per device: a device mutes a kind by sending <kind>=off on its /notifications poll. The body reads owner/name #123: title, and tapping the alert opens that pull request.

The first poll of an account only records the current state, so turning the view on does not flood you with alerts for pull requests that already exist. The cursor is kept on the host, so a restart neither repeats nor drops alerts.

Polling and rate limits

The host node polls GitHub every 60 seconds by default (your poll interval) and keeps polling when no client is connected. Requests are conditional (they send the previous ETag) and a 304 Not Modified answer does not count against GitHub's rate limit, so an idle repository costs no budget. In detail:

• The repository list is reread every 10 minutes.
• Open pull requests are read on every poll for active repositories: pinned, having open pull requests, or pushed in the last 14 days. Quiet repositories are read every 10 minutes.
• Open issues and the latest workflow runs are read for active repositories only. They are read on every poll for pinned repositories and for repositories whose previous read showed a queued or running workflow run, so a running CI keeps updating. Every other active repository is read every 10 minutes.
• Check state is fetched only when a pull request's head commit changes, and reviews only when the pull request changed.
• While a check on one of your own pull requests, or a workflow run you started, is running, polling speeds up to 15 seconds.
• When the remaining budget drops below 200 requests, polling slows to one poll every 5 minutes.
• When GitHub rejects the token (401, or a 403 that is not a rate limit, for example a revoked or expired token), the view shows "GitHub rejected the token" with the reason and stops regular polling. The host retries after 2 minutes, then doubles the wait up to once every 30 minutes, and logs the rejection once. Saving a token in Settings -> GitHub, or the refresh button, tries again at once; the first good poll resumes normal polling.

Expect a few hundred requests per hour for about 60 repositories with 15 open pull requests, mostly free 304 answers, well under GitHub's 5000 per hour. Pinning many repositories raises this, because each pinned repository also reads its issues and workflow runs on every poll. The view header shows who you are signed in as, when it last synced, how many requests are left, and Fast polling while the 15 second interval is on. The refresh button polls immediately.

F1 command palette

When the flag is on, the palette has Go to GitHub, Refresh GitHub and GitHub settings: accounts, token, host node. Inside the view it adds the tabs, GitHub: customize the overview, the pull request and issue buckets (including Team on a Team plan), the failing toggles for pull requests and workflow runs and Only my workflow runs. With a pull request open it adds Open #n on GitHub, Comment on #n, Approve #n, Request changes on #n, Merge #n, Review #n with an agent and Fix failing CI of #n with an agent. With an issue open it adds Open issue #n on GitHub, Comment on issue #n, Work on issue #n with an agent, Assign issue #n to me, Close issue #n and Reopen issue #n. With a workflow run open it adds Open run on GitHub, Re-run failed jobs of the run, Re-run every job of the run and Cancel run.

Ask the Assistant

The Clusto Assistant has a read-only clusto_github_prs tool. It lists the open pull requests across your accounts (repository, number, title, author, draft, check status, review decision, requested reviewers and whether one waits on your review), plus sync errors, optionally filtered by repository or account. Each account also reports failing_workflow_runs, the number of its latest workflow runs that finished with a failure (counted for the same repository filter), so the Assistant can tell you CI is red without listing every run. Pull request titles are written by other people, so the Assistant treats them as data. To act on a pull request it points you at this view.

Worktrees and the base ref

Creating a worktree from origin/<branch> now fetches that branch from origin first (git fetch --no-tags origin <branch>), so the new worktree starts at what the remote has right now rather than at the last fetch. This applies to every worktree created from a remote-tracking base, not only the issue hand-off. A failed fetch (offline, no credentials, unknown branch) is reported as an error and no worktree is created; Clusto never silently falls back to a stale ref. A base that is a local branch, tag or commit is used as given and fetches nothing. Pull request worktrees (worktrees/pr-<number>) fetch the pull request head instead, as described under Review with an agent.