<p>Linear's official MCP server launched in May 2025. It lets the robots lean in on the
project management work. I want to get some ideation-bots going.</p>
<h2 id="supported-commands">Supported Commands</h2>
<table>
<thead>
<tr>
<th>Category</th>
<th>Commands</th>
</tr>
</thead>
<tbody>
<tr>
<td>Issues</td>
<td>list, get, create/update, status, statuses</td>
</tr>
<tr>
<td>Projects</td>
<td>list, get, create/update, labels</td>
</tr>
<tr>
<td>Documents</td>
<td>list, get, create, update, search</td>
</tr>
<tr>
<td>Comments</td>
<td>list, create/update, delete</td>
</tr>
<tr>
<td>Attachments</td>
<td>get, create, delete, extract images</td>
</tr>
<tr>
<td>Milestones</td>
<td>list, get, create/update</td>
</tr>
<tr>
<td>Cycles</td>
<td>list</td>
</tr>
<tr>
<td>Teams</td>
<td>list, get</td>
</tr>
<tr>
<td>Users</td>
<td>list, get</td>
</tr>
<tr>
<td>Labels</td>
<td>list issue labels, create issue label</td>
</tr>
</tbody>
</table>
<h2 id="setup">Setup</h2>
<p>Linear hosts the MCP server at <code>https://mcp.linear.app/mcp</code>. Use that endpoint, not the
old SSE one which is deprecated.</p>
<h3 id="claude-code">Claude Code</h3>
<pre><code class="language-bash">claude mcp add --transport http linear-server https://mcp.linear.app/mcp
</code></pre>
<p>Restart and authenticate via OAuth.</p>
<hr>
<h1 id="idea-nightly-ideation-engine">Idea: Nightly Ideation Engine</h1>
<p>Instead of using Linear as a human-operated task tracker, an AI agent can read youri
codebase, compare it against goals, and file suggestions directly.</p>
<p>What I'm hoping to build is a system where a scheduled agent runs nightly. It reads
blog posts, checks page speed, reviews SEO metadata, and compares everything against a
set of high-level goals:</p>
<ul>
<li>100% accurate content</li>
<li>Fast loading</li>
<li>Low cost</li>
<li>Looks good</li>
<li>Good SEO</li>
<li>Interesting tutorials about emerging tooling</li>
</ul>
<p>It should create Linear issues for anything worth improving, labeled "Suggestion" and
drop them into the Backlog.</p>
<h3 id="the-pipeline">The pipeline</h3>
<p>Linear's built-in statuses act as gates between human and agent
work.</p>
<pre class="mermaid">
stateDiagram-v2
    [*] --> Backlog: AI files suggestion
    Backlog --> Todo: Human promotes
    Backlog --> Canceled: Human rejects
    Todo --> InProgress: Agent picks up
    InProgress --> InReview: Agent finishes
    InReview --> Done: Human approves
    InReview --> InProgress: Human pushes back
</pre>
<p>Each step has a clear owner:</p>
<table>
<thead>
<tr>
<th>Status</th>
<th>Owner</th>
<th>What happens</th>
</tr>
</thead>
<tbody>
<tr>
<td>Backlog</td>
<td>AI</td>
<td>Nightly agent creates suggestion issues</td>
</tr>
<tr>
<td>Todo</td>
<td>Human</td>
<td>You move the good ones forward</td>
</tr>
<tr>
<td>In Progress</td>
<td>Agent</td>
<td>A working agent picks it up</td>
</tr>
<tr>
<td>In Review</td>
<td>Agent</td>
<td>Agent finishes, leaves a comment</td>
</tr>
<tr>
<td>Done</td>
<td>Human</td>
<td>You verify and close</td>
</tr>
<tr>
<td>Canceled</td>
<td>Human</td>
<td>Bad idea, toss it</td>
</tr>
</tbody>
</table>
<h3 id="agent-notes-via-comments">Agent notes via comments</h3>
<p>When agents work on an issue, they leave comments. This beats
internal context files because comments are visible, searchable,
and survive across sessions. If one agent starts a task and another
finishes it, the full history is right there on the issue.</p>
<p>I might also run multiple planning agents that each comment on a
ticket before I review it. A fact-checker, a SEO reviewer, and a
style auditor could all weigh in on the same Backlog issue. By the
time I look at it, there's already a thread of perspectives.</p>
<pre><code class="language-bash"># An agent checking for work:
# list_issues with label="Suggestion", state="Todo"

