Connect to Linear

Connecting Linear means you can delegate straight from your board: tag an issue with cate and a Cate agent handles it. Everything they do contributes to collective context: specs, decisions, handoff comments, and research visible to teammates and their agents.

An agent walks you through the setup and helps you merge .cate/workflows.json — your tracker configuration file — to your default branch.

Before you start

Add your GitHub credentials in Settings → Accounts — Linear needs to reference pull requests. Then add your Linear credentials: click “Sign in with Linear” to authenticate via OAuth.

If your project needs different credentials than your global settings, see Project-specific credentials.

Run the connect flow

Click New Task in the top right, then Configure → Linear. If Linear isn’t available, check that your Linear credentials are set in Settings → Accounts.

The agent checks your git remote, then walks you through:

1. Team selection — the agent discovers your Linear teams. Select the team you want Cate to use.

2. Status mapping — the agent maps your existing Linear workflow states to Cate’s queues. You can have any statuses you want — Cate recommends a set of five, but works with your existing workflow. See Status lifecycle for details on how statuses map to queues.

3. Cycles — if your team uses cycles, Cate can scope work to the current cycle so agents only pick up issues assigned to it.

4. Configuration — the agent asks about your dispatch label, branch naming convention, and autonomy preference, then writes everything to .cate/workflows.json.

After connecting

The agent commits the configuration and ensures it reaches your default branch. Once merged, the app picks up the new tracker automatically.

To adjust the configuration later, start a Pair session and ask the agent to help. See the workflows.json reference for field descriptions.

Project-specific credentials

If this project needs different credentials than your global settings — for example, a different GitHub account or Linear workspace — click the project settings gear (top right) and set them under the project’s credential overrides.

Troubleshooting

Expired or revoked OAuth token. Re-authenticate by clicking “Sign in with Linear” in Settings → Accounts.

Team not found. Confirm the team you selected during setup still exists in Linear and that your account has access to it. Re-run setup if the team was renamed or reorganized.