Hermes Agent + Linear: AI Issue Triage and Sprint Execution Guide

hermes mcp install linear

hermes mcp configure linear

A Practical Linear Workflow: The Issue-to-Outcome Loop

The official documentation describes the useful pattern as an issue-to-outcome loop: Hermes reads a Linear issue, checks related files or pull requests, asks for missing details only when needed, implements or drafts the next step, and then updates the issue with exactly what changed and what still needs human review.

Bug Triage

For bug triage, Hermes can summarize the report, find the likely code path, reproduce if possible, and add a clear fix plan or pull request link. This requires the GitHub integration to be active so the agent can inspect the repository and create branches or pull requests.

Sprint Planning

For sprint planning, Hermes can group issues by risk, dependency, owner, and missing context before the planning meeting. The agent can read all open issues for a project, identify stale blockers, find issues with missing owners, and flag ambiguous acceptance criteria. This gives engineering managers a sprint-risk summary without manually reading every open issue.

Support Handoff

For support handoff, Hermes can turn a Telegram, Discord, email, or Slack thread into a Linear issue with reproduction steps and acceptance criteria. The documentation notes that founders who collect bugs in these channels can use Hermes to create clean Linear issues. This requires the relevant messaging channel integration to be connected separately.

Release Cleanup

For release cleanup, Hermes can scan open issues, find stale blockers, and draft the final "what shipped / what slipped" update. The agent can read all issues for a cycle or project, identify which ones are still open, check for blockers, and produce a summary report.

When to Use Linear Versus the Hermes Kanban Board

The official documentation provides clear guidance on when to use each system:

• Use Linear when humans need to own, prioritize, or discuss the issue later. Linear is best for team planning, product visibility, assignment, labels, priorities, projects, cycles, and reporting.
• Use Hermes Kanban for the agent's internal execution plan when a job needs multiple steps, subagents, dependencies, or progress comments. The Kanban board handles parent tasks, child tasks, specialist profiles, parallel work, and progress comments while the agent is running.
• You can use both. Linear tracks the official deliverable; Kanban tracks how Hermes decomposes and executes the work. The documentation recommends storing the Linear issue ID in the Hermes task title or notes when you want a stable cross-reference.

Routing Issue Types to Specialist Agents

Different Linear work should not all go to the same generic prompt. The official documentation describes how to use Hermes profiles and skills to keep behaviors separate while Linear stays the shared work queue:

• Bugs can load a code-focused profile with GitHub access.
• Documentation issues can load a writing profile with the docs repo and Notion context.
• QA issues can load browser and terminal tools.

Hermes profiles and skills let you keep those behaviors separate while Linear remains the shared work queue. This is an advanced pattern that requires defining multiple profiles and routing rules.

Safe Rollout Checklist

The official documentation provides a safe rollout checklist that treats Linear as production project data:

1. Install the catalog entry with hermes mcp install linear, then complete the browser OAuth flow if prompted.
2. Use hermes mcp configure linear to leave destructive or rarely needed tools disabled.
3. Run one read-only prompt such as "summarize my highest-priority Linear issues for this project."
4. Add write access only after confirming team, project, labels, and priority mapping are correct.
5. Pair with GitHub for pull-request work and Telegram/Slack/Discord for human-visible status reports.

The documentation emphasizes that Linear write access should be staged. Start by letting Hermes read and summarize. Then allow issue creation for low-risk workflows. Only later should it update statuses or post comments automatically, and even then the skill should define exactly when approval is required. This keeps the tracker trustworthy instead of turning it into an unreviewed bot log.

Human Approval Still Matters

The official documentation explicitly addresses the safety of letting an agent update Linear. It states that it can be safe if you stage permissions: read-only first, issue creation next, and status/comment updates only after your team defines clear conventions and approval points. The skill should define exactly when approval is required for each type of write action.

Common Setup Issues

The documentation lists several common setup issues and their solutions:

• No Linear tools show up. Run hermes mcp list and confirm the Linear catalog entry is installed and enabled. Start a fresh Hermes session after changing MCP configuration.
• OAuth opens but the agent still cannot read issues. Finish the browser authorization flow, then run hermes mcp test linear or reopen Hermes so the client reconnects.
• Hermes creates issues in the wrong place. Define the default Linear team, project, labels, and priority mapping in a skill or prompt template before enabling write-heavy workflows.

Troubleshooting

Based on the common setup issues documented in the official source, here is a troubleshooting guide:

Issue: No Linear tools appear after installation

Run hermes mcp list to confirm the Linear catalog entry is installed and enabled. If it is not listed, re-run hermes mcp install linear. If it is listed but still not working, start a fresh Hermes session. The documentation explicitly says to start a fresh session after changing MCP configuration.

Issue: OAuth flow completes but agent cannot read issues

Run hermes mcp test linear to verify the connection. If that does not work, reopen Hermes so the client reconnects. The documentation lists this as a separate step from the initial OAuth flow.

Issue: Issues created in the wrong project or team

Define the default Linear team, project, labels, and priority mapping in a skill or prompt template before enabling write-heavy workflows. The documentation warns that this is a common issue and that you should not enable write tools until these defaults are configured.

Issue: The optional demo video feels unrelated

The documentation includes a note that the video (Hermes Agent Just Became a Project Manager by Nemanja Mirkovic) is an optional Kanban/project-manager demo. The actual Linear setup uses the Linear MCP; the Kanban demo only explains how Hermes decomposes multi-step work. If you are only setting up Linear, you can skip the video.

Going Further

Once you have the basic Linear integration working, the official documentation suggests several next steps:

• Use Hermes with GitHub. Connect Linear issue work to branches, pull requests, reviews, and Actions failures. This is the most powerful extension of the Linear integration because it enables the full issue-to-outcome loop.
• Add tools to Hermes. Learn how MCP and tool selection expose external systems safely. The documentation links to a general guide on adding tools to Hermes.
• Consider Hermes pricing and managed cloud. Decide whether to self-host the integration or use managed FlyHermes uptime. The documentation links to a pricing page for this decision.
• Explore other integrations. The documentation mentions Telegram, Discord, Slack, WhatsApp, and Signal as additional integrations that can feed into the Linear workflow. Connecting these channels lets Hermes turn conversations into Linear issues.
• Review related setup guides. The documentation links to guides for GitHub, Jira, and Notion integrations, which can be combined with Linear for cross-platform workflows.