How to connect Linear to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Linear from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Linear tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Linear call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

Linear's 403s are scope-shaped, and the mechanics matter. OAuth apps carry Linear scopes: read, write, issues:create, and admin. A connection approved before a scope was added does not get it retroactively, so after changing permissions, reconnect so the new scope is granted. A personal key acts with its owner's authority, and an API key created with 'All teams' scoping can fail against a team outside that scope; the OAuth equivalent is an account that is not a member of the team in the request. And the usual ClawLink-specific cause still applies: the agent passed a placeholder id like YOUR_ID or an example team_id from docs. Run linear_list_linear_teams first, then retry with the real team id from the result.

Ask the agent to diagnose it:

Call linear_get_current_user and linear_list_linear_teams, tell me which teams the connection can see, then retry the failing call once and quote the exact error body.

Verified against Linear's own rate-limiting docs on 2026-08-02, because the numbers circulating in AI answers are stale or wrong. OAuth-app requests are limited to 5,000 per hour per user, with a complexity budget of 2,000,000 points per hour. Errors come back as HTTP 400 with a RATELIMITED code inside the GraphQL errors array, not as HTTP 429, which makes them easy to mistake for bad requests. The response includes X-RateLimit-Requests-* and X-RateLimit-Complexity-* headers with the reset time. When an agent hits this, the fix is to wait for the window and retry, and to stop polling: Linear's docs specifically discourage polling and recommend webhooks and filtering instead.

Search engines answer this error in Cursor and Claude Code terms: wipe the npx cache, delete mcp.json, avoid hyphens in server names, use the mcp-remote https://mcp.linear.app/sse config block. All of that is for people running their own MCP servers, and Linear's official hosted server lives at mcp.linear.app. On the ClawLink hosted flow the analogous error is 'Tool schema not loaded yet': schemas load on demand the first time a tool runs and are cached after that, so the error clears on retry within seconds. If every Linear call keeps failing with it in a fresh chat, reconnect from the dashboard; a persistent pattern points to a config problem on our side, not a file on your machine.

Try reconnecting Linear and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Linear: link your Linear account once in the browser and Hermes Agent can call the Linear API through 32 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Linear in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Linear in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Linear working from chat.

If you run Hermes Agent and only need Linear from it, the native command is the simplest path and this page is not going to argue with it. hermes mcp install linear runs browser OAuth and writes the server config into Hermes's own configuration. What ClawLink adds is a hosted connection instead of a local one: the token is stored server-side and refreshed for you, there is no config file to maintain, the connection is managed from the ClawLink dashboard, and the same account works for OpenClaw alongside Hermes. For a single agent on a single machine, the native CLI does the job. For a connection you want to manage centrally, ClawLink is the hosted version of the same flow.

No. Both the native hermes mcp install linear command and the ClawLink hosted flow use Linear's OAuth, so you sign in to Linear in the browser once and never generate a personal API key. The manual route engines still teach, creating an API key and using it with a third-party MCP server, is the path this page and the native CLI both replace. Linear's own docs note that API-key requests are limited to 2,500 per hour per user while OAuth-app requests get 5,000, which is a separate reason the hosted and native OAuth routes beat the key route.

The answers both engines give to this query settle on least privilege: connect with scoped permissions, prefer read-only defaults, and gate writes. The ClawLink connection uses Linear's OAuth scopes and acts as your account, so the same rules apply: the agent can do what the connected account can do, including every issues:create call if that scope is granted. Set the agent's own permission rules to match what you want done, and revoke the connection from the ClawLink dashboard at any time, after which Linear rejects further calls.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.