Pull requests

An experimental tracker surface: a pull request inbox, review comments staged locally until you send them, merging, and an issues list fed by GitHub, Linear, or both. It drives the gh CLI, so gh auth login is the only setup for the GitHub half.

Turn it on

Enable GitHub under Project Settings → Experimental. It needs the GitHub CLI 2.48.0 or newer on PATH, signed in via gh auth login, and an origin remote on GitHub. Ouijit never stores a GitHub token; every GitHub call goes through gh on the host, and sandboxed terminals never see your credentials.

Add Linear

Enable Linear beside it, then paste a personal API key into App Settings → Linear. Make one in Linear under Settings → API: Read and Create comments is enough to read issues and comment, and Write additionally buys the control that moves an issue. Limiting the key to one team is fine, and narrows what Ouijit can see.

One key serves every project, since a key reads one workspace. A project in a second workspace can keep its own under Project Settings → Linear, which is also where the field appears when there is no key yet — clearing it puts that project back on the app-wide one. Keys are encrypted by your OS keychain and kept out of the renderer, the REST API and every sandboxed terminal. On a machine with no keychain — Linux without a keyring — Ouijit refuses to store one and reads LINEAR_API_KEY from your environment instead.

Ouijit then works out which issues are this project's. Workspaces that label issues under a repo label group — the convention other Linear integrations already write — are matched against your origin remote and connected without being asked. Otherwise a row above the list asks once which team to use. Change it, or disconnect the project from Linear entirely, under Project Settings → Linear.

For an issue to move on its own when its pull request opens and merges, connect Linear's GitHub integration — in Linear, per repository. Without it nothing syncs, and the state control on the issue is the way to move it.

Work the inbox

The panel lists open pull requests in three groups: Needs your review, Authored, and Everything else, with an issues tab beside them. A pull request opens into Summary, Timeline, and Code tabs: checks, review threads with resolve and reply, and per-file diffs with a Viewed state that resets when the head changes. Browsing a pull request never checks anything out.

Work the issues

The Issues tab is one list, ordered by what wants your attention: Triage, In progress, Assigned to you, Current cycle, then the repository's open issues. Each group is answered by whichever source can answer it — an ENG-231 and a #299 sit side by side under one Assigned to you — and a group with nothing in it does not render, so a project with one tracker sees one tracker's groups.

An issue opens in the same chrome a pull request does, with what its source knows: assignee, priority, cycle, estimate and team for a Linear issue, assignees and labels for a GitHub one. A Linear issue carries a state control that moves it through its team's workflow — the fastest way to move one, and the only way where Linear is not watching the repository. Under a key without Write the control is absent.

Comments post when you send them. A comment written by an agent through the CLI waits above the box with its origin beside it, until you press Send.

A workspace running Linear's own GitHub sync has each piece of work as a Linear issue and a mirrored GitHub issue, so it appears twice — once under Linear's groups, once under the repository's.

Stage a review

Review comments start as local drafts. Nothing reaches GitHub until you press Comment, Approve, or Request changes, which submits the drafts as one review. Drafts re-anchor when the pull request's head moves; one that can no longer be placed is flagged rather than deleted, and blocks submission until you discard or rewrite it, because GitHub would reject the whole review.

Agents stage drafts through the CLI, and each draft shows its origin so you can tell who wrote what before sending: 

ouijit pr draft add 42 --file src/api.ts --line 88 \
  --origin claude --body "this can throw when the token is missing"

See Agents for the full agent review workflow.

Read it through a lens

The Code pane takes the same lenses the worktree diff does, from the picker above the file list: an agent reads the change and answers with its parts, and the rail and the document both follow that order instead of the file tree.

Read marks follow the parts. A file split across three of them is ticked a part at a time, and counts as read once every part of it has been. A lens written for an earlier head is dropped rather than shown against hunks a force-push has moved; the picker offers to run it again. An agent can write one itself with ouijit pr lens set, described under the CLI.

Merge

Open pull requests get a merge menu with Merge, Squash, and Rebase, plus a delete-branch toggle. Unmet requirements are listed; when GitHub grants you admin bypass, a separate Merge without meeting requirements entry maps to gh pr merge --admin.

Connect pull requests and tasks

Ouijit links a task to the pull request on its branch automatically, so a PR the agent opened mid-session still shows up on the card. The other direction works too:

  • Check out as task creates a task with a worktree at the pull request's head, with the PR body as its prompt and the PR's base branch as its merge target.
  • Create pull request on a task card pushes the branch and runs gh pr create, so your repository's PR template applies.
  • A task created from an issue links back, and its pull request closes the issue.
  • A task created from a Linear issue starts on the branch name Linear suggested, and the pull request opened from it carries the issue identifier in its body. Linear reads either one, so the issue moves to In Review and then to Done as the pull request does — provided Linear's GitHub integration is connected to the repository.