cyrus-setup-linear
Skill888 starsChanged 53 days agoApache-2.0View on GitHub
Create a Linear OAuth application and configure Cyrus to use it — supports agent-browser automation or guided manual setup.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- cyrusagents/cyrusword for word, first seen Sep 24, 2026
Other versions1 project uses a version of this.
Word for word · 1
- cyrusagents/cyrus★ 902100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- packages/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- googleSkill
- release-core-testSkill
- cyrus-setup-claude-authSkill
- cyrus-setup-endpointSkill
- cyrus-setup-githubSkill
- cyrus-setup-gitlabSkill
- cyrus-setup-launchSkill
- cyrus-setup-prerequisitesSkill
- cyrus-setup-repositorySkill
- cyrus-setupSkill
- cyrus-setup-slackSkill
- debugSkill
- f1-test-driveSkill
- implementationSkill
- investigateSkill
- releaseSkill
- summarizeSkill
- verify-and-shipSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 8 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
If LINEAR_CLIENT_ID is already set, check if OAuth is also complete:
- Distinctive: line 24
If both are set, inform the user:
- Very specific: line 33
Read the base URL from the env file (set by setup-endpoint):
- Very specific: line 104
If <AGENT_NAME> contains the word "Linear" or a URL, choose a different OAuth application name before building the manifest.
- Very specific: line 108
If claude-in-chrome MCP tools are available → use Path A-1 (claude-in-chrome)
- Very specific: line 109
If agent-browser is installed (which agent-browser) and a Chrome debug session is connected → use Path A-2 (agent-browser)
- Very specific: line 114
Use the mcp__claude-in-chrome__* tools to navigate and interact with the user's existing Chrome browser.
- Distinctive: line 128
If the user is not signed in, pause and ask them to sign in.
- Very specific: line 132
If agent-browser is connected to a Chrome debug session, automate the Linear app creation.
- Distinctive: line 140
Wait for page to load. Take a screenshot to verify you're on the right page and logged in.
- Distinctive: line 146
After creation, Linear redirects to the app settings page.
- Distinctive: line 207
After the user confirms they've saved:
- Very specific: line 215
All three must return 1 (the .
- Distinctive: line 219
Run the OAuth authorization flow:
- Distinctive: line 226
Start a temporary OAuth callback server
- Very specific: line 228
After the user clicks Authorize, save tokens to ~/.cyrus/config.json
- Distinctive: line 236
If the count is 0, authorization failed.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CRITICAL: Never use Read, Edit, or Write tools on ~/.cyrus/.env or any file inside ~/.cyrus/. Use only Bash commands (grep, printf >>, etc.) to interact with env files — secrets must never be read into the conversation context. Never scrape, extract, or read secret values from web pages — guide the user to copy them manually.
Setup Linear
Creates a Linear OAuth application and configures credentials so Cyrus can receive webhooks and respond to issues.
Step 1: Check Existing Configuration
grep -E '^LINEAR_CLIENT_ID=' ~/.cyrus/.env 2>/dev/nullIf LINEAR_CLIENT_ID is already set, check if OAuth is also complete:
grep -q '"workspaces"' ~/.cyrus/config.json 2>/dev/null && echo "configured" || echo "not configured"If both are set, inform the user:
Linear is already configured. Skipping this step. To reconfigure, remove
LINEAR_CLIENT_ID,LINEAR_CLIENT_SECRET, andLINEAR_WEBHOOK_SECRETfrom~/.cyrus/.envand re-run.
Skip to completion.
Step 2: Get CYRUS_BASE_URL
Read the base URL from the env file (set by setup-endpoint):
grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-This is needed for the callback and webhook URLs.
Step 3: Create Linear OAuth App From Manifest
Linear OAuth apps must be created from a manifest-backed setup URL. Do not create the app from scratch or fill each field manually. The manifest flow keeps the app configuration reproducible and avoids drift in callback, webhook, and event type settings.
3a. Build the manifest URL
Generate a JSON OAuth app manifest and encode it into Linear's manifest query parameter:
CYRUS_BASE_URL="<CYRUS_BASE_URL>" \
AGENT_NAME="<AGENT_NAME>" \
AGENT_DESCRIPTION="<AGENT_DESCRIPTION>" \
node <<'NODE'
const fs = require("node:fs");
const baseUrl = process.env.CYRUS_BASE_URL.replace(/\/+$/, "");
const agentName = process.env.AGENT_NAME || "Cyrus";
const agentDescription =
process.env.AGENT_DESCRIPTION || "AI coding agent for automated development";
const manifest = {
$schema: "https://linear.app/.well-known/oauth-app-manifest.schema.json",
schemaVersion: "1.0.0",
distribution: "private",
display: {
description: agentDescription,
},
developer: {
name: "Self-hosted",
},
oauth: {
client_name: agentName,
client_uri: "https://github.com/ceedaragents/cyrus",
redirect_uris: [`${baseUrl}/callback`],
grant_types: ["authorization_code"],
},
webhook: {
enabled: true,
url: `${baseUrl}/linear-webhook`,
resourceTypes: [
"AgentSessionEvent",
"AppUserNotification",
"PermissionChange",
"Issue",
],
},
};
const manifestJson = JSON.stringify(manifest, null, 2);
const manifestUrl = `https://linear.app/settings/api/applications/new?manifest=${encodeURIComponent(JSON.stringify(manifest))}`;
fs.writeFileSync("/tmp/cyrus-linear-oauth-app-manifest.json", `${manifestJson}\n`);
fs.writeFileSync("/tmp/cyrus-linear-oauth-app-url.txt", `${manifestUrl}\n`);
console.log(manifestJson);
console.log(`\n${manifestUrl}`);
NODE
LINEAR_MANIFEST_URL="$(cat /tmp/cyrus-linear-oauth-app-url.txt)"The same URL is now stored in LINEAR_MANIFEST_URL for automation commands and in /tmp/cyrus-linear-oauth-app-url.txt for manual copy/paste. The JSON is stored in /tmp/cyrus-linear-oauth-app-manifest.json for review/debugging only; do not ask the user to fill the OAuth app form manually from it.
If <AGENT_NAME> contains the word "Linear" or a URL, choose a different OAuth application name before building the manifest. Linear rejects OAuth client names with those values.
Determine which browser automation mode to use (see orchestrator rules):
- If
claude-in-chromeMCP tools are available → use Path A-1 (claude-in-chrome) - If
agent-browseris installed (which agent-browser) and a Chrome debug session is connected → use Path A-2 (agent-browser) - Otherwise → use Path B (manual)
Path A-1: claude-in-chrome Automation
Use the mcp__claude-in-chrome__* tools to navigate and interact with the user's existing Chrome browser. The user is likely already signed in to Linear.
Navigate to LINEAR_MANIFEST_URL. The page should open with the manifest-applied OAuth app configuration already populated.
Review only non-secret fields:
- Application name matches
<AGENT_NAME> - Developer name is
Self-hosted - Developer URL is
https://github.com/ceedaragents/cyrus - Redirect callback URLs contains
<CYRUS_BASE_URL>/callback - Webhook is enabled with URL
<CYRUS_BASE_URL>/linear-webhook - Event types include Agent session events, Inbox notifications, Permission changes, and Issues
- Public/distribution is private or disabled
If the user is not signed in, pause and ask them to sign in. After review, click Create. Do NOT screenshot credential pages or attempt to scrape secrets. Proceed to Step 4.
Path A-2: agent-browser Automation
If agent-browser is connected to a Chrome debug session, automate the Linear app creation.
3b. Navigate to the manifest URL
agent-browser navigate "$LINEAR_MANIFEST_URL"Wait for page to load. Take a screenshot to verify you're on the right page and logged in.
3c. Review and create
Review the same non-secret manifest-applied fields listed in Path A-1. If the page asks the user to sign in, pause and let them complete sign-in. Click Create.
After creation, Linear redirects to the app settings page. Do NOT screenshot credential pages or attempt to scrape secrets. Proceed to Step 4.
Path B: Manual Guided Setup
Guide the user through manual creation:
Create a Linear OAuth Application
Open this manifest-backed Linear app creation URL:
<LINEAR_MANIFEST_URL>- Sign in to Linear if prompted, then review the pre-filled settings:
- Application name:
<AGENT_NAME>- Developer name:
Self-hosted- Developer URL:
https://github.com/ceedaragents/cyrus- Redirect callback URLs:
<CYRUS_BASE_URL>/callback- Webhook URL:
<CYRUS_BASE_URL>/linear-webhook- Webhook: ✓ enabled
- Event types: ✓ Agent session events, ✓ Inbox notifications, ✓ Permission changes, ✓ Issues
- Public: ✗ leave disabled (this is a private self-hosted app)
- Click Create
Proceed to Step 4.
Step 4: Collect Credentials
The agent must NOT scrape, read, or extract secrets from the page. The user copies them manually into the env file.
4a. Add credential placeholders
grep -q '^LINEAR_CLIENT_ID=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_ID=' >> ~/.cyrus/.env
grep -q '^LINEAR_CLIENT_SECRET=' ~/.cyrus/.env || echo 'LINEAR_CLIENT_SECRET=' >> ~/.cyrus/.env
grep -q '^LINEAR_WEBHOOK_SECRET=' ~/.cyrus/.env || echo 'LINEAR_WEBHOOK_SECRET=' >> ~/.cyrus/.env4b. Open env file for editing
# macOS
code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env
# Linux
code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env4c. Guide the user
Tell the user:
I've opened
~/.cyrus/.env. You need to paste three values from your Linear app settings page:
- Client ID — copy it and paste after
LINEAR_CLIENT_ID=- Client Secret — click the copy button next to it (it's masked with dots), paste after
LINEAR_CLIENT_SECRET=- Webhook Signing Secret — click the copy button next to it, paste after
LINEAR_WEBHOOK_SECRET=Save and close the file when done.
4d. Verify
After the user confirms they've saved:
grep -c '^LINEAR_CLIENT_ID=.' ~/.cyrus/.env
grep -c '^LINEAR_CLIENT_SECRET=.' ~/.cyrus/.env
grep -c '^LINEAR_WEBHOOK_SECRET=.' ~/.cyrus/.envAll three must return 1 (the . after = ensures the value is not empty). If any are 0, ask the user to check the file.
Step 5: Authorize with Linear
Run the OAuth authorization flow:
cyrus self-auth-linearThis will:
- Start a temporary OAuth callback server
- Open the browser to Linear's authorization page
- After the user clicks Authorize, save tokens to
~/.cyrus/config.json
Verify authorization succeeded:
cat ~/.cyrus/config.json | grep -c '"workspaces"'If the count is 0, authorization failed. Ask the user to check their credentials and try again.
Completion
✓ Linear OAuth application created ✓ Credentials saved to
~/.cyrus/.env✓ Workspace authorized viacyrus self-auth-linear
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