# An agent leaving notes:
# save_comment with issueId and markdown body
</code></pre>
<h3 id="filtering">Filtering</h3>
<p>The nightly agent queries existing Backlog suggestions before
creating new ones, avoiding duplicates. Working agents filter
by label and status to find their next task:</p>
<pre><code>list_issues → label: "Suggestion", state: "Todo"
</code></pre>
<h2 id="defining-state-as-prompts">Defining State as Prompts</h2>
<p>Linear's community Terraform provider exists but only covers teams,
labels, workflow states, and templates. No custom views. The GraphQL
API has a <code>customViewCreate</code> mutation, but nobody's wrapped it in
IaC tooling yet.</p>
<p>So instead of declaring views in HCL, I described mine as a prompt
and had Claude set it up via <a href="/playwright-mcp.html">Playwright MCP</a>:</p>
<blockquote>
<p>Create a custom view called "Suggestion Backlog" on the Pericak
team. Filter to issues where label includes "Suggestion" and
status is "Backlog". Description: "AI-generated improvement
suggestions awaiting human review".</p>
</blockquote>
<p>Claude navigated to Linear in Chromium, clicked "Add new view",
filled in the name, added both filters, and hit Save. The view
now lives as a tab on the team page.</p>
<p>This is nondeterministic state management. There's no lock file,
no plan/apply, no drift detection. But it works, and the prompt
is the documentation. If the view ever gets deleted, re-run the
prompt.</p>
<h3 id="a-linear-admin-agent">A Linear-Admin agent</h3>
<p>A "Linear-Admin" agent could own all workspace
configuration: views, labels, workflow states, notification
settings. You'd feed it a doc describing your desired workspace
setup, and it would use Playwright to converge Linear's UI to
match. Like Terraform, but with a browser instead of an API.</p>
<p>The tradeoffs are real. Playwright clicks are slow, brittle if
Linear redesigns their UI, and hard to make idempotent. But for
a personal workspace where the alternative is "click around in
the UI manually," the prompt-as-IaC approach is surprisingly
practical.</p>
<p>Still faster than a person.</p>


<p>I use Cursor and Claude Code, sometimes Codex, and I'm about to try OpenCode.
Each tool has its own rules format, and I've been maintaining them separately.
<a href="https://github.com/intellectronica/ruler">Ruler</a> generates each tool's native
config from a single source. Worth setting up.</p>
<h1 id="tool-agnosticism-with-common-rules">Tool agnosticism with common rules</h1>
<p>I'm trying to keep up. There are too many tools. I don't want to migrate things around.
We're using this at work too, since different devs use different tools. Here's how I
set up Ruler to consolidate my Cursor and Claude rules together.</p>
<p>I had this rule in Cursor:</p>
<pre><code class="language-markdown"># Monorepo rules

This git repo is a monorepo. It contains multiple sub-projects.
Do not look for context or cross-reference calls between sub-projects.
Each directory within apps/ and games/ is a sub-project. They shouldn't
share code.
</code></pre>
<p>Claude Code has CLAUDE.md files scattered through the tree:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Contents</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>CLAUDE.md</code> (root)</td>
<td>Branching: never commit to main, always PR</td>
</tr>
<tr>
<td><code>apps/games/sillyapp/CLAUDE.md</code></td>
<td>iOS build and test commands, simulator lifecycle</td>
</tr>
<tr>
<td><code>apps/blog/.../posts/CLAUDE.md</code></td>
<td>Blog writing voice, formatting rules, structure</td>
</tr>
<tr>
<td><code>apps/games/kid-bot-battle-sim/features/CLAUDE.md</code></td>
<td>Interface details for that feature set</td>
</tr>
</tbody>
</table>
<h1 id="ruler-setup">Ruler Setup</h1>
<pre><code class="language-bash">npm install -g @intellectronica/ruler
</code></pre>
<p>Initialize at the repo root:</p>
<pre><code class="language-bash">ruler init
</code></pre>
<p>This creates a <code>.ruler/</code> directory and a <code>ruler.toml</code> config. Drop your
instructions as Markdown files inside <code>.ruler/</code>, then:</p>
<pre><code class="language-bash">ruler apply
</code></pre>
<h2 id="what-happens-when-you-run-it">What happens when you run it</h2>
<p>Claude Code gets <code>CLAUDE.md</code>. Everything else (Cursor, OpenCode, Codex,
Copilot, 30+ others) gets <code>AGENTS.md</code>. Generated files go into <code>.gitignore</code>
automatically, so only the <code>.ruler/</code> source is committed.</p>
<p>Ruler supports nested directories. A <code>.ruler/</code> at the repo root applies
globally. A <code>.ruler/</code> inside a sub-project applies when an agent is working
there. That matches how Claude Code already loads CLAUDE.md files walking up
the directory tree.</p>
<pre class="mermaid">
graph TD
    A[".ruler/ at repo root\nbranching, monorepo"] --> B[Claude Code]
    A --> C[Everyone Else\nCursor, OpenCode, Codex...]
    E[".ruler/ in sillyapp/\nbuild, test"] --> B
    E --> C
    F[".ruler/ in posts/\nblog style"] --> B
    F --> C
    B --> G[CLAUDE.md]
    C --> H[AGENTS.md]
