Skip to main content

​
Prerequisites

  • Node.js 22+ — Download
  • pnpm 9+ — npm install -g pnpm
  • GitHub account — For repository access and OAuth

​
Install

Pick the method that works for your platform:

​
Launch

openlinear
The CLI launcher resolves the desktop binary from ~/Applications/OpenLinear.app (macOS) or ~/.openlinear/ (Linux) and opens the app.

​
Connect GitHub

1

Authenticate

openlinear github login
This opens GitHub in your browser for OAuth, or falls back to device flow. Your token stays on your machine.
2

Verify

openlinear github whoami
Confirms your GitHub identity is connected.

​
Create Your First Task

1

Open the App

Launch OpenLinear. You’ll land on the kanban board.
2

Connect a Repository

Click Source → Edit in the project config panel. Enter a GitHub repo URL or select from your repositories.
3

Add a Task

Click + Add task in the Todo column. Describe what you want:
Add a health check endpoint at GET /api/health 
that returns { status: "ok", timestamp: Date.now() }
4

Execute

Drag the task to In Progress, or right-click and select Execute. OpenLinear will:
  1. Clone the repository
  2. Create a branch (openlinear/<task-id>)
  3. Start the AI agent
  4. Write code and commit changes
  5. Give you a PR compare URL
5

Review

Click the PR link in the task card to review the diff on GitHub. Merge when satisfied.

​
Configure AI Provider

OpenLinear uses OpenCode as the execution engine. You need at least one AI provider configured:
  1. Open Settings in the sidebar
  2. Go to AI Providers
  3. Add your API key for one of: Anthropic, OpenAI, Google, GitHub Copilot, or any supported provider
  4. Select a model in the Model Selector dropdown on the board
OpenCode provides free models (Minimix, GLM5, KimiK2.5) that work without an API key.

​
Next Steps

Desktop App Guide

Learn all the desktop features — kanban board, batch execution, model selection.

CLI Reference

Full command reference for the openlinear CLI.

API Reference

REST API for programmatic access to tasks, projects, and execution.

Architecture

Understand how the desktop app, sidecar, and API work together.