Linear Channel for NanoClaw

Add Linear Channel

Adds Linear support via the Chat SDK bridge. The agent participates in issue comment threads. Every comment on a Linear issue triggers the agent — no @-mention needed. NanoClaw doesn't ship channels in trunk — this skill copies the Linear adapter in from the channels branch.

The mechanical steps under Apply carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Prerequisites

Recommended: Create a Linear OAuth application so the agent posts as an app identity, not as you. This prevents the adapter from filtering your own comments as self-messages.

1. Go to Linear Settings > API > OAuth Applications
2. Create an app (e.g. "NanoClaw Bot")
   • Developer URL: your repo URL (e.g. https://github.com/your-org/nanoclaw)
   • Callback URL: http://localhost
3. After creating, click the app and enable Client credentials under grant types
4. Copy the Client ID and Client Secret

Alternative: Use a Personal API Key (LINEAR_API_KEY) for simpler setup. The agent will post as you, and your own comments will be filtered (other team members' comments still work).

Apply

Linear OAuth apps post and read comments under an app identity that can't be @-mentioned; the adapter's declared channel defaults therefore respond to plain comments rather than mention-only, and the wiring below sets that same pattern mode explicitly.

1. Copy the adapter and its registration test

Fetch the channels branch and copy the Linear adapter and its registration test into src/channels/ (overwrite — the branch is canonical):

src/channels/linear.ts
src/channels/linear-registration.test.ts

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into the channel registry:

import './linear.js';

3. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and latest:

@chat-adapter/linear@4.29.0

4. Build and validate

Build first: it guards the typed createChatSdkBridge(...) core call and proves the dependency is installed. Then run the one integration test.

pnpm run build

pnpm exec vitest run src/channels/linear-registration.test.ts

Both must be clean before proceeding. linear-registration.test.ts imports the real channel barrel and asserts the registry contains linear. It goes red if the import './linear.js'; line is deleted or drifts, if the barrel fails to evaluate, or if @chat-adapter/linear isn't installed (the import throws) — so it also covers the dependency from step 3. End-to-end message delivery against a real Linear workspace is verified manually once the service is running — see Wiring and Next Steps.

Credentials

Linear app and webhook setup is human and interactive — these steps are prose (no parser can click through the Linear UI), except the final env write.

1. Set up a webhook

1. Go to Linear Settings > API > Webhooks > New webhook
2. Label: NanoClaw
3. URL: https://your-domain/webhook/linear (the shared webhook server, default port 3000)
4. Team: select the team you want to monitor
5. Events: check Comment
6. Save — copy the signing secret

Note: Linear webhook delivery may be delayed 1-5 minutes for new webhooks. This is normal.

2. Store the credentials

Capture the values, then write them. prompt only asks and binds the answer to a name; a separate directive consumes it. Here they go to .env (set-if-absent — a value you've already filled in is never overwritten) and sync to the container.

Use either the OAuth app credentials (recommended) or a Personal API key. For the API-key path, paste none at the OAuth prompts and set LINEAR_API_KEY in .env by hand (commented in the template below). LINEAR_BOT_USERNAME is the display name for the bot, used for self-message detection when using a Personal API Key. LINEAR_TEAM_KEY is the Linear team key (e.g. ENG, NAN) — find it in Linear under Settings > Teams; all issues in this team route to one messaging group.

Paste the OAuth Client ID — Linear Settings > API > OAuth Applications. Paste `none` if using a Personal API key instead.

Paste the OAuth Client Secret. Paste `none` if using a Personal API key instead.

Paste the webhook signing secret from the webhook you just created.

Enter the Linear team key (e.g. `ENG`, `NAN`) — Settings > Teams.

Enter the bot display name (e.g. `NanoClaw Bot`).

LINEAR_CLIENT_ID={{linear_client_id}}
LINEAR_CLIENT_SECRET={{linear_client_secret}}
LINEAR_WEBHOOK_SECRET={{linear_webhook_secret}}
LINEAR_TEAM_KEY={{linear_team_key}}
LINEAR_BOT_USERNAME={{linear_bot_username}}

If you went the Personal API key route, add this line to .env instead of the OAuth pair (agent posts as you, your own comments are filtered):

LINEAR_API_KEY=lin_api_...