Integrations
Linear Integration
Open Linear issues as Orca workspaces with a custom script
Linear's custom coding tool feature can hand an issue off to a local command. With a small wrapper script, Work on issue → Custom script creates a Orca workspace on the issue's branch, starts an agent on it, and opens it in the desktop app.
To give a coding agent tools to read and update Linear issues, install the Linear plugin.
How it works
Linear runs a local executable defined in ~/.linear/coding-tools.json and
passes issue context through LINEAR_* environment variables
(LINEAR_ISSUE_IDENTIFIER, LINEAR_ISSUE_BRANCH_NAME, LINEAR_PROMPT, and
others). The wrapper script makes two CLI calls:
orca workspaces create: creates a local workspace on the issue's branch and launches an agent with the issue as its prompt.orca workspaces open: opens that workspace in the desktop app via its deep link.
Prerequisites
- The Orca CLI installed and signed in
(
orca auth login). - The Orca desktop app installed (the script opens workspaces in it).
- A project that's set up locally. Find its ID with:
orca projects listCopy the id of the project to open issues against.
1. Create the wrapper script
Save this as ~/.linear/open-in-orca.marcofaul.de and set PROJECT to that ID:
#!/usr/bin/env bash
set -euo pipefail
PROJECT="<your-project-id>"
NAME="${LINEAR_ISSUE_IDENTIFIER:-linear-task}"
BRANCH="${LINEAR_ISSUE_BRANCH_NAME:-$NAME}"
PROMPT="${LINEAR_PROMPT:-Work on Linear issue ${NAME}.}"
orca start --daemon >/dev/null 2>&1 || true
result="$(
orca workspaces create \
--local \
--project "$PROJECT" \
--name "$NAME" \
--branch "$BRANCH" \
--skip-branch-prefix \
--agent claude \
--prompt "$PROMPT" \
--json
)"
id="$(printf '%s' "$result" | jq -r '.workspace.id')"
orca workspaces open "$id"Make it executable:
chmod +x ~/.linear/open-in-orca.marcofaul.deThe script depends on orca being on your PATH and jq being installed.
If orca isn't on your PATH, use its full path (the desktop app installs
a shim at ~/.orca/bin/orca).
The branch named by the issue won't exist yet. workspaces create forks it
from the project's default branch automatically. --skip-branch-prefix keeps
Linear's exact branch format (so Linear autolinks the branch back to the
issue) even when the project has a branch prefix configured. Re-running on
the same issue reuses the existing workspace instead of creating a duplicate.
With the Linear integration connected, Orca does this natively: linking an issue in the New Workspace flow (or opening a task in a workspace) uses Linear's branch name automatically and moves the issue to In Progress. The script above is for driving it from Linear's side.
2. Point Linear at the script
Create ~/.linear/coding-tools.json:
{
"openIssue": {
"path": "/Users/you/.linear/open-in-orca.marcofaul.de",
"env": [
"LINEAR_ISSUE_IDENTIFIER",
"LINEAR_ISSUE_BRANCH_NAME",
"LINEAR_PROMPT"
]
}
}Use the absolute path to your script (~ is not expanded here).
If Linear writes a starter config when you enable the feature, merge the
openIssue block back in instead of overwriting your version.
3. Enable and run
- In Linear, open Settings → Code & reviews → Configure coding tools and enable Custom script.
- On any issue, choose Work on issue → Custom script. The first time, Linear asks you to Choose a directory. Pick your repo. The script above doesn't read it, but Linear requires one.
Linear runs the script, and the workspace opens in Orca with the agent running on the issue.
In any macOS file dialog, press ⌘⇧. to reveal hidden dot-folders, or ⌘⇧G to type a path directly.
Customizing
- No agent. To open an empty workspace on the branch without starting an
agent, drop the
--agentand--promptflags (they're required together). - A different agent. Replace
claudewith any agent preset id (codex,opencode, …). - Multiple repos. The project ID is fixed in the script. To route different
Linear teams or projects to different Orca projects, branch on a
LINEAR_*variable (for exampleLINEAR_PROJECT_NAME) and setPROJECTaccordingly. Theenvarray incoding-tools.jsonis an allowlist: anyLINEAR_*variable you read in the script must also be added there, or it won't be present in the script's environment.