</pre>
<p>You can symlink ~/.ruler to your dir too if you want global Claude rules.</p>
<h1 id="note-consider-just-using-agentsmd">Note: Consider just using AGENTS.md</h1>
<p>Most tools read <code>AGENTS.md</code>: Cursor, OpenCode, Codex, <del>others</del>. If all you have is
rules, it's not a bad idea to skip all of this and just use that format. I think it
might win. That doesn't help with Skills, though.</p>
<p>Cursor also has a <a href="/wiki/ai-tools/cursor-cli.html">headless CLI agent</a> for running
agents from the terminal, similar to <code>claude -p</code> in Claude Code. Worth knowing
about if you're scripting workflows across tools.</p>
<h2 id="skills">Skills</h2>
<p>Rules are basically just fancy prompt context that are always loaded.
Skills are just fancy prompt context loaded on-demand, maybe with some extra files
sometimes. Different tools implement them in different ways:</p>
<ul>
<li>Claude Code: <code>.claude/skills/</code></li>
<li>Cursor: <code>.cursor/skills/</code></li>
<li>Other tools follow the same pattern under their own config directories</li>
</ul>
<p>Ruler figures it out and distributes them for you. Could this all just be a bash
script? Yes. Does it do a bunch of stuff I don't understand too? Also, probably, yes.</p>
<p>Enabled by default. Pass <code>--no-skills</code> to skip it:</p>
<pre><code class="language-bash">ruler apply           # distributes rules + skills
ruler apply --no-skills  # rules only
</code></pre>
<hr>
<h1 id="consolidating-rules-migration-steps">Consolidating rules: Migration steps</h1>
<p>The <code>ruler.toml</code> at the root lists the agents to target:</p>
<pre><code class="language-toml">default_agents = ["claude", "cursor"]
</code></pre>
<p>Content moves from existing config files into <code>.ruler/</code> source files:</p>
<pre><code>.ruler/
  branching.md        # from root CLAUDE.md
  monorepo.md         # from .cursor/rules/monorepo.md (Claude never saw this)
apps/games/sillyapp/
  .ruler/
    build.md          # from sillyapp/CLAUDE.md
apps/blog/blog/markdown/posts/
  .ruler/
    style.md          # from posts/CLAUDE.md
apps/games/kid-bot-battle-sim/features/
  .ruler/
    interfaces.md     # from features/CLAUDE.md
</code></pre>
<p>Root <code>.ruler/branching.md</code> (was only in Claude Code):</p>
<pre><code class="language-markdown"># Branching

Never commit directly to `main`. Always create a branch and open a PR
against main for review.
</code></pre>
<p>Root <code>.ruler/monorepo.md</code> (was only in Cursor):</p>
<pre><code class="language-markdown"># Monorepo

This repo contains multiple independent sub-projects under `apps/` and
`games/`. Do not cross-reference or import code between sub-projects.
Each directory in those folders is its own isolated project.
</code></pre>
<p>The project-specific files (sillyapp build commands, blog style guide)
move into <code>.ruler/</code> inside their directories unchanged. Content stays the
same, location shifts.</p>
<p>Note: the existing hand-written CLAUDE.md files get replaced by generated
versions after <code>ruler apply</code>. Edit the <code>.ruler/</code> source, not the output.</p>


Kyle Pericak

Linear MCP: Planning with Robots

Cross-Tool AI Rules with Ruler