cyrus-setup-linear

重要：~/.cyrus/.env または ~/.cyrus/ 内のファイルに対して、Read、Edit、Write ツールを絶対に使用しないでください。環境ファイルを操作する場合は、Bash コマンド（grep、printf >> など）のみを使用してください。シークレットを会話のコンテキストに読み込んではいけません。Web ページからシークレットの値をスクレイピング、抽出、読み取りしないでください。ユーザー自身でコピーするよう案内してください。

Linear をセットアップする

Linear OAuth アプリを作成し、Cyrus が Webhook を受信して課題に応答できるよう認証情報を設定します。

ステップ 1：既存の設定を確認する

grep -E '^LINEAR_CLIENT_ID=' ~/.cyrus/.env 2>/dev/null

LINEAR_CLIENT_ID がすでに設定されている場合は、OAuth の設定も完了しているか確認します。

grep -q '"workspaces"' ~/.cyrus/config.json 2>/dev/null && echo "configured" || echo "not configured"

両方が設定されている場合は、ユーザーに次のように伝えます。

Linear はすでに設定されています。このステップをスキップします。 再設定するには、~/.cyrus/.env から LINEAR_CLIENT_ID、LINEAR_CLIENT_SECRET、LINEAR_WEBHOOK_SECRET を削除して、再実行してください。

完了までスキップします。

ステップ 2：CYRUS_BASE_URL を取得する

環境ファイルからベース URL を読み取ります（setup-endpoint によって設定されています）。

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

これはコールバック URL と Webhook URL に必要です。

ステップ 3：マニフェストから Linear OAuth アプリを作成する

Linear OAuth アプリは、マニフェストを利用するセットアップ URL から作成する必要があります。アプリを一から作成したり、各フィールドを手動で入力したりしないでください。マニフェストを使うことでアプリ設定を再現可能な状態に保ち、コールバック、Webhook、イベントタイプの設定にずれが生じるのを防げます。

3a. マニフェスト URL を作成する

JSON の OAuth アプリマニフェストを生成し、Linear の manifest クエリパラメーターにエンコードします。

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)"

同じ URL が、自動化コマンド用の LINEAR_MANIFEST_URL と、手動でコピー＆ペーストするための /tmp/cyrus-linear-oauth-app-url.txt に保存されます。JSON は確認やデバッグ専用として /tmp/cyrus-linear-oauth-app-manifest.json に保存されます。ユーザーに OAuth アプリのフォームを手動で入力するよう求めないでください。

<AGENT_NAME> に「Linear」という単語または URL が含まれている場合は、マニフェストを作成する前に別の OAuth アプリ名を選んでください。Linear はこれらの値を含む OAuth クライアント名を拒否します。

オーケストレーターのルールを参照し、使用するブラウザー自動化モードを判断します。

1. claude-in-chrome MCP ツールが利用可能な場合 → Path A-1（claude-in-chrome）を使用
2. agent-browser がインストールされており（which agent-browser）、Chrome デバッグセッションが接続されている場合 → Path A-2（agent-browser）を使用
3. それ以外の場合 → Path B（手動）を使用

Path A-1：claude-in-chrome による自動化

mcp__claude-in-chrome__* ツールを使用して、ユーザーが現在使用している Chrome ブラウザーに移動し、操作します。ユーザーはすでに Linear にサインインしている可能性があります。

LINEAR_MANIFEST_URL に移動します。マニフェストが適用された OAuth アプリ設定がすでに入力された状態でページが開きます。

シークレットではないフィールドのみ確認します。

• アプリケーション名が <AGENT_NAME> と一致している
• 開発者名が Self-hosted になっている
• 開発者 URL が https://github.com/ceedaragents/cyrus になっている
• リダイレクトコールバック URL に <CYRUS_BASE_URL>/callback が含まれている
• Webhook が有効で、URL が <CYRUS_BASE_URL>/linear-webhook になっている
• イベントタイプに Agent session events、Inbox notifications、Permission changes、Issues が含まれている
• 公開／配布設定が非公開または無効になっている

ユーザーがサインインしていない場合は、いったん停止してサインインを依頼してください。確認後、Create をクリックします。認証情報のページをスクリーンショットに撮ったり、シークレットをスクレイピングしたりしないでください。 ステップ 4 に進みます。

Path A-2：agent-browser による自動化

agent-browser が Chrome デバッグセッションに接続されている場合は、Linear アプリの作成を自動化します。

3b. マニフェスト URL に移動する

agent-browser navigate "$LINEAR_MANIFEST_URL"

ページの読み込みを待ちます。正しいページが表示され、ログイン済みであることを確認するため、スクリーンショットを撮影します。

3c. 確認して作成する

Path A-1 に記載された、マニフェストが適用されたフィールドのうち、同じシークレットではない項目を確認します。ページでユーザーにサインインを求められた場合は、いったん停止し、ユーザー自身でサインインを完了してもらいます。Create をクリックします。

作成後、Linear によってアプリ設定ページにリダイレクトされます。認証情報のページをスクリーンショットに撮ったり、シークレットをスクレイピングしたりしないでください。 ステップ 4 に進みます。

パス B：手動セットアップガイド

手動での作成手順をユーザーに案内します。

Linear OAuth アプリケーションを作成する

1. マニフェストが適用された Linear アプリ作成 URL を開きます。

   <LINEAR_MANIFEST_URL>

2. 求められた場合は Linear にサインインし、入力済みの設定を確認します。

   • アプリケーション名： <AGENT_NAME>
   • 開発者名： Self-hosted
   • 開発者 URL： https://github.com/ceedaragents/cyrus
   • リダイレクトコールバック URL： <CYRUS_BASE_URL>/callback
   • Webhook URL： <CYRUS_BASE_URL>/linear-webhook
   • Webhook： ✓ 有効
   • イベントタイプ： ✓ エージェントセッションイベント、✓ 受信トレイの通知、✓ 権限の変更、✓ イシュー
   • 公開： ✗ 無効のままにします（これはプライベートなセルフホストアプリです）

3. Create をクリックします。

ステップ 4 に進みます。

ステップ 4：認証情報を取得する

エージェントはページからシークレットをスクレイピング、読み取り、抽出してはなりません。 ユーザーが手動でコピーし、env ファイルに貼り付けます。

4a. 認証情報のプレースホルダーを追加する

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/.env

4b. 編集する env ファイルを開く

# 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/.env

4c. ユーザーに案内する

ユーザーに次のように伝えます。

~/.cyrus/.env を開きました。Linear アプリ設定ページから 3 つの値を貼り付けてください。

1. Client ID — コピーして LINEAR_CLIENT_ID= の後に貼り付けます
2. Client Secret — 横にあるコピー ボタンをクリックし（ドットでマスクされています）、LINEAR_CLIENT_SECRET= の後に貼り付けます
3. Webhook Signing Secret — 横にあるコピー ボタンをクリックし、LINEAR_WEBHOOK_SECRET= の後に貼り付けます

完了したら、ファイルを保存して閉じてください。

4d. 検証する

ユーザーが保存したことを確認したら、次を実行します。

grep -c '^LINEAR_CLIENT_ID=.' ~/.cyrus/.env
grep -c '^LINEAR_CLIENT_SECRET=.' ~/.cyrus/.env
grep -c '^LINEAR_WEBHOOK_SECRET=.' ~/.cyrus/.env

3 つすべてが 1 を返す必要があります（= の後の . により、値が空でないことを確認します）。いずれかが 0 の場合は、ファイルを確認するようユーザーに伝えます。

ステップ 5：Linear で認証する

OAuth 認証フローを実行します。

cyrus self-auth-linear

これにより、次の処理が行われます。

1. 一時的な OAuth コールバックサーバーを起動します
2. ブラウザーで Linear の認証ページを開きます
3. ユーザーが Authorize をクリックすると、トークンを ~/.cyrus/config.json に保存します

認証が成功したことを確認します。

cat ~/.cyrus/config.json | grep -c '"workspaces"'

カウントが 0 の場合、認証に失敗しています。認証情報を確認して再試行するようユーザーに伝えます。

完了

✓ Linear OAuth アプリケーションを作成しました ✓ 認証情報を ~/.cyrus/.env に保存しました ✓ cyrus self-auth-linear でワークスペースを認証しました