Pull requests and issues
Experimental: a pull request inbox, review comments staged locally until you send them, merging, and an
issues list from 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.
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. Between them you get 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.
Add Linear
Enable Linear beside GitHub under Project Settings → Experimental, 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. Write also enables 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 a whole workspace. A project in a second workspace can keep
its own key under Project Settings → Linear. The field also appears there when there
is no app-wide key yet. Clearing it puts that project back on the app-wide key. 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, such as Linux without a keyring, Ouijit refuses to store one and reads LINEAR_API_KEY
from your environment instead.
Ouijit then works out which issues belong to this project. If the workspace labels issues under a
repo label group, the convention other Linear integrations use, Ouijit matches the project to
your origin remote and connects it without asking. 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.
To have an issue move on its own when its pull request opens and merges, connect Linear's GitHub integration to the repository in Linear. Without it nothing syncs, and you move the issue with its state control.
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 draws from whichever tracker can fill it, so an ENG-231
and a #299 sit side by side under one Assigned to you. An empty group is not
shown, so a project with one tracker sees that tracker's groups.
An issue opens in the same view a pull request does, with what its tracker knows. A Linear issue shows assignee, priority, cycle, estimate and team. A GitHub issue shows assignees and labels. A Linear issue also has a state control that moves it through its team's workflow. Unless Linear is watching the repository, that control is the only way to move one. 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.
Search filters the list as you type and also asks GitHub and Linear. Issues and pull requests the list isn't showing, open or closed, appear under More results. Type a number to look that one up. Long lists stop at fifty with Show more at the end.
In a workspace running Linear's own GitHub sync, each piece of work is both a Linear issue and a mirrored GitHub issue, so it appears twice: once under Linear's groups and 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, since 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 For 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 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 not 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 runs 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.
-
An existing task links to an issue with
ouijit issue link 299 --task 42, orENG-231for a Linear issue. The issue shows on the card, and the task menu opens or unlinks it. An issue links to one task at a time. - 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. That needs Linear's GitHub integration connected to the repository.