# How to connect Linear to Hermes Agent (no API keys)

> Connect Linear to Hermes with ClawLink in one click — 32 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/linear

Most guides for giving Hermes Agent Linear access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Linear setup: pair once in the browser and your always-on Hermes agent can act on Linear for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Linear.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Linear** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect linear  # connect Linear (browser OAuth)
npx -y @useclawlink/cli actions linear  # list available actions
npx -y @useclawlink/cli run linear <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Linear in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Call linear_list_linear_teams to get a real team id, then linear_create_linear_issue with that team_id, title '\<title>', and description '\<description>'. Confirm the issue identifier it returns.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Linear is connected in the dashboard, that agent calls the same 32 Linear tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Linear MCP for Hermes

Looking for a Linear MCP server for Hermes Agent? ClawLink connects Linear to Hermes Agent and exposes 32 Linear tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Linear integration](https://claw-link.dev/openclaw/linear) works the same way.

The default answer for connecting Linear to Hermes Agent has changed, and this page has to name it: Hermes now ships `hermes mcp install linear`, which runs Linear's browser OAuth and updates your agent configuration for you. Google's AI Overview teaches that command first, and it is the right first answer for most users. ClawLink is the hosted alternative: the same browser OAuth, but the connection lives in the ClawLink dashboard, no config file on your machine, 32 tools ready for chat, and the same connected account works for OpenClaw if you run both agents. Choose the native command when you want Hermes to own the setup; choose ClawLink when you want the connection managed in one dashboard across agents.

## What the Hermes Agent Linear integration can do

32 Linear tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 32.

### 30 of 32 Linear tools for Hermes

| Tool | What it does |
|---|---|
| **Create attachment** `linear_create_attachment` | Creates a new attachment and associates it with a specific, existing Linear issue. |
| **Create comment reaction** `linear_create_comment_reaction` | Tool to add a reaction to an existing Linear comment. Use when you want to programmatically react to a comment on an issue. |
| **Create linear comment** `linear_create_linear_comment` | Creates a new comment on a specified Linear issue. This action modifies shared workspace data and is not reversible — confirm the target issue and comment content before executing. |
| **Create linear issue** `linear_create_linear_issue` | Creates a new issue in a specified Linear project and team, requiring team_id and title, and allowing optional properties like description, assignee, state, priority, cycle, and due date. |
| **Create linear issue relation** `linear_create_linear_issue_relation` | Create a relationship between two Linear issues using the issueRelationCreate mutation. Use this to establish connections like 'blocks', 'duplicate', or 'related' between issues. |
| **Create linear label** `linear_create_linear_label` | Creates a new label in Linear for a specified team, used to categorize and organize issues. Label names must be unique within each team. |
| **Create linear project** `linear_create_linear_project` | Creates a new Linear project with specified name and team associations. |
| **Create project milestone** `linear_create_project_milestone` | Tool to create a project milestone in Linear with a name and optional target date and sort order. Use when you need to add milestones to track progress within a project. |
| **Create project update** `linear_create_project_update` | Tool to create a project status update post for a Linear project. Use when you need to post progress updates, status reports, or announcements for a project. |
| **Get attachment** `linear_get_attachment` | Downloads a specific attachment from a Linear issue; the `file_name` must include the correct file extension. |
| **Get current user** `linear_get_current_user` | Gets the currently authenticated user's ID, name, email, and other profile information — this is the account behind the API token, which may be a bot or service account rather than a human user. |
| **Get cycles by team ID** `linear_get_cycles_by_team_id` | Retrieves all cycles for a specified Linear team ID; cycles are time-boxed work periods (like |
| **Get issue defaults** `linear_get_issue_defaults` | Fetches a Linear team's default issue estimate and state, useful for pre-filling new issue forms |
| **Get linear issue** `linear_get_linear_issue` | Retrieves an existing Linear issue's comprehensive details, including id, identifier, title |
| **Get linear project** `linear_get_linear_project` | Retrieves a single Linear project by its unique identifier |
| **List issue drafts** `linear_list_issue_drafts` | List issue drafts |
| **List issues by team ID** `linear_list_issues_by_team_id` | List all issues for a specific Linear team, scoped by team ID |
| **List linear cycles** `linear_list_linear_cycles` | Retrieves all cycles (time-boxed sprint iterations) org-wide from the Linear account; no |
| **List linear issues** `linear_list_linear_issues` | Lists non-archived Linear issues; if project_id is not specified, issues from all accessible |
| **List linear labels** `linear_list_linear_labels` | Retrieves labels from Linear |
| **List linear projects** `linear_list_linear_projects` | Retrieves all projects from the Linear account |
| **List linear states** `linear_list_linear_states` | Retrieves all workflow states for a specified team in Linear, representing the stages an issue |
| **List linear teams** `linear_list_linear_teams` | Retrieves all teams with their members and projects |
| **List linear users** `linear_list_linear_users` | Lists all workspace users (not team-scoped) with their IDs, names, emails, and active status |
| **Search issues** `linear_search_issues` | Search Linear issues using full-text search across identifier, title, and description |
| **Update issue** `linear_update_issue` | Updates an existing Linear issue using its `issue_id`; requires at least one other attribute |
| **Update linear comment** `linear_update_linear_comment` | Update an existing Linear comment's body text |
| **Update linear project** `linear_update_linear_project` | Update an existing Linear project |
| **Remove issue label** `linear_remove_issue_label` | Removes a specified label from an existing Linear issue using their IDs; successful even if the |
| **Remove reaction** `linear_remove_reaction` | Remove a reaction on a comment |

## Example prompts

**Create an issue in a team**

> Call linear_list_linear_teams to get a real team id, then linear_create_linear_issue with that team_id, title '\<title>', and description '\<description>'. Confirm the issue identifier it returns.

**List my open issues**

> Use linear_list_linear_issues with assignee_id set to the result of linear_get_current_user, then group the issues by state and tell me what is due this week.

**Search issues and update one**

> Search Linear with linear_search_issues for '\<query>', pick the most relevant issue, then linear_update_issue to set its priority to high using the issue_id from the search results.

## How the Linear tools take their arguments

Verified against the live tool schemas; Linear's team-scoped model is where argument errors come from.

- **Issue creation requires a team.** `linear_create_linear_issue` takes `team_id` and `title` as required arguments; cycle, priority, state, assignee, labels, parent, and due date are all optional.
- **List tools differ by scope.** `linear_list_linear_issues` with no `project_id` returns issues from all accessible projects, while `linear_list_issues_by_team_id` stays inside one team. `linear_list_linear_cycles` is org-wide, `linear_get_cycles_by_team_id` is not.
- **`linear_get_current_user` identifies 'me'.** Its schema says to use it to identify the current user in operations that take a user id, which is the correct first call before filtering issues by assignee.
- **Search is full-text.** `linear_search_issues` searches identifier, title, and description, so it finds issues by identifier like `ENG-123` as well as by words.

## ClawLink vs. building it yourself

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.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Linear app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Linear through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Linear. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Linear actions to the runtime in a format your agent can reliably use. | 32 tools for Linear are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Linear to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Linear in the browser, and the 32 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Linear
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`.

### Connection succeeds but no tools appear
Reconnect Linear from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Linear tools
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.

### Linear returns 403 or "permission denied" on one action while others work
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 API 403 insufficient permissions
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:

```text
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.
```

### Linear API rate limit
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.

### Linear MCP tool not found
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.

### OAuth finished in the browser but the account is still missing
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.

### Is there a Hermes Agent Linear integration?
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.

### How do I connect Linear to Hermes with ClawLink?
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.

### How long does it take to connect Linear to Hermes Agent?
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.

### Why use ClawLink instead of wiring Linear up myself?
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.

### Should I use `hermes mcp install linear` instead?
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.

### Do I need a Linear API key or personal access token?
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.

### Is it safe to connect Linear to an AI agent?
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.

### Hermes paired but still can't use Linear
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`.

## Related

- [Hermes SafetyCulture integration](https://claw-link.dev/hermes/safetyculture) — SafetyCulture (formerly iAuditor) is a workplace operations platform that enables teams to conduct digital inspections, manage audits, track issues, schedule tasks, and maintain compliance through mobile and web applications.
- [Connect LaunchDarkly](https://claw-link.dev/hermes/launch-darkly) — A feature management platform that helps teams build better software faster using feature flags.
- [Crowdin](https://claw-link.dev/hermes/crowdin) — Manage translations, localization projects, and language resources