Linear
Start OpenInspect sessions by mentioning or assigning the Linear Agent on an issue, follow progress in Linear, and control model and repository selection.
Mention or assign the Linear Agent on an issue to start a session, then use Linear for progress, results, and follow-ups.
This page is for people using Linear day to day. Installing the Linear OAuth app and deploying the worker is operator work; see the Linear bot setup guide in the repository.
Quick start
-
Open the Linear issue you want OpenInspect to work on.
-
Mention the agent in a comment:
@OpenInspect please implement this issue and open a pull request -
Or assign the issue to the Linear Agent when the issue already explains the work.
-
Include
owner/repoif the issue could match more than one repository. -
Use View Session to watch the full session.
-
Send follow-ups through the same active Linear Agent session.
Linear shows the session as agent activities while the work runs elsewhere:
What Linear can do
| Workflow | How it works |
|---|---|
| Start from an issue mention | Mention the Linear Agent on an issue |
| Start from assignment | Assign the issue to the Linear Agent |
| Continue active work | Send a follow-up through the same active Linear Agent session |
| Stop or cancel work | Stop or cancel the Linear Agent session to stop the OpenInspect session |
| Resolve the repository | Let OpenInspect infer the repository, or include owner/repo when asked |
| Follow progress | Watch Linear activities or open the full session with View Session |
Only a mention or an assignment starts work. Regular issue comments continue work only when they are part of an active Linear Agent session.
Start, continue, or stop work
From a mention
Mention the Linear Agent on an issue. OpenInspect uses the issue and recent comments as context, and the triggering comment becomes the instruction, so say what you want done:
@OpenInspect can you fix the failing invite flow described above?From assignment
Assign the issue to the Linear Agent when the title and description already describe the work. Assignment works best when the issue includes a clear title and description, acceptance criteria or the expected result, the target repository if it is ambiguous, and whether the agent should open a pull request.
Follow-ups
Follow-up prompts on an issue with an active session go to that session. When available, OpenInspect adds recent agent output as context.
Issue-to-session mappings are kept for 7 days. If the mapping has expired, or the previous session was stopped or cancelled, a new Linear Agent request may start a new session.
Stop or cancel
Stopping or cancelling the Linear Agent session stops the OpenInspect sandbox session and clears the issue's session mapping.
Repository selection
Before starting, OpenInspect chooses a repository from the Linear project, team, labels, issue text, comments, and repository metadata. If the issue could match more than one repository, name it in the issue or the trigger comment:
Please handle this in acme/billing-api.If OpenInspect asks for clarification, reply with owner/repo; that answer is used on the next attempt.
Administrators can map Linear projects or teams to repositories, and those mappings can point at an environment instead of a single repository, so an issue opens the environment's full workspace. Mapping setup is in the Linear bot setup guide.
If the resolved repository is outside the Linear Repository Scope, Linear shows an error and no session starts.
Team ownership versus target mappings
A team lead or workspace administrator can bind an external Linear team ID in an OpenInspect team's Channels tab. Primary marks its main binding for that provider; Source also routes new sessions to that team. An external Linear team belongs to only one OpenInspect team, and a team has at most one primary binding per provider. Enter the Linear team ID, not a team name or issue-key prefix. Slack channel discovery is not needed.
Legacy config:team-repos and config:project-repos mappings select a repository or environment. They do not assign OpenInspect team ownership, grant membership, or grant repository access. The teams database migration does not convert those KV mappings into bindings. To adopt team ownership, explicitly add the binding, OpenInspect members, and repository grants; retain any target mappings you still need for target selection. Adding a binding does not reassign existing sessions.
Linear's unboundChannels policy defaults to workspace: unbound Linear teams start workspace-owned sessions. reject asks for a binding instead and creates no session. A failed binding lookup also stops launch instead of silently choosing workspace ownership.
Repository, environment, and resolved integration-setting lookups carry the external Linear team scope. Actor-bearing catalogs require membership or workspace-admin access, and creating a team session checks actual membership and target grants. Failed scoped lookups do not fall back to workspace-wide catalogs. A legacy target mapping cannot make an unavailable target accessible.
Discovery and callback reads can run without a human actor under narrow Linear-bot service permissions, still scoped to the Linear team. That does not impersonate a member or grant arbitrary session creation. Automation-created delegations use the installed app user as the acting identity for creation.
Team enforcement rollout
TEAMS_ENFORCEMENT remains shadow by default, not on. Team-read denials can be audited rather
than blocked in that mode, so scoped reads alone do not guarantee cross-team output isolation.
Private-session access remains enforced.
What Linear shows
| Activity | What it means |
|---|---|
| Thinking | OpenInspect is analyzing the issue or choosing a repository |
| Working | A session has started |
| Tool progress | Optional updates for file reads, edits, and commands |
| Clarification | OpenInspect needs more information, usually the repository name |
| Completion or error | The session finished, failed, or could not continue |
When a session starts, Linear receives a View Session link. If the agent opens a pull request, Linear receives a Pull Request link when the session finishes. Live output, logs, artifacts, and file changes are in the web session.
Completion content is checked before posting. The bot verifies the issue's current Linear team and withholds results if it changed from the recorded launch team or cannot be verified. It then reads events and artifacts without a human actor, scoped to the verified team. Denied or failed reads produce a generic results-withheld error, not session content or a PR link. Older callbacks recover the launch team from a matching issue-session mapping when possible; otherwise they use the verified current team for the scoped read. Team-visibility enforcement on those reads depends on the rollout mode above.
OpenInspect changes an issue's status at most once, when a person starts a session:
| Issue state before | What OpenInspect does |
|---|---|
| Unstarted, session started by a person | Moves the issue to the team's first started workflow state, only after the initial prompt reaches a live sandbox |
| Unstarted, session started by an automation | Nothing |
| Already started, completed, or cancelled | Nothing |
| Any state, on a follow-up | Nothing; follow-ups never change status |
OpenInspect does not change labels, assignee, priority, or project; pull request workflow changes stay with Linear's GitHub integration.
Settings › Integrations › Linear
| Setting | What it controls |
|---|---|
| Agent harness | OpenCode (default), Claude Agent, or Codex for new Linear-started sessions |
| Default model and Default reasoning effort | Model and reasoning depth for Linear-started sessions; the list shows only models the selected harness can run |
| Repository Scope | All repositories (Linear events can run against every accessible repository) or Selected repositories (only the allowlist) |
| Issue Session Instructions | Custom instructions appended to agent prompts for all Linear issue sessions (coding standards, preferred tools, PR conventions); up to 10,000 characters |
| Allow user model preferences | Whether admin-managed user preferences can override the model |
| Allow model labels (model:*) | Whether a model:* issue label can choose the model |
| Emit tool progress activities | Whether Linear shows intermediate file and command activity |
| Repository Overrides | Per-repository harness, model, effort, tool updates, user preference override, and label model override |
With no settings configured, all accessible repositories are in scope, user preferences and model labels are allowed, and tool progress is on.
Model selection uses this priority, highest first:
- A
model:*issue label, when allowed. - The Linear user's preference, when allowed. These preferences are admin or API managed, not set from a Linear screen.
- The repository override, then the global Linear default.
- The deployment default model.
The selected Agent harness is preserved. If it cannot run the resolved model, the bot posts an error activity in Linear and creates no coding session instead of switching to OpenCode. Claude Agent runs Anthropic models only, so a model:gpt-* label is refused on that harness. Choose a compatible model:* label, user preference, or default model, or change the Linear integration harness, then delegate again. Labels and user preferences apply only when allowed. For successful launches, the "Creating coding session" activity names the harness.
Omitted repository harness and model fields inherit individually from the global settings. If neither level sets a harness, it is OpenCode. Explicitly choosing a restricted harness such as Claude Agent requires a compatible default model at that same settings level (global or repository), not an inherited model. The settings form and control plane reject a missing model or an incompatible pair at that level. Save validation does not check the merged global/repository pair; cross-level mismatches are refused at launch.
Claude Agent sessions started from Linear are automated sessions: they use the default Claude account when its Automated authentication allows it, otherwise ANTHROPIC_API_KEY. See Provider accounts. A harness change applies to new sessions; follow-ups keep the session's harness.
Admin and safety notes
- Linear webhooks are verified before OpenInspect acts on them.
- Linear client credentials, access tokens, webhook secrets, and callback secrets stay server-side. Access tokens are cached and replaced automatically.
- Linear does not provide Git credentials. Repository access comes from the deployment's source-control integration, such as the GitHub App installation.
- Repository Scope controls which resolved repositories can receive Linear-started sessions.
- Issue titles, descriptions, comments, and agent prompts are sent to the agent. Do not put secrets in them.
- Linear-started sessions never use anyone's personal memories, because their replies post where others read them. Repository and environment memories still apply.
- OpenInspect links each Linear user to an account by their Linear email. A new user whose email the bot can't read, or whose email matches no account and isn't allowed by the workspace's sign-in rules, gets an error activity and no session. People the workspace admits only by GitHub username or organization should sign in on the web first with their Linear email.
Troubleshooting
Next steps
GitHub
Automatic pull request reviews, @mention actions, PR Feedback Autofix, and the GitHub bot settings that control who can trigger OpenInspect from GitHub.
Personal access tokens
Issue tokens that let tools such as the OpenInspect MCP server call the API as you, limited to the permissions you grant